Overview Orka Cluster 3.2
Orka offers a seamless and consistent user experience that caters to various use cases and requirements.
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
Тerm | Definition |
---|---|
Node | A genuine Apple physical host that provides computational resources (RAM and CPU) for workloads. A host OS runs on top, with no direct access (via VNC, SSH, or Screen Sharing). |
VM config Also: VM template | A template for an Orka virtual machine. Deploy multiple VM instances (VMs) from a single VM config. Starting with Orka 3.0.0 using VM configs is optional. |
VM Also: VM instance | VMs take up resources from nodes and require a certain amount of CPU and memory. |
Image Related: base image, empty image | A disk image that represents VM storage. Base images are bootable disk images that provide the OS, file system, and storage for the VM configs and VMs. Empty images provide added storage or serve as the base image during manual OS installs from ISO. |
ISO | (Intel-only) A disk image used exclusively to install macOS on a virtual machine. |
4. Add a User
-
Make sure the added as a user to the MacStadium Customer Portal account for the cluster.
-
Connect to your cluster via VPN. Ensure there is an up-and-running VPN connection when working with Orka.
- Get the IP Plan.
- Get a VPN client and use it to connect to the cluster using the firewall IP and credentials obtained in the previous step.
- Keep the VPN connection to the cluster live.
-
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.
- In the Orka3 CLI, run
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 thePrivate-1
network (usually,10.221.188.100
), prefixed withhttp
. For example:http://10.221.188.100
.- For clusters deployed with Orka 2.1 or later, it is the
.20
address for yourPrivate-1
network (usually10.221.188.20
). prefixed withhttp
. For example:http://10.221.188.20
.- It is possible to use
https://<orka-domain>
andhttps://<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>
, andhttps://<custom-domain>
interchangeably in workflows.
-
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.orka3 login
When prompted, provide the MacStadium Customer Portal credentials in the login form in the browser.
-
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:orka3 user get-token
-
To use the Orka Web UI, log in with an authentication token.
In the Orka3 CLI, obtain a token by running:orka3 user get-token
-
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.
- 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.
- (Optional) Delete unused VMs.
Next Steps
Choose how to get started with Orka.
Updated 23 days ago