Understanding Orka images
Images are used to spin up VMs in Orka. An image contains the macOS operating system, applications, and any configurations you’ve set up. Image architecture types- amd64 architecture - Intel-based images (previously denoted by an
.imgextension). Orka 3.6 and earlier only: Orka 4.0 supports Apple silicon only and rejects new VMs that use amd64 images. - arm64 architecture - Apple silicon-based images (previously denoted by an
.orkasiextension)
Extensions are no longer required as part of an image name. The architecture is determined automatically.
ghcr.io/macstadium/orka-images/<os>:<tag>, for example ghcr.io/macstadium/orka-images/tahoe:26.6.1.
- To see which macOS versions and tags exist, check OrkaHub or the orka-images repository. Don’t assume a tag exists for every macOS point release. MacStadium builds and publishes new guest images manually, so a tag can lag behind Apple’s release.
latestis a moving tag. MacStadium re-publishes it, for example to update the Orka VM Tools, so its contents can change without the macOS version changing. If you omit the tag, Orka useslatest.- MacStadium doesn’t send notifications when it publishes a new image or re-publishes
latest. To find out about new images, check OrkaHub or the orka-images repository. If an image changing under your pipelines would be a problem, pin a version tag or a digest, as described in the following points. - To keep a fixed macOS version in VM configs and pipelines, pin a version tag where one exists, such as
tahoe:26.6.1. Version tags aren’t rebuilt when MacStadium updates the VM Tools, so features that need the Orka 4.0 VM Tools, such as User Data, needlatestor your own image with updated tools. For an image that never changes, pin it by digest instead of a tag, for exampleghcr.io/macstadium/orka-images/tahoe@sha256:<DIGEST>. - You don’t need to pull these images first. Pass the reference directly to
orka vm deploy --imageororka imagecache add. - The default login for these images is username
adminand passwordadmin. Change it after your first login. See Understanding Orka credentials.
Local image commands
orka image list
List the locally stored images in your Orka cluster. (Note, you may not have any images until you runimagecache or a vm deploy command)
Syntax:
--output is not set, prints only essential information in a table format. Use wide for additional error information or json for JSON output.
Examples:
orka image copy
Copy the specified image and set a new name for the copy. Image name requirements:- Does not exceed 63 characters including the file extension (if set)
- Consists of lowercase alphanumeric characters, dashes (-) or periods (.)
- Must be unique to the cluster
Copying an image is an async operation. To check the status:
orka image list IMAGE_COPY_NAMEorka3 image generate
(Intel-only) Generate a new empty image with the specified size. Use an empty image to perform a fresh macOS install from ISO. Generated images are always created as amd64 images (Intel-based images) and are accessible from all namespaces.Generating an image is an async operation. To check the status:
orka image list GENERATED_IMAGE_NAMEorka image set-description
Set a custom description for the specified image. This can be helpful to identify the owner of the image, where it originated from, or how it is used across workflows. Syntax:orka image delete
Delete the specified locally stored images. Syntax:Image cache commands
Manage images stored on Orka cluster nodes. By adding images to a node before deployment of a VM using that base image, you can manage and control the delay caused by remote or even local cluster storage image pulls, providing consistent deployment times.Image cache operations are only supported for Apple silicon nodes. The alias for
imagecache is ic.orka imagecache add
Cache the specified image on the specified node(s). Add an image to one, a select number, or all cluster node namespace members or members of a tagged node group. The image must be pulled in the cluster before caching it on the node(s), unless it is an OCI image. For OCI images, make sure you have the necessary credentials to pull the OCI image.Caching an image is an async operation. To check the status:
orka imagecache info IMAGE_NAME--nodes, --tags, and --all flags are mutually exclusive.
Syntax:
orka imagecache info
Display the caching status of an image across nodes. Use this to verify if images are available for deployment (“ready” status) or if the caching operation is still active (“caching” status). Syntax:orka imagecache list
List cached images across nodes. Provides information about cached images such as image tag (OCI repo pulled images only), the image-id (a unique identifier from manifest), the sparse size of the image, and the number of nodes the image is cached on. Syntax:List the images cached on one node
Theorka imagecache commands show images across nodes. To see every image cached on one node, for example before you run orka imagecache remove, read the node’s OrkaNode resource with kubectl. orka login saves your token to your kubeconfig, so kubectl works with the same access as the Orka CLI.
<NODE_NAME> with the node’s name from orka node list, and <NAMESPACE> with the namespace the node is assigned to. Nodes are in orka-default unless they’ve been moved to another namespace.
Each line shows an image’s names, its status (Ready, Caching, Failed, Removing, or RemoveFailed), and the disk space it uses, in bytes. To also see each image’s virtual size and any error message, use -o yaml and look under status.images.
Only Apple silicon nodes report cached images. On Intel nodes, the list is empty.
orka imagecache remove
Requires your Orka cluster to be running 3.6.3 or later, this is a server-side requirement, not a CLI one. Updating only your local
orka CLI does not enable this command: if your cluster hasn’t been upgraded to 3.6.3+, 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 before troubleshooting further.orka imagecache info IMAGE_NAME to check the status.
The --nodes, --tags, and --all flags are mutually exclusive. Exactly one is required.
Syntax:
If the targeted node no longer exists, the cache entry is cleaned up immediately. If the image is not currently cached on a targeted node, the operation completes without error.
If removal reaches
Failed and retrying does not resolve it, contact support@macstadium.com.
Remote images (deprecated)
orka remote-image list
List the available images in the remote repository or look for specific images in the remote repository. Syntax:orka remote-image pull
Copy an image from the remote repository and store it locally in the Orka cluster. You can keep the original name or set a new name in the local cluster storage.Pulling a remote image is an async operation. To check the status:
orka image list PULLED_IMAGE_NAME
