Orka Cluster 3.2 Introduction

About

Orka Cluster is an enterprise virtualization and orchestration solution designed for macOS. It provides two classes of capabilities:

• Virtualization (optimized for Apple Silicon and macOS, with Apple Hypervisor interface)
• Orchestration (designed for scalability, speed, and reliability, with native K8S-based scheduling)

Orka Cluster 3.2 is deployed to the MacStadium Cloud. Users typically run integrations to CI (continuous integration) systems such as Jenkins, GitHub Actions, GitLab, BuildKite, or a custom systems, and use that to manage build/test workloads that execute on macOS, such as iOS apps.

Overview

Orka Cluster can be purchased by meeting with MacStadium Sales and Field Engineering teams. The MacStadium team works with users to size and fit the Orka Cluster deployment.

A deployment typically consists of:

• A control plane that facilitates the orchestration activities, including provisioning and de-provisioning of VMs across hosts running virtualization interfaces to macOS compute resources.
• A fleet of MacStadium Bare Metal Mac hosts running virtualization interfaces to macOS compute resources.
• An image repository to store and distribute the images to the fleet, where they are used as VMs.

An Orka Cluster can start with as little as two nodes and can scale to hundreds of nodes if needed. The MacStadium team can assist in confirming the size and scaling.

Key Concepts

• The Orka 3.2 CLI (orka3) is the primary interface to working with Orka Cluster. It is perfect for both manual use and automation.
• To build an automated CI/CD system, look into the available Orka integrations - from Jenkins to GitHub Actions. The Orka team continuously adds to the list of supported solutions.
• 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.

🗒️

NOTE

The Orka Cluster may be behind a firewall and may require a VPN to access. Details are provided in the Portal.

Terminology

• Bare Metal Macs: MacStadium has a variety of standard Mac models that run the virtualization software to manage and use the macOS compute resources
• Control Plane: Facilitates the orchestration activities, which includes provisioning and de-provisioning of VMs across the fleet of hosts that are running virtualization interfaces to macOS compute resources. This runs natively inside of Kubernetes for optimal performance and scale. (This is abstracted away from users, so they never need to interface with K8S, unless they want to.)
• Host (or Node): A physical computer with a host macOS and an installation of Orka the Orka Cluster Virtualization software
• Image (or OCI Image): Bits on disk that represent VM storage. Images can be deployed as a VM in an Orka Cluster and provide the OS, file system, and built in storage are used by the VM.
  • OCI refers to the standard format that the image is packaged with. Images are stored in any OCI-compliant registry. Starting with Orka 3.2, MacStadium has begun storing OCI compliant images for various versions of the macOS in our public GitHub registry viewable at GitHub - macstadium/orka-images: Public images for Apple silicon-based Orka virtual machines
• A VM is a virtual machine runtime on top of the macOS host. The VM runs a guest OS image and macOS supports up to 2 running VMs per host.

Getting Started

The following steps and commands quickly introduce the basic features of Orka Cluster:

1. First-time setup:

• Review the IP Plan and configure networking access
• Install and configure the orka3 client with the api-url
• Manage users via the Portal

2. Run orka3 login and orka3 user get-token to sign into the cluster control plane
3. Learn the 3 main objects to work with: nodes, images, and vms
4. Deploy and Connect to a New VM
5. Modify, Save, and Stop the VM
6. Manage Image Caching behaviors

🗒️

NEXT STEPS

Take the customized VM and integrate it with a CI tool.

1. First Time Setup

Review IP Plan and Setup Networking

1. Login to the account on portal.macstadium.com and get the IP Plan.

• Use the <ORKA_API_URL> with the Firewall / VPN information to connect to the Orka Cluster outside the Portal.
• Use the .20 address for the Private-1 network (usually 10.221.188.20). prefixed with http. For example: http://10.221.188.20.

2. Connect to the Cluster via a VPN or other mesh network. Ensure the network connection is up-and-running from your calling application (that is, a local laptop with orka3 client, or CI system that execute builds) when working with Orka.

• MacStadium currently provides VPN based access. Use a VPN client to connect to the cluster using the firewall IP and credentials obtained from the IP Plan.
• MacStadium supports customers who wish to bring their own mesh networks or other tools.

3. Keep the VPN connection to the cluster live.

Install and Configure orka3 CLI

1. Visit the links below to download and install the orka3 CLI binary for the local environment.

• Orka Cluster 3.2 Release Notes

2. Configure the local orka3 environment with the appropriate ORKA_API_URL so the CLI knows where to connect. This step is a one-time effort.

• In the Orka3 CLI, run orka3 config set --api-url <ORKA_API_URL>.

🗒️

NOTE

Invite users in the Portal via the Users->Add New Users flow.

2. Run orka3 Login to Sign into the Cluster Control Plane

orka3 is the CLI to interface with the Orka Cluster. Once connected to the VPN or mesh network, login and retrieve a token that can be used for subsequent interactions.

1. Use the orka3 CLI to login. The below command opens a web browser to support authentication with the MacStadium Customer Portal credentials.

orka3 login

2. Obtain a token by running the following command to login to the cluster and obtain an authentication token. The token authenticates uniquely with Orka. This operation stores a token locally at ~/.kube/config file.

orka3 user get-token

3. Optional - 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.
4. Optional - For CI/CD integrations, authenticate with a dedicated service account.

3. Learn the 3 Main Objects

Nodes, images, and VMs

• Use orka3 nodes list to see a list of nodes or hosts in the cluster. Use the -o wide option to see more information about the nodes
• Use orka3 images list to see information about the images available to the cluster for running as VMs
• Use orka3 vm list to see information about the current VMs running in the cluster

4. Deploy and Connect to a New VM

• Launch a VM from a base image, including options to load from the OCI registry.
• For legacy users, there is a demonstrated loading from an NFS mount.
• Access the VM via SSH, VNC, or Apple Screen Sharing.

🗒️

NOTE

To deploy a VM, an image is required. Check the MacStadium registry on ghcr.io 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.

5. Modify, Save, and Stop the VM

• Install dependencies or configure the environment for CI builds.
• Once customized, save the VM configuration as a new image for future use.

6. Manage Image Caches

Manage images stored on Orka Cluster nodes. By adding images to a node before deployment of a VM using that base image, DevOps and engineering staff can manage and control the delay caused by remote or even local cluster storage image pulls providing consistent deployment times.

Next Steps - Integrate with CI tooling

See Orka Cluster 3.2 Integrations