Skip to main content
Requires Orka 3.2 or later on an Apple silicon cluster. If you’re on an earlier version, this feature is not available.

​
About

Image Caching lets you download Orka images ahead of time to any node in the Orka cluster. Pre-caching images provides faster and more reliable VM deployments by reducing delays caused by network bandwidth issues. Without Image Caching, automated CI jobs pull new images from a remote OCI registry or the local cluster datastore (NFS) during CI runtime, which can cause delays.

​
System Requirements

Scheduled Caching is available for:
  • Orka 3.2+
  • macOS computers based on Apple silicon

​
Overview

The first time a VM is run on a node, the image needs to be cached locally on that node. Previously, you could not bypass this step before running automated CI pipeline jobs. Since initial image pull speed depends on image size, network bandwidth, and node resource utilization, a build using a new VM image can take several minutes and produce inconsistent deployment times. Scheduled Caching lets you bypass these delays by pre-caching new images on Orka cluster nodes before CI automation starts. The cluster knows which nodes have necessary images cached, greatly reducing image loading and scheduled downtime. If a node cache lacks a needed image, you can pick nodes for cache operations and stipulate that VMs deploy on those nodes using those images. In other words, Scheduled Caching is an asynchronous operation.

​
Key Concepts

  • Image Caching allows preemptive copying of an Orka VM image on any cluster node member, to avoid delays caused by network bandwidth when images are pulled from an OCI registry or the cluster NFS datastore.
  • An image is the bits on disk representing a VM that can be used for saving state and sharing modifications.
  • MacStadium base VM Orka images are macOS OCI compliant VM images stored in our public GitHub registry ghcr.io/macstadium/orka-images/ with user credentials user/pwd: admin/admin, have Homebrew package manager installed, orka-vm-tools installed, and have screen sharing enabled and SSH access enabled.
  • Cluster local storage is an NFS mounted filesystem for storing images locally (local registry service). NFS is a legacy storage path. For clusters on Orka 3.5 or later, OCI-based storage via Harbor is recommended. See Migrating NFS images to OCI with Harbor.
  • A VM is a virtual runtime on top of the macOS host. The VM runs a guest OS image and macOS supports up to 2 running VMs per cluster node.
  • For the macOS versions you can run as a guest OS on each Orka release, see the compatibility matrix.
Orka can deploy a VM from multiple image sources: a cloud image datastore (OCI registry service), cached images on a cluster node member, and Orka’s local cluster registry (NFS, legacy). There are three distinct CLI commands to display each storage type and the images available on that datastore.

​
Getting Started

To get started with Scheduled Caching via the Orka CLI, take the following steps:
  1. Run orka imagecache -h to see the CLI tree structure: commands, subcommands and options/flags
  2. Run orka image list to view images used by the Orka cluster so far
  3. Run orka imagecache list to view images currently stored on Orka Cluster nodes
  4. View the Orka Cluster node names by typing orka node list
  5. Add a new image to a cluster node orka imagecache add
  6. Check the status of an image caching operation orka imagecache info
  7. Rapidly deploy a new VM using a recently cached Orka image on a specific node orka vm deploy --image <image_name> --node <node_name>

​
Image Caching FAQs

General information and guidance on Scheduled Caching
  • Does caching have an impact on running VMs?
    • Caching small images (16 GB) may be unnoticeable in VMs with long-running build times. (If a build takes 10 minutes, then a cache operation of 1 minute has a lower impact on the overall duration of the build job.)
    • The greater the number of images cached, the more significant the impact on a running VM on that node, due to resource contention. The image caching operation consumes resources on the node, particularly disk I/O.
  • How many cache operations can run at once?
    • Cache jobs share a node’s pod quota with the VMs on that node. The quota is 4 per node by default, so a node running VMs has fewer slots left for cache jobs.
    • Caching more images simultaneously is faster than caching multiple images sequentially.
    • On Orka 3.6.4 and later, a caching job that can’t be scheduled or gets stuck fails after 3 hours by default and releases its resources. On earlier versions, stuck caching jobs never failed, and four or more on one node blocked new VM deployments there.
  • Does caching have an impact on build performance?
    • Performance is impacted depending on the number of cache operations running.
    • MacStadium recommends that build jobs and caching operations not run concurrently unless:
      • The actual image size is small.
      • Long-running builds are active, and a small performance hit is acceptable.
  • Does caching have an impact on the performance of other cache operations?
    • Yes. A VM running on a node with an active caching job will see a noticeable increase in task execution time, proportional to the size of the image being written.
  • Does caching have an impact on network, memory, or CPU performance?
    • Nodes with an active caching download can impact a VM’s performance, including network I/O operations and CPU/memory availability.
  • Does caching have an impact on cluster performance?
    • The Orka scheduler may experience increased latency on any node running active caching operations.
  • Can I delete images from a cluster node cache?
    • Yes, on Orka 3.6.3 and later. This is a cluster-side requirement, not a CLI one: your Orka cluster itself must be running 3.6.3 or later. Updating only your local orka CLI does not enable this feature; if your cluster hasn’t been upgraded, the command fails even with a current CLI. See How to upgrade your Orka cluster or contact MacStadium support to confirm your cluster’s version. Once your cluster is on 3.6.3 or later, use orka imagecache remove IMAGE_NAME --nodes NODE_NAME to remove a cached image from a specific node, --all to remove from every node in the namespace, or --tags to target nodes by tag. This also covers images that were cached automatically when a VM was deployed. Removal is asynchronous; run orka imagecache info IMAGE_NAME to check the status. See orka imagecache remove for the full reference. Do not run this command while VMs are actively being deployed from that image: if removal runs between a deployment’s pull and clone stages, the deployment may fail with a generic error.
Orka 3.5.1 fix: orka ic add previously failed silently when caching images to nodes in custom namespaces. This is resolved in Orka 3.5.1. If you cache images to non-default namespaces, upgrade to 3.5.1 or later and re-cache any previously failed images.

​
Known issues

Re-caching an image committed under the same name (Orka 3.6.3 and later). If you modify an existing image and commit the changes while keeping the same name and tag, a later orka imagecache add can report the image as already cached on some nodes and skip re-caching the updated image. This affects both OCI and NFS images.The impact is limited. VMs always deploy from the updated image, because the first VM deployment from that image on an affected node re-caches it automatically. Those deployments are slower, since the cache is rebuilt at deploy time instead of ahead of time.To pre-cache the updated image explicitly, use either workaround:
  • Remove the cached image and add it again: orka imagecache remove <IMAGE> --all (or --nodes / --tags), then orka imagecache add <IMAGE> --all.
  • Deploy a VM from the image once to force a re-cache.
A fix is planned for a future Orka release. This note will be updated with the version that resolves it.