Image Management in Orka for macOS and iOS CI

Managing Mac VM images is simple with Orka. Learn about image storage, and walk through a sample workflow with the Orka CLI.

When executing iOS or macOS CI at scale, you will likely need to provision a large number of macOS build agents. This action can commonly take two forms. Teams can either provision a bank of compute resources simultaneously and leave them waiting for jobs, as you would find in a hybrid CI pipeline, or they can build the CI pipeline such that a new Mac VM is stood up and provisioned as a preliminary stage in the CI pipeline itself, as you will find in an ephemeral CI pipeline’s architecture.

MacStadium’s Orka, a unique, enterprise-ready macOS virtualization platform built on Kubernetes and Docker, supports both of these approaches very effectively.

Whichever approach your team settles on, the most efficient way to spin up identical Mac VMs is by pre-building a “golden image” that defines your desired build environment. With a golden image at the ready, teams can simply and reliably recreate the exact same build environment in Orka time and again with very little effort or technical overhead.

Storing macOS Images in Orka

There are two locations from which you can access images/ISOs in Orka, either local or remote storage. Remote storage offers Orka users read-only access to a shared storage solution where MacStadium makes macOS base images available to all Orka users.

The local storage option for Orka is local to your Orka cluster, and it offers users both read and write privileges. Local storage in Orka is a private storage solution that users can pull or upload macOS images/ISOs into. Moreover, this local storage solution affords users the opportunity to safely make any changes to a given base image that they like, such as installing build tools or otherwise modifying the build environment and then saving the modified image for future use. This act of saving a modified image is how you will create the golden image that you will ultimately use to spin up your build agents in Orka.

Using the Orka CLI to Manage macOS Images

Now, we’ll walk through a basic workflow that will demonstrate how you can use the resources described above to create a unique macOS image based on the Big Sur OS.

To list available images in the remote Orka storage, you can run the following:

orka image list-remote
  │       images       │
  │ 90GBigSurSSH.img   │
  │ 90GCatalinaSSH.img │
  │ Mojave-Clean.img   │
  │ Test.img           │

To pull a Big Sur image with SSH enabled from the remote storage to your local storage, run:

orka image pull
    Image name to pull: 90GBigSurSSH.img     Successfully copied image.
    New name for image

To save a copy of a modified base image, first, start a VM based on the image you’d like to modify by running:

orka vm create
                   VM Name: example
                Base image: 90GBigSurSSH.img
       CPU (3,4,6,8,12,24): 3
                      VCPU: 3                   Must equal CPU when <= 3
               Deploy Node:
             [Attach Disk]:
  VNC Console Enable (Y/n): y

Create Status: Successfully Created
Deploy Status: Successfully Deployed

Then, to get your connection details along with the VM ID, run:

orka vm list

You can then SSH into the running VM, make any changes you like, and then save a copy of the VM as an image in its current, modified state by running:

orka image save -v <VM_ID> -b <NEW_IMAGE_NAME> -y

Then you will have a modified macOS image in your local Orka storage that you can use as a template for spinning up any number of identical VMs for your iOS or macOS CI/CD pipeline.


Creating a master or “golden image” is the most efficient way to create identical Mac VMs time and again, which is useful for a reliable, scalable iOS or macOS CI pipeline. Above, we discussed both local and remote storage in Orka, and how these pieces will factor into your creating a golden image for your CI/CD workflows. We then walked through a sample workflow in which we pulled a Big Sur image from the remote storage, started a Mac VM based on that image, updated the running VM, and finally saved a copy of the VM as a new image that we will be able to spin up future VMs from.

Do you have additional questions or need more help with Orka? Visit our Orka Docs for more info, or chat with us on the MacStadium Community Slack channel.