CI/CD Integrations Quick Start

🚧

Quick navigation

Time to read: 4 minutes, 23 seconds

Jump to: 1. Before you begin | 2. Some Orka CI/CD basics | 3. Pick your CI/CD integration | 4. Create a user & get a token | 5. Create the template for your permanent or ephemeral agent | 6. Complete the CI/CD setup

🚧

The ultimate quick start

If you want to skip the detailed explanations, just run through these steps on your own:

1. Review the list of available integrations at Orka Tools & Integrations and choose the one you want to use.
2. Create an Orka user and get a token with the API.
3. List the available VMs and images with the API.
4. Create an SSH-enabled VM config for your workflow with the API.
5. Complete the CI/CD integration setup as per its instructions.

Orka provides many integrations and plugins to set up a CI/CD pipeline with your preferred service provider. You can also build an in-house CI/CD integration with the Orka API. This page focuses on the ready CI/CD solutions for Orka.

The Orka CI/CD integrations will be most useful to:

• users with basic Orka knowledge and basic or advanced knowledge about their preferred CI/CD provider
• users with workflows that require automation

1. Before you begin

1. Get your IP Plan. You can download it from the MacStadium portal.
2. Connect to your Orka cluster via VPN.
   1. Download and install a VPN client. Note that if you're using an Orka domain or an external custom domain, you might need to make some additional configuration changes.
   2. Use the server address and credentials from the VPN section of your IP Plan.

2. Some Orka CI/CD basics

• CI/CD integrations must target your Orka API endpoint via IP, Orka domain, or external custom domain. If you are using an Orka domain or an external custom domain, you must ensure that the CI/CD integration can resolve the domain.

📘

What's your Orka endpoint?

You can get the IP for your Orka endpoint from your IP Plan:

• For clusters deployed before Orka 2.1, it's the .100 address for your Private-1 network (usually, 10.221.188.100).
• For clusters deployed with Orka 2.1 or later, it's the .20 address for your Private-1 network (usually 10.221.188.20).
  You need to use http with the IP.

To get the Orka domain for your Orka cluster, contact MacStadium. To use an external custom domain, see here.

Note that you can use http://<orka-IP>, https://<orka-domain>, and https://<custom-domain> interchangeably in your workflows.

• Most CI/CD integrations rely on SSH to connect to the VM where your builds run.
• Most CI/CD integrations provide both permanent and ephemeral build agents.

📘

Glossary: Permanent build agent

A running VM that persists between the iterations of your CI/CD pipeline. This VM is never destroyed, and the CI/CD pipeline reuses it on every run.

📘

Glossary: Ephemeral build agent

A new VM that spins up and lives for the duration of the CI/CD pipeline iteration. After the iteration is complete, the VM is destroyed.

3. Pick your CI/CD integration

Go to Orka Tools & Integrations and review the latest list of available integrations. Pick the one you want to use and navigate to its detailed setup instructions (usually available in the respective repo or official integration page).

4. Create a user & get a token

Orka requires you to create a dedicated Orka user for your cluster. This operation also creates a dedicated namespace in the cluster. You are the owner of this namespace. When you create a VM config and/or deploy a VM instance from it, they become associated with your namespace. Other users will not be able to manage your VM configs and your VMs and vice versa. Administrators will be able to list, delete, and purge your VM configs and instances.

📘

IMPORTANT

All sample API calls from this point use generic placeholder values.
Change the Orka API endpoint (10.221.188.100, 10.221.188.20, your Orka domain, or your external custom domain), the token, the license key, and any other placeholders as needed to reflect your environment.

All sample responses went through a JSON formatting service. Your responses might be formatted differently.

1. In your preferred command-line tool, run the following command:

curl --location --request POST 'http://<orka-api-ip>/users' \
--header 'Content-Type: application/json' \
--header 'orka-licensekey: myLicenseKey' \
--data-raw '{
	"password": "123456",
	"email": "[email protected]"
}'

{
   "message":"",
   "help":{},
   "errors":[],
   "email":"[email protected]"
}

This call creates a user in the Orka database. However, it does not log you in, and it does not return a token in the response. Tokens are used in almost all Orka operations to identify you with the service.

2. Get a token for the newly created user. You will not need this token for the actual CI/CD integration. You will need it to complete the Orka side of the requirements.

curl --location --request POST 'http://<orka-api-ip>/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[email protected]",
    "password": "123456"
}'

{
   "message":"",
   "help":{},
   "errors":[],
   "token":"eyJh..."
}

Grab the token from the response and use it for operations that require you to pass the Authorization: Bearer <token> header.

5. Create the template for your permanent or ephemeral agent

1. Check if there are any VM configs or VMs on your environment.

curl --location --request GET 'http://<orka-api-ip>/resources/vm/list' \
--header 'Authorization: Bearer eyJh...'

If this is the first time you're using Orka, you will get an empty response for virtual_machine_resources.

{
   "message":"",
   "help":{},
   "errors":[],
   "virtual_machine_resources":[]
}

This API call lists the VM configs and VM instances associated with your user. You will never see the VMs of other users.

👍

Do you want to see all VMs on the environment?

Run:

cURL

curl --location --request GET 'http://<orka-api-ip>/resources/vm/list/all' \
--header 'Authorization: Bearer eyJh...' \
--header 'orka-licensekey: myLicenseKey'

Note that this is an administrative operation and requires you to pass a valid Orka license key.

2. List the available base images that you can use to create a VM config.

curl --location --request GET 'http://<orka-api-ip>/resources/image/list' \
--header 'Authorization: Bearer eyJh...'

You will likely see a 90GBVenturaSSH.orkasi item in the response. It is a fully installed and configured macOS Ventura image with a 90GB disk size. It also has an admin user configured and SSH and Apple Screen Sharing access enabled.

📘

Glossary: Image

A disk image that represents VM storage. Base images are bootable disk images that provide the OS, file system, and storage for your VM configs and VMs. Empty images provide added storage or serve as the base image during manual OS installs from ISO.

3. Create your first VM config:

curl --location --request POST 'http://<orka-api-ip>/resources/vm/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh...' \
--data-raw '{
	"orka_vm_name": "myorkavm",
	"orka_base_image": "90GBVenturaSSH.orkasi",
	"orka_image": "myorkavm",
	"orka_cpu_core": 6,
	"vcpu_count": 6
}'

As a bare minimum, you need to pass the following data in the body of the request:

• orka_vm_name: Set any user-friendly name that will help you recognize the VM config and the instances deployed from it.
• orka_base_image: Set to 90GBVenturaSSH.orkasi.
• orka_image: Set to the same name you provided for orka_vm_name.
• orka_cpu_core: Set to 6. This is the number of CPUs for the VM.
• vcpu_count: Set to 6. Unless CPU is 3, it must be half of or the exact amount of CPUs. This setting indicates if hyperthreading is enabled. If vCPU equals CPU, hyperthreading is on.

📘

VM name limitations

The name you specify under VM Name must meet the following requirements:

• Doesn't exceed 38 characters.
• Contains only lowercase Latin alphanumeric characters (0-9, a-z) and dashes (-).
• Begins and ends with an alphanumeric character.

This call creates a VM config.

{
   "message":"Successfully Created",
   "help":{
      "deploy_virtual_machine":"To deploy a VM, make sure you have a configuration created and use the endpoint http://<orka-api-ip>/resources/vm/deploy",
      "required_request_data_for_deploy":{
         "orka_vm_name":"myorkavm",
         "orka_node_name":"<ORKA_NODE_NAME>"
      }
   },
   "errors":[]
}

📘

Glossary: VM config

A template for an Orka virtual machine. You can deploy multiple VM instances (VMs) from a single VM config.

Your CI/CD pipeline will use this SSH-enabled VM config (template) to spin up permanent or ephemeral agents. Every agent is a deployed VM instance of a VM config.

📘

Glossary: VM instance (VM)

A deployed instance of a VM config. VMs take up resources from your nodes and require a certain amount of CPU and RAM to run.

📘

Are you not using the 90GBVenturaSSH.orkasi image?

If you're using another image as your starting point or if you are installing your OS from ISO, you will likely not have SSH or Screen Sharing enabled by default (even though the respective ports will be mapped by default). In this case, you need to connect to the VM via VNC. You can then enable SSH and Screen Sharing connectivity in the OS.

6. Complete the CI/CD setup

Revisit the setup instructions for your preferred Orka CI/CD integration. Fill in any configuration fields as needed.

Note that you might need to provide the SSH credentials for the VM.

👍

What are the credentials for my VM config?

By default, the 90GBVenturaSSH.orkasi image is configured with an admin/admin set of credentials.

What's next

You're ready to explore Orka on your own. You might find the following resources helpful:

• If you need to create more VM configs and customize them, see Quick Start with the Orka CLI and Quick Start with the Orka API.
• Explore Orka Docs for more advanced tasks and tutorials.
• Seek help from the Orka community in the MacStadium Community Slack.
• Get support in the MacStadium portal.
• Is a feature missing? Please share your feedback with us.