Skip to main content

​
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 .img extension). 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 .orkasi extension)
Extensions are no longer required as part of an image name. The architecture is determined automatically.
Image accessibility Local images are accessible from all namespaces in your Orka cluster.

​
Local image commands

Deprecated in Orka 4.0. NFS-hosted images are deprecated and will be removed in a future Orka release. Use OCI images instead, created with orka vm push. In Orka 4.0, every orka image command prints a deprecation warning to stderr and shows (Deprecated) in its help. To move existing images, see Migrate NFS Orka images to OCI format with Harbor. The orka imagecache commands aren’t affected.

​
orka image list

List the locally stored images in your Orka cluster. (Note, you may not have any images until you run imagecache or a vm deploy command) Syntax:
Options:
If --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
By default, this operation also copies the description of the source image. You can explicitly change the description during this operation.
Copying an image is an async operation. To check the status: orka image list IMAGE_COPY_NAME
Syntax:
Options:
Examples:

​
orka3 image generate

Removed in Orka 4.0. orka3 image generate only creates Intel images and works on Orka 3.6 and earlier. In Orka 4.0 it returns an unknown-command error.
(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_NAME
Syntax:
Options:
Examples:

​
orka 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.
This operation overrides the existing description and cannot be undone.
Syntax:
Options:
Examples:

​
orka image delete

Delete the specified locally stored images.
This operation cannot be undone. VMs or VM configurations that use this image are affected and might stop working as expected.
Syntax:
Options:
Examples:

​
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
The --nodes, --tags, and --all flags are mutually exclusive. Syntax:
Options:
Examples:

​
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:
Options:
Examples:

​
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:
Options:
Examples:

​
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.
Remove a cached image from one or more nodes. Use this to free disk space on specific nodes, rotate stale images, or remove images that were cached automatically when a VM was deployed. Removal is asynchronous: the command initiates the operation and returns immediately. Run orka imagecache info IMAGE_NAME to check the status. The --nodes, --tags, and --all flags are mutually exclusive. Exactly one is required.
Do not remove an image while VMs are actively being deployed from it on the same node. If removal runs during the brief window between a deployment’s pull and clone stages, the deployment may fail with a generic error. The race window is typically seconds, but there is no automatic protection against it. Wait for in-flight deployments to complete before removing a cached image.
Syntax:
Options:
Examples:
Removal states: 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)

Deprecated in Orka 4.0. Remote images are NFS-hosted and will be removed in a future Orka release. In Orka 4.0, the orka remote-image commands print a deprecation warning to stderr and show (Deprecated) in their help. Use OCI registries for image storage, and use orka imagecache to load images into the cluster.

​
orka remote-image list

List the available images in the remote repository or look for specific images in the remote repository. Syntax:
Examples:

​
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
Syntax:
Examples: