About

Orka Cluster is an enterprise virtualization cloud solution for Mac build- infrastructures. Using the power of Kubernetes native technology. Orka enables user to orchestrate macOS workloads in a cloud-agnostic enhanced environment using Kubernetes on genuine Apple hardware.

• Orka = Orchestration with Kubernetes on Apple
• Cluster = A group of nodes that represents an Orka environment, which is hosted in a MacStadium data center and sits behind a Cisco firewall. (To reach it, there must be an active VPN connection.)

Overview

Every Orka user has unique use cases and requirements. Whether looking to run single Xcode builds or create an automated CI/CD pipeline with daily and nightly builds, the Orka journey goes through the a few simple steps (shown below).

Getting Started

1. Contact MacStadium

Contact MacStadium to discuss requirements. Based on specific use cases, the team recommends and provides the best hardware options.

2. Choose Tools

• The Orka Web UI provides a quick and user-friendly way to manage an Orka cluster. Currently, the Web UI offers limited functionality compared to the Orka3 CLI and the Orka3 API.
• The Orka 3.2 CLI is the easiest way to start with Orka. It is perfect for both manual use and automation alike.
• To build an automated CI/CD system, look into the available Orka integrations - from Jenkins to Drone, the Orka team continuously adds to the list of supported solutions.

3. Learn Orka Terminology

4. Add a User

1. Make sure the added as a user to the MacStadium Customer Portal account for the cluster.

2. Connect to your cluster via VPN. Ensure there is an up-and-running VPN connection when working with Orka.

   1. Get the IP Plan.
   2. Get a VPN client and use it to connect to the cluster using the firewall IP and credentials obtained in the previous step.
   3. Keep the VPN connection to the cluster live.

3. Configure the environment. This step is a one-time effort.

   • In the Orka3 CLI, run orka3 config set --api-url <ORKA_API_URL>.
   • For Orka3 API calls, target the Orka API endpoint or use the Swagger UI at <ORKA_API_URL>/api/v1/swagger.
   • For the Orka Web UI, go to <ORKA_API_URL> in the browser.
   • For CI/CD integrations, configure Orka API URL as prompted during the setup.

📘

What is the Orka API URL?

For an Orka Enterprise user, the Orka API URL is available from the IP Plan:

• For clusters deployed before Orka 2.1, it is the .100 address for the Private-1 network (usually, 10.221.188.100), prefixed with http. For example: http://10.221.188.100.
• For clusters deployed with Orka 2.1 or later, it is the .20 address for your Private-1 network (usually 10.221.188.20). prefixed with http. For example: http://10.221.188.20.
• It is possible to use https://<orka-domain> and https://<custom-domain>(if configured). To get the Orka domain for the Orka cluster, contact MacStadium. To use an external custom domain, see here.

Use http://<orka-IP>, https://<orka-domain>, and https://<custom-domain> interchangeably in workflows.

3. To use the Orka3 CLI, log in to the cluster and obtain an authentication token.
   The token authenticates uniquely with Orka. This operation stores a token locally at ~/.kube/config file.

   Shell

   orka3 login
   

   When prompted, provide the MacStadium Customer Portal credentials in the login form in the browser.

4. To use the Orka3 API, provide the Authorization: Bearer <TOKEN> header in the API calls or authorize the Swagger UI at <ORKA_API_URL>/api/v1/swagger. Use the authentication token.
   In the Orka3 CLI, obtain a token by running:

   Shell

   orka3 user get-token
   

5. To use the Orka Web UI, log in with an authentication token.
   In the Orka3 CLI, obtain a token by running:

   Shell

   orka3 user get-token
   

6. For CI/CD integrations, authenticate is based on the integration version.

   • If running a 2.x-compatible version, continue using your old user and password.
   • If you are running a 3.0.0-compatible version, authenticate with a dedicated service account.

🚧

WARNING

The first time a user creates a new Orka VM, a new interface called bridge 100 is configured and assigned a private IPv4 address, which is used for MacStadium Admins and management purposes. The network range used by Orka falls within 192.168.0.0/16. Users who also utilize this private IP range within their network may experience address conflict within the MacStadium VPN. Currently, Orka does not support changing the management and administration of the IPv4 network address range used. A workaround for this situation is to employ Network Address Translation (NAT), which avoids IP address conflicts within 192.168.0.0/16.

5. Deploying VMs

To deploy a VM, an image is required. Check what images are available locally in the cluster. Check out the remote and pull an image if the local image list is empty, or use an image from an OCI-compatible registry. Check https://github.com/macstadium/orka-images for the latest available OCI-compatible images provided by MacStadium. The images available out-of-the-box provide a pre-configured disk size and a pre-installed OS.

(Intel-only) To use a different disk size or prefer to install an OS yourself, go to the ISO way. Create an empty image of sufficient size and attach an ISO to your VM.

2. Working with VMs.

Connect to the VMs via VNC, SSH, or Apple Screen Sharing. Once connected, change the VM by installing extra software, enabling OS features, and others. For more information, see VNC, SSH, and Screen Sharing for Orka VMs.

To preserve the changes from one VM and deploy new VMs with these exact changes. Save or commit the changes, or push them to a remote OCI-compatible registry, to preserve and make them available for future configs and deployments.

3. (Optional) Delete unused VMs.

Next Steps

Choose how to get started with Orka.