Orka3 CLI Command Reference

Overview

Orka Cluster helps customers with existing virtualization and orchestration technologies available in a macOS environment.

Orka Cluster is:

Relatively simple to get up and running
Kubernetes-based, so the learning curve is minimal, and resources are plentiful
A multi-interface offering, including a CLI and a fully featured API for interacting with, and automating an environment, VMs, and more.

Orka 3.2 Cluster

Manage Orka

orka3 [flags]

Options

-h, --help help for orka3

Sub-commands

orka3 completion - Generate the autocompletion script for the specified shell
orka3 config - Manage the local Orka CLI configuration
orka3 image - Manage locally stored images
orka3 imagecache - Manage individual cluster node(s) image cache
orks3 iso-Manage locally stored ISOs
orka3 login - Log in to your Orka cluster or create a new user
orka3 namespace - (Admin-only) Manage namespaces
orka3 node - Manage Orka nodes in the specified namespace
orka3 registrycredential - (Admin-only) Manage OCI registry credentials
orka3 remote-image - (Deprecated) List or pull images from the remote repository. This functionality will be removed in future releases. MacStadium suggests using OCI image repositories for storage.
orka3 remote-iso - (Deprecated) List or pull ISOs from the remote repository. This functionality will be removed in future releases. MacStadium suggests using OCI image repositories for image management.
orka3 rolebinding - (Admin-only) Manage rolebindings (used for user access management)
orka3 serviceaccount - (Admin-only) Manage service accounts
orka3 user - Manage your authentication with Orka
orka3 version - Print the current version of the Orka CLI
orka3 vm - Manage VMs
orka3 vm-config - Manage VM configurations

Commands for Managing Orka Cluster

Orka Completion

Generate the autocompletion script for the specified shell.

Synopsis

Generate the autocompletion script for orka3 for the specified shell.
See each sub-command's help for details on how to use the generated script.

Options

-h, --help help for completion

Sub-commands

orka3 - Manage Orka
orka3 completion bash - Generate the autocompletion script for bash
orka3 completion fish - Generate the autocompletion script for fish
orka3 completion powershell - Generate the autocompletion script for powershell
orka3 completion zsh - Generate the autocompletion script for zsh

Orka Completion Bash

Generate the autocompletion script for bash.

Synopsis

Generate the autocompletion script for the bash shell.

This script depends on the bash-completion package.
If it is not installed already, then install it via the OS's package manager.

To load completions in the current shell session:

source <(orka3 completion bash)

To load completions for every new session, execute once:

Linux:

orka3 completion bash > /etc/bash_completion.d/orka3

macOS:

orka3 completion bash > $(brew --prefix)/etc/bash_completion.d/orka3

A new shell must be started for this setup to take effect.

orka3 completion bash

Options

-h, --help help for bash --no-descriptions disable completion descriptions

Orka Completion Fish

Generate the autocompletion script for fish.

Synopsis

Generate the autocompletion script for the fish shell.

To load completions in the current shell session:

orka3 completion fish | source

To load completions for every new session, execute once:

orka3 completion fish > ~/.config/fish/completions/orka3.fish

A new shell must be started for this setup to take effect.

orka3 completion fish [flags]

Options

-h, --help help for fish --no-descriptions disable completion descriptions

Orka Completion Powershell

Generate the autocompletion script for powershell.

Synopsis

Generate the autocompletion script for powershell.

To load completions in your current shell session:

orka3 completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command
to the powershell profile.

orka3 completion powershell [flags]

Options

-h, --help help for powershell --no-descriptions disable completion descriptions

Orka Completion Zsh

Generate the autocompletion script for zsh

Synopsis

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in the environment, then is needs to be enabled. Execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in the current shell session:

source <(orka3 completion zsh)
To load completions for every new session, execute once:

Linux

orka3 completion zsh > "${fpath[1]}/\_orka3"

macOS

orka3 completion zsh > $(brew --prefix)/share/zsh/site-functions/\_orka3

A new shell must be started for this setup to take effect.

orka3 completion zsh [flags]

Options

\-h, --help help for zsh --no-descriptions disable completion descriptions

Orka Config

Manage the local Orka CLI configuration.

Synopsis

View or edit the current Orka CLI configuration.

The first time the Orka CLI is run, set the Orka service URL. Orka CLI commands are executed against this address.

Options

-h, --help help for config

Sub-commands

orka3 - Manage Orka
orka3 config set - Set the Orka CLI local configuration
orka3 config view - View the current local Orka CLI configuration

Orka Config Set

Set the Orka CLI local configuration.

Synopsis

Set the Orka CLI local configuration.

The first time the Orka CLI is run, set the Orka service URL. Orka CLI commands are executed against this address.

For environments initially deployed with Orka 2.1 or later, this is typically http://10.221.188.20.
For environments initially deployed before Orka 2.1, this is typically http://10.221.188.100.

It is possible to use the built-in Orka domain (COMPANY.orka.app) or an external custom domain. For more information, see Built-In Orka Domains and External Custom Domains

orka3 config set --api-url ORKA_SERVICE_URL [flags]

Examples

# Set your Orka service URL to 10.221.188.20 (for environments initially deployed with Orka 2.1 and later)

orka3 config set --api-url http://10.221.188.20

# Set your Orka service URL to 10.221.188.100 (for environments initially deployed before Orka 2.1)

orka3 config set --api-url http://10.221.188.100

# Set your Orka service URL to your built-in Orka domain (additional configuration required)

orka3 config set --api-url https://company.orka.app

# Set your Orka service URL to an external custom domain (additional configuration required)

orka3 config set --api-url https://company.com

Options

-a, --api-url string (Required) The Orka service URL against which to run all Orka CLI commands. -h, --help help for set

Orka Config View

View the current local Orka CLI configuration.

Synopsis

View the current local Orka CLI configuration.

orka3 config view [flags]

Examples

# Print your current Orka CLI configuration

orka3 config view

Options

-h, --help help for view

Orka Image

Manage locally stored images.

Synopsis

Manage the images stored locally in the Orka cluster.

Images are used to spin up VMs.
An amd64 architecture indicates an Intel-based image. (Previously denoted by an .img extension. Extensions are no longer required as part of an image name.
An arm64 extension indicates an Apple silicon-based image. (Previously denoted by an .orkasi extension. Extensions are no longer required as part of an image name.)

Local images are accessible from all namespaces.

orka3 image [flags]

Options

-h, --help help for image

Sub-commands

orka3 - Manage Orka
orka3 image copy - Copy the specified image
orka3 image delete - Delete the specified locally stored images
orka3 image generate - (Intel-only) Generate a new empty image with the specified size
orka3 image list - List the locally stored images
orka3 image set-description - Set a custom description for the specified image

Orka Image Copy

Copy the specified image.

Synopsis

Copy the specified image and set a new name for the copy.

The new name for the copy must meet the following 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. it is possible to explicitly change the description during this operation.

Copying an image is an async operation. To check the status of the operation, run:

orka3 image list IMAGE_COPY_NAME

Images are used to spin up VMs.
An amd64 architecture indicates an Intel-based image. (Previously denoted by an .img extension. Extensions are no longer required as part of an image name.)
An arm64 extension indicates an Apple silicon-based image. (Previously denoted by an .orkasi extension. Extensions are no longer required as part of an image name.)

Remote and local images are accessible from all namespaces.

orka3 image copy IMAGE_NAME IMAGE_COPY_NAME [--set-description 'DESCRIPTION'] [flags]

Examples

# Copy the existing '90gbventurassh.orkasi' and set the name of the copy to '90gbventurassh-copy.orkasi'

orka3 image copy 90gbventurassh.orkasi 90gbventurassh-copy.orkasi

# Copy the existing '90gbventurassh.orkasi', set the name of the copy to '90gbventurassh-copy.orkasi' and provide a custom description for the copy

orka3 image copy 90gbventurassh.orkasi 90gbventurassh.orkasi --description '[[email protected]](mailto:[email protected]) copied this image from 90gbventurassh.orkasi'

Options

-d, --description string (Optional) If set, changes the description of the copy. Defaults to 'Copied from SOURCE_IMAGE_DESCRIPTION'. -h, --help help for copy

Orka Image Delete

Delete the specified locally stored images.

Synopsis

Delete the specified locally stored images.

🚧
CAUTION:
This operation cannot be undone. VMs or VM configurations that use this image are affected and might stop working as expected.

orka3 image delete IMAGE_NAME [IMAGE_NAME_2 ...] [flags]

Examples

# Delete '90gbventurassh.orkasi' from your Orka cluster

orka3 image delete 90gbventurassh.orkasi

# Delete '90gbventurassh.orkasi' and '90gbventurassh.img' from your Orka cluster

orka3 image delete 90gbventurassh.orkasi 90gbventurassh.img

Options

\-h, --help help for delete

Orka Image Generate

(Intel-only) Generate a new empty image with the specified size

Synopsis

(Intel-only) Generate a new empty image with the specified size. Use an empty image to perform a fresh macOS install from ISO.

The name of the generated image must meet the following 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

Generating an image is an async operation. To check the status of the operation, run:
orka3 image list GENERATED_IMAGE_NAME

Images are used to spin up VMs. Generated images are always created as amd64 images (Intel-based images). Generated images are accessible from all namespaces.

orka3 image generate IMAGE_NAME SIZE [--set-description 'DESCRIPTION'] [flags]

Examples

# (Intel-only) Generate an empty 120GB image and set its name to '120gbemptyimage'

orka3 image generate 120gbemptyimage 120G

# (Intel-only) Generate an empty 120GB image, set its name to '120gbemptyimage', and provide a custom description for it

orka3 image generate 120gbemptyimage 120G --description '[[email protected]](mailto:[email protected]) created this empty image

Options

-d, --description string (Optional) If set, changes the description of the generated image. Defaults to a blank description. -h, --help help for generate

Orka Image List

List the locally stored images.

Synopsis

List the locally stored images.

Images are used to spin up VMs.
An amd64 architecture indicates an Intel-based image. (Previously denoted by an .img extension. Extensions are no longer required as part of an image name.)
An arm64 extension indicates an Apple silicon-based image. (Previously denoted by an .orkasi extension. Extensions are no longer required as part of an image name.)

Remote and local images are accessible from all namespaces.

If --output is not set, then it prints only the essential information in a table format.
It is possible to print an extended table with error information or JSON.

orka3 image list [IMAGE_NAME_1 [IMAGE_NAME_2 ...]] [--output wide|json] [flags]

Examples

# List the images stored locally in your Orka cluster

orka3 image list

# Check if the specified image exists locally

orka3 image list 90gbventurassh.img

# Check if the specified images exist locally

orka3 image list 90gbventurassh.img 90gbventurassh.orkasi

# Search for all local Intel-based images

orka3 image list | grep 'amd64'

# List the images stored locally and print the output as JSON

orka3 image list --output json

# Show additional error information for the locally stored images

orka3 image list --output wide

# Show additional error information for '90gbventurassh.orkasi'

orka3 image list 90gbventurassh.orkasi --output wide

# Show additional error information for the specified images

orka3 image list 90gbventurassh.orkasi 90gbventurassh.img --output wide

Options

-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Orka Image Set-Description

Set a custom description for the specified image.

Synopsis

Set a custom description for the specified image. This might be helpful to identify the owner of the image, where the image originated from, or how it is used across workflows.

🚧
CAUTION:
This operation overrides the existing description and cannot be undone.

Images are used to spin up VMs.
An amd64 architecture indicates an Intel-based image. (Previously denoted by an .img extension. Extensions are no longer required as part of an image name.)
An arm64 extension indicates an Apple silicon-based image. (Previously denoted by an .orkasi extension. Extensions are no longer required as part of an image name.)

Remote and local images are accessible from all namespaces.

orka3 image set-description IMAGE_NAME DESCRIPTION [flags]

Examples

# Set a custom description for '90gbventurassh.orkasi'

orka3 image set-description 90gbventurassh.orkasi '[[email protected]](mailto:[email protected]) set this description'

Options

-h, --help help for set-description

Orka ISO

Manage locally stored ISOs.

Synopsis

Manage locally stored ISOs. Use ISOs to perform a fresh macOS install on an empty Intel-based disk.

Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

orka3 iso [flags]

Options

-h, --help help for iso

Sub-commands

orka3 - Manage Orka
orka3 iso copy - Copy the specified locally stored ISO
orka3 iso delete - Delete the specified locally stored ISOs
orka3 iso list - List the locally stored ISOs
orka3 iso set-description - Set a custom description for the specified locally stored ISO

Orka ISO Copy

Copy the specified locally stored ISO.

Synopsis

Copy the specified locally stored ISO and set a new name for the copy. The copy is also stored locally in the Orka cluster.

The new name for the copy must meet the following 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 ISO. It is possible to explicitly change the description during this operation.

Copying an ISO is an async operation. To check the status of the operation, run:
orka3 iso list ISO_COPY_NAME

Use ISOs to perform a fresh macOS install on an empty Intel-based disk. Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

orka3 iso copy ISO_NAME ISO_COPY_NAME [--set-description 'DESCRIPTION'] [flags]

Examples

# Copy the existing 'ventura.iso' and set the name of the copy to 'ventura-copy.iso'

orka3 iso copy ventura.iso ventura-copy.iso

# Copy the existing 'ventura.iso', set the name of the copy to 'ventura-copy.iso' and provide a custom description for the copy

orka3 iso copy ventura.iso ventura-copy.iso --description '[[email protected]](mailto:[email protected]) copied this ISO from ventura.iso'

Options

-d, --description string (Optional) If set, changes the description of the copy. Defaults to 'SOURCE_ISO_DESCRIPTION'. -h, --help help for copy

Orka ISO Delete

Delete the specified locally stored ISOs.

Synopsis

Delete the specified locally stored ISOs.

🚧
CAUTION:
This operation cannot be undone. VMs or VM configurations that use this ISO will be affected and might stop working as expected.

Use ISOs to perform a fresh macOS install on an empty Intel-based disk. Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

orka3 iso delete ISO_NAME [ISO_NAME_2 ...] [flags]

Examples

# Delete 'ventura.iso' from your Orka cluster

orka3 iso delete ventura.iso

# Delete 'ventura.iso' and 'ventura-copy.iso' from your Orka cluster

orka3 iso delete ventura.iso ventura-copy.iso

Options

-h, --help help for delete

Orka ISO List

List the locally stored ISOs.

Synopsis

List the locally stored ISOs. Use ISOs to perform a fresh macOS install on an empty Intel-based disk.

Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

If --output is not set, the it prints only the essential information in a table format.
It is also possible to print an extended table with error information or JSON.

orka3 iso list [ISO_NAME_1 [ISO_NAME_2 ...]] [--output wide|json] [flags]

Examples

# List the ISOs stored locally in your Orka cluster

orka3 iso list

# Check if the specified ISO exists locally

orka3 iso list ventura.iso

# Check if the specified ISOs exist locally

orka3 iso list ventura.iso monterey.iso

# Search for all local ISOs that contain 'monterey' in the name

orka3 iso list | grep 'monterey'

# List the ISOs stored locally and print the output as JSON

orka3 iso list --output json

# Show additional error information for the locally stored ISOs

orka3 iso list --output wide

# Show additional error information for 'ventura.iso'

orka3 iso list ventura.iso --output wide

# Show additional error information for the specified ISOs

orka3 iso list monterey.iso ventura.iso --output wide

Options

-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Orka Set-Description

Set a custom description for the specified locally stored ISO.

Synopsis

Set a custom description for the specified locally stored ISO. This might be helpful to identify the owner of the ISO, where the ISO originated from, or how it is used across workflows.

🚧
CAUTION:
This operation overrides the existing description and cannot be undone.

Use ISOs to perform a fresh macOS install on an empty Intel-based disk. Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

orka3 iso set-description ISO_NAME DESCRIPTION [flags]

Examples

# Set a custom description for 'ventura.iso'

orka3 iso set-description ventura.iso '[[email protected]](mailto:[email protected]) set this description'

Options

-h, --help help for set-description

Orka Imagecache

Synopsis

Manage images stored on Orka cluster nodes. By adding images to a node before deployment of a VM using that base image, DevOps and engineering staff can manage and control the delay caused by remote or even local cluster storage image pulls providing consistent deployment times.

Images are used to spin up VMs.
An 'amd64' architecture indicates an Intel-based image. (Previously denoted by an '.img' extension. Extensions are no longer required as part of an image name.)
An 'arm64' extension indicates an Apple silicon-based image. (Previously denoted by an '.orkasi' extension. Extensions are no longer required as part of an image name.)

Both remote and local images are accessible from all namespaces.

orka3 imagecache [flags]

Options

-h, --help help for imagecache

Sub-commands

orka3 - Manage Orka
orka3 imagecache add - Copy the specified image
orka3 imagecache info - Delete the specified locally stored image(s)
orka3 imagecache list- (Intel-only) Generate a new empty image with the specified size

Orka Imagecache Add

Cache the specified image on the specified node(s).

Synopsis

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. See the 'orka3 regcred --help' command.

Caching an image is an async operation. To check the status of the operation, run:

orka3 imagecache info IMAGE_NAME

The 'nodes' and 'tags' flags are mutually exclusive.

The alias for ‘imagecache’ is 'ic' ex. orka3 ic --help

This operation is only supported for Apple Silicon nodes.

orka3 imagecache add IMAGE_NAME [--namespace CURRENT_NAMESPACE] {--nodes | --tags | --all} [flags]

Options

\--all Cache the image on all nodes in the current namespace.

\-h, --help Help for add

\--nodes The node(s) on which to cache the image on.

\--tags The node tag(s) by which to filter the nodes on which to cache the image on.

Examples

# Cache the 'sonoma-90gb-orka3-arm' image on the 'mini-arm-10' node

orka3 imagecache add sonoma-90gb-orka3-arm --nodes mini-arm-10

\# Cache the 'sonoma-90gb-orka3-arm' image on multiple nodes

orka3 imagecache add sonoma-90gb-orka3-arm --nodes mini-arm-10,mini-arm-11

\# Cache the 'sonoma-90gb-orka3-arm' image on all nodes in the current namespace

orka3 imagecache add sonoma-90gb-orka3-arm --all

\# Cache the 'sonoma-90gb-orka3-arm' image on nodes that have both 'my-tag' and 'my-other-tag'

orka3 imagecache add sonoma-90gb-orka3-arm --tags my-tag,my-other-tag

\# Cache the 'sonoma-90gb-orka3-arm' image on the 'mini-arm-10' node in the 'my-namespace' namespace

orka3 imagecache add sonoma-90gb-orka3-arm --nodes mini-arm-10 --namespace my-namespace

Orka Imagecache Info

Display the caching status of an image across nodes.

Synopsis

Use the info sub-command to verify if images are available for deployment ‘ready’ status or if the caching operation is still active ‘caching’ status. Specify an image name to get associated nodes that have the image cached already.

Shows the status of the specified image across the nodes where it is cached.

If '--output' is not set, prints only the essential information in a table format.

You can also print an extended table with error information or JSON.

orka3 imagecache info IMAGE_NAME [--namespace CURRENT_NAMESPACE] [flags]

Options

-h, --help help for info

-o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

-n, --namespace string (Global/Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Examples

# Display the caching status of the 'sonoma-90gb-orka3-arm' image

orka3 imagecache info sonoma-90gb-orka3-arm

# Display the caching status of an OCI Image ('latest' is the default tag)

orka3 imagecache info ghcr.io/macstadium/orka-images/sonoma

# Display the caching status of an OCI Image with a specific tag

orka3 imagecache info ghcr.io/macs

Orka Imagecache List

List cached images across nodes.

Synopsis

Use the list sub-command to provide 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.

orka3 imagecache list [IMAGE_NAME_1 IMAGE_NAME_2 ...] [--namespace CURRENT_NAMESPACE] [flags]

Options

\-h, --help help for list

\-o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

\-n, --namespace string (Global/Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Examples

# List all cached images on all nodes in the current namespace

orka3 imagecache list

\# Check if the specified image is cached on any node

orka3 imagecache list sonoma-90gb-orka3-arm

\# Check if an OCI image is cached on any node ('latest' is the default tag)

orka3 imagecache list ghcr.io/macstadium/orka-images/sonoma

\# Check if an OCI image with tag is cached on any node

orka3 imagecache list ghcr.io/macstadium/orka-images/sonoma:14.0

\# Check if the specified images are cached on any node

orka3 imagecache list sonoma-90gb-orka3-arm ghcr.io/macstadium/orka-images/sonoma:14.0

\# List all cached images on all nodes and print the output as JSON

orka3 imagecache list --output json

Orka Login

Synopsis

Log in to the Orka cluster with the MacStadium Customer Portal credentials. This operation launches a browser window with a login form.

Only an administrator or a member of the company account in the MacStadium Customer Portal.

After a successfully log in, Orka generates an authentication token and stores it in ~/.kube/config.

Alternatively, you can log in with a valid authentication token (e.g., a service account token):
orka3 user set-token

orka3 login [flags]

Examples

# Log in to your Orka cluster with your MacStadium Customer Portal credentials

orka3 user login

Options

-h, --help help for login

Orka Namespace

(Admin-only) Manage namespaces.

Synopsis

Manage the namespaces for the cluster. All operations in this group require administrative privileges.

Namespaces are used for grouping and dedicated resources to specific Orka users or service accounts. All users have access to the orka-default namespace. Based on specific rolebindings, a user or a service account might also be able to access the resources within additional namespaces.

All cluster namespaces must have the orka- prefix.

orka3 namespace [flags]

Options

-h, --help help for namespace

Sub-commands

orka3 - Manage Orka
orka3 namespace create - (Admin-only) Create a new namespace
orka3 namespace delete - (Admin-only) Delete the specified namespace
orka3 namespace list - (Admin-only) List namespaces

Orka Namespace Create

(Admin-only) Create a new namespace.

Synopsis

Create a new namespace with the specified name. This operation requires administrative privileges.

The namespace name must meet the following requirements:

Begins with the orka- prefix
Does not exceed 63 characters (including the prefix)
Consists of lowercase alphanumeric characters or dashes (-)
Еnds with an alphanumeric character
Must be unique to the cluster

If --enable-custom-pods is set, then it creates a new namespace dedicated to running custom K8s resources (formerly, sandboxing). Orka VMs cannot be deployed in that namespace.

After creating a new namespace, move one or more nodes to the namespace to provide it with computational resources. This is also known as node dedication:
orka3 tag namespace NODE --namespace NAMESPACE

To provide explicit access to one or more users (or service accounts) to the namespace:
orka3 rolebinding add-subject --namespace NAMESPACE --user EMAIL
orka3 rolebinding add-subject --namespace NAMESPACE --serviceaccount SA_NAMESPACE:SERVICE_ACCOUNT

orka3 namespace create NAMESPACE_NAME [flags]

Examples

# Create a new namespace named 'orka-test'

orka3 namespace create orka-test

# Create a new namespace named 'orka-cp' which allows running custom pods (previuosly sandboxing)

orka3 namespace create orka-cp --enable-custom-pods

Options

--enable-custom-pods If set, configures the namespace to enable the running of custom pods (formerly, sandboxing). You will not be able to run Orka VMs in that namespace. -h, --help help for create

Orka Namespace Delete

(Admin-only) Delete the specified namespace.

Synopsis

Delete the specified namespace. This operation requires administrative privileges.

All VMs (or custom pods) must be removed and nodes from the namespace before running this operation.

🚧
CAUTION:
This is a destructive operation and cannot be undone. To restore a deleted namespace, re-create it, move the respective Orka nodes, and re-add the respective users to the respective role bindings.

orka3 namespace delete NAMESPACE_NAME [NAMESPACE_2 ...] [flags]

Examples

# Delete the 'orka-test' namespace

orka3 namespace delete orka-test

# Delete multiple namespaces

orka3 namespace delete orka-test orka-production

Options

-h, --help help for delete -t, --timeout duration (Optional) If set, indicates the length of time to wait before giving up on deleting each namespace. (default 1h0m0s)

Orka Namespace List

(Admin-only) List namespaces.

Synopsis

List all namespaces for the Orka cluster. Use this command to check if one or more specific namespaces already exist (see examples). This operation requires administrative privileges.

orka3 namespace list [NAMESPACE_1 [NAMESPACE_2 ...]] [flags]

Examples

# List the existing namespaces for your Orka cluster

orka3 namespace list

# Check if a specific namespace exists

orka3 namespace list orka-test

# Check if several specific namespaces exist

orka3 namespace list orka-test orka-production

Options

-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Orka Node

Manage Orka nodes in the specified namespace.

Synopsis

Manage Orka nodes in the specified namespace: list, move across namespaces, and configure node affinity.

If --namespace is not set, operates in the orka-default namespace.

Some commands require administrative privileges.

orka3 node [flags]

Options

-h, --help help for node -n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Sub-commands

orka3 - Manage Orka
orka3 node list - Show information about the specified Orka node(s)
orka3 node namespace - (Admin-only) Move Orka nodes across namespaces
orka3 node tag - (Admin-only) Tag the specified Orka node for targeted VM deployment (set node affinity)
orka3 node untag - (Admin-only) Untag the specified Orka node for targeted VM deployment (remove node affinity)

Orka Node List

Show information about the specified Orka nodes.

Synopsis

Show basic or extended information about the specified Orka nodes.
Based on the specified output, the command returns information ranging from available resources and status to node IP and architecture, among others.

If --output is not set, then it prints only the essential information in a table format.
It is possible print an extended table or JSON.
If --namespace is not set, then it operates in the orka-default namespace.

orka3 node list \[NODE_NAME_1 [NODE_NAME_2 ...]] [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]

Examples

# List all Orka nodes in the 'orka-default' namespace

orka3 node list

# List all Orka nodes in the 'orka-default' namespace (extended table)

orka3 node list --output wide

# List all Orka nodes in the specified namespace (basic table)

orka3 node list --namespace orka-test

# List all Orka nodes in the specified namespace (extended table)

orka3 node list --namespace orka-test --output wide

# Show basic information about the specified Orka node

orka3 node list mini-1

# Show detailed information about the specified Orka node

orka3 node list mini-1 --output wide

# Show basic information about the specified Orka nodes

orka3 node list mini-1 mini-2

# Show detailed information about the specified Orka nodes

orka3 node list mini-1 mini-2 --output wide

# Print the information in JSON output format

orka3 node list --output json

Options

\-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Node Namespace

(Admin-only) Move Orka nodes across namespaces

Synopsis

Move Orka nodes across namespaces. This operation requires administrative privileges.

If --namespace is not set, the it assumes that the specified node is located in the orka-default namespace.

orka3 node namespace NODE [--namespace CURRENT_NAMESPACE] TARGET_NAMESPACE [flags]

Examples

# Move the specified Orka node from the 'orka-default' namespace to the 'orka-test' namespace

orka3 node namespace mini-1 orka-test

# Move the specified Orka node from the 'orka-test' namespace to the 'orka-production' namespace

orka3 node namespace mini-1 --namespace orka-test orka-production

# Move the specified Orka node back from the 'orka-production' namespace to the 'orka-default' namespace

orka3 node namespace mini-1 --namespace orka-production orka-default

Options

\-h, --help help for namespace

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Node Tag

(Admin-only) Tag the specified Orka node for targeted VM deployment (set node affinity).

Synopsis

Tag the specified Orka node for targeted VM deployment (set node affinity). This operation requires administrative privileges.

Node affinity indicates that the tagged node is preferred for the deployment of VMs with the same tag. Orka first attempts to deploy on any nodes with the respective tag, before moving to the remaining nodes in the environment. Orka attempts to deploy on other nodes, only if the VM setting to require a tag is no.

Your tag must meet the following requirements:

Does not exceed 63 characters
Consists of alphanumeric characters, dashes (-), underscores (_), or periods (.)
Begins and ends with an alphanumeric character
Set only one tag at a time. To add multiple tags, run the command separately for each tag.

If --namespace is not set, then it assumes that the specified node is located in the orka-default namespace.

To list the tags applied to a node, run the following command:
orka3 node list NAME [--namespace NAMESPACE] --output wide

orka3 node tag NODE_NAME TAG [--namespace TARGET_NAMESPACE] [flags]

Examples

# Tag the specified Orka node, located in the 'orka-default' namespace, with the specified tag ('jenkins')

orka3 tag mini-1 jenkins

# Tag the specified Orka node, located in the 'orka-test' namespace, with the specified tag ('jenkins')

orka3 tag mini-1 --namespace orka-test jenkins

# Check if the tag was applied as expected

orka3 node list mini-1 --output wide

Options

\-h, --help help for tag

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Node Untag

(Admin-only) Untag the specified Orka node for targeted VM deployment (remove node affinity).

Synopsis

Untag the specified Orka node for targeted VM deployment (remove node affinity). This operation requires administrative privileges.

Remove only one tag at a time. To remove multiple tags, run the command separately for each tag.

If --namespace is not set, the it assumes that the specified node is located in the orka-default namespace.

To list the tags applied to a node, run the following command:
orka3 node list NAME [--namespace NAMESPACE] --output wide

orka3 node untag NODE_NAME TAG [--namespace TARGET_NAMESPACE] [flags]

Examples

# Remove the specified single tag from the specified Orka node

orka3 node untag mini-1 my-tag

# Remove the specified single tag from the specified Orka node located in the 'orka-test' namespace

orka3 node untag mini-1 --namespace orka-test my-tag

# Check if the tag was removed as expected

orka3 node list mini-1 --output wide

Options

-h, --help help for untag

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Registry Credential

(Admin-only) Manage OCI registry credentials.

Synopsis

Manage OCI registry credentials. This group of operations requires administrative privileges.

OCI registry credentials are required to push and pull OCI-compatible Apple silicon-based Orka images to or from private repositories. OCI images are available only for Apple silicon-based VMs.

To deploy a VM using an OCI image, run:
orka3 vm deploy --image server.com/repository/image:tag

To push an image to an OCI registry (for example, GitHub packages), run:
orka3 vm push VM_NAME server.com/repository/image:tag

If --namespace is not set, then it creates the registry credentials in the orka-default namespace.

orka3 registrycredential [flags]

Options

\-h, --help help for registrycredential -n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Sub-commands

orka3 - Manage Orka
orka3 registrycredential add - (Admin-only) Add credentials for an OCI registry server
orka3 registrycredential list - (Admin-only) List OCI registry servers
orka3 registrycredential remove - (Admin-only) Remove credentials for an OCI registry server

Orka Registry Credential Add

(Admin-only) Add credentials for an OCI registry server.

Synopsis

Add credentials for the specified OCI registry server in the orka-default namespace or the specified namespace. This operation requires administrative privileges.

Add new credentials for a new server, or replace the existing credentials for an existing server.
The server address of the registry must include the scheme, hostname and (optionally) port. For example, 'https://ghcr.io' or 'https://10.221.188.5:30080'.

OCI registry credentials are required to push and pull OCI-compatible Apple silicon-based Orka images to or from private repositories.

If insecure communication is allowed, then requests to the registry server will fall back to HTTP when HTTPS is unavailable (disabled by default).

If --namespace is not set, then it adds the credentials in the orka-default namespace.

orka3 registrycredential add SERVER --username USERNAME {--password PASSWORD | --password-stdin} [--replace] [--allow-insecure] [flags]

Examples

# Add registry credentials for GitHub Packages in the specified namespace

orka3 regcred add <https://ghcr.io> --username whoami --password ghp\_\*\*\* --namespace orka-test

# Read the password for GitHub Packages from stdin

echo -n "$PASSWORD" | orka3 regcred add <https://ghcr.io> --username whoami --password-stdin

# Read the password for GitHub Packages from file over stdin

orka3 regcred add <https://ghcr.io> --username whoami --password-stdin \< password.txt

# Add credentials for an insecure server

orka3 regcred add --allow-insecure <http://10.221.188.5:30080> --username admin --password p@ssw0rd

# Replace the existing credentials for GitHub Packages

orka3 regcred add --replace <https://ghcr.io> --username whoami --password ghp\_\*\*\*

Option

--allow-insecure (Optional) If HTTPS is not available, falls back to HTTP. -h, --help help for add \-h, --help help for add -p, --password string Password for registry authentication. You can read the password from stdin instead with the '--password-stdin' flag. --password-stdin Read the password from stdin. You can provide the password with the '--password' flag instead. --replace (Optional) Replaces the credentials for the specified server name. -u, --username string (Required) Username for registry authentication.

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Registry Credential List

(Admin-only) List OCI registry servers.

Synopsis

Lists the OCI registry servers that have stored credentials in the orka-default namespace or the specified namespace. This operation requires administrative privileges.

If --output is not set, then it prints only the essential information in a table format.
It is also possible print an extended table or JSON.

If --namespace is not set, then it lists the servers stored in the orka-default namespace.

orka3 registrycredential list [flags]

Examples

# List the OCI registry servers for which you have stored credentials in the 'orka-default' namespace

orka3 regcred list

# Show additional information about each registry server in the specified namespace

orka3 regcred list --output wide --namespace orka-test

Options

\-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Registry Credential Remove

(Admin-only) Remove credentials for an OCI registry server.

Synopsis

Remove the authentication credentials for the specified registry server in the orka-default namespace or the specified namespace. This operation requires administrative privileges.

The server address of the registry must include the scheme, hostname and (optionally) port. For example, 'https://ghcr.io' or 'https://10.221.188.5:30080'.

If --namespace is not set, then it removes the credentials from the orka-default namespace.

orka3 registrycredential remove SERVER [flags]

Examples

# Remove registry credentials for GitHub Packages in the 'orka-default' namespace

orka3 regcred remove <https://ghcr.io>

# Remove registry credentials for a private server in the 'orka-test' namespace

orka3 regcred remove <http://10.221.188.5:30080> --namespace orka-test

Options

\-h, --help help for remove

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

(Deprecated) Orka Remote-Image

🚧
CAUTION
This functionality will be removed in future releases. MacStadium recommends using OCI registries for image storage and management. the orka3 imagecache command should be used as a replacement to load images into the cluster.

List or pull images from the remote repository.

Synopsis

List or pull images from the remote repository (also referred to as remote images).

Images are used to spin up VMs. MacStadium manages a remote repository of vanilla macOS images. To use a remote image to spin up a VM, it must be pulled locally on the Orka Cluster.

Images are used to spin up VMs. MacStadium manages a remote repository of vanilla macOS images. To use a remote image to spin up a VM, it must have been pulled locally on the Orka cluster.

An amd64 architecture indicates an Intel-based image. (Previously denoted by an .img extension. Extensions are no longer required as part of an image name.)
An arm64 extension indicates an Apple silicon-based image. (Previously denoted by an .orkasi extension. Extensions are no longer required as part of an image name.)

Remote and local images are accessible from all namespaces.

orka3 remote-image [flags]

Options

\-h, --help help for remote-image

Sub-commands

orka3 - Manage Orka
orka3 remote-image list - List images in the remote repository
orka3 remote-image pull - Pull an image from the remote repository

(Deprecated) Orka Remote-Image List

🚧
CAUTION
This functionality will be removed in future releases. MacStadium recommends using OCI registries for image storage and management. the orka3 imagecache command should be used as a replacement to load images into the cluster.

List images in the remote repository.

Synopsis

List the available images in the remote repository or look for specific images in the remote repository. Images in the remote repository are also referred to as remote images.

Images are used to spin up VMs. MacStadium manages a remote repository of vanilla macOS images. To use a remote image to spin up a VM, it must have been pulled locally on the Orka cluster.

Remote and local images are accessible from all namespaces.

orka3 remote-image list [IMAGE_NAME_1 [IMAGE_NAME_2 ...]] [--output wide|json] [flags]

Examples

# List the available images in the remote repository

orka3 remote-image list

# Check if the specified image exists in the remote repository

orka3 remote-image list 90gbventurassh.img

# Check if the specified images exist in the remote repository

orka3 remote-image list 90gbventurassh.img 90gbventurassh.orkasi

# Search for all remote Intel-based images

orka3 remote-image list | grep 'amd64'

# List the available images in the remote repository and print the output as JSON

orka3 remote-image list --output json

Options

-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

(Deprecated) Orka Remote-Image Pull

🚧
CAUTION
This functionality will be removed in future releases. MacStadium recommends using OCI registries for image storage and management. the orka3 imagecache command should be used as a replacement to load images into the cluster.

Pull an image from the remote repository.

Synopsis

Copy an image from the remote repository (also referred to as remote image) and store it locally in the Orka Cluster. It is possible to keep the original name or set a new name in the local cluster storage. Note that pulling a remote image locally takes up from the available cluster storage.

If set, the new local name for the image must meet the following 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

Pulling a remote image is an async operation. To check the status of the operation, run:
orka3 image list PULLED_IMAGE_NAME

Images are used to spin up VMs. MacStadium manages a remote repository of vanilla macOS images. To use a remote image to spin up a VM, it must have been pulled locally on the Orka cluster.

Remote and local images are accessible from all namespaces.

orka3 remote-image pull REMOTE_IMAGE_NAME [NEW_LOCAL_IMAGE] [--set-description 'DESCRIPTION'] [flags]

Examples

# Pull the specified image from the remote repository

orka3 remote-image pull 90gbventurassh.orkasi

# Pull '90gbventurassh.orkasi' from the remote repository and rename it to '90gbventurassh2023.orkasi'

orka3 remote-image pull 90gbventurassh.orkasi 90gbventurassh2023.orkasi

# Pull '90gbventurassh.orkasi' from the remote repository and set a custom description

orka3 remote-image pull 90gbventurassh.orkasi --description '[[email protected]](mailto:[email protected]) pulled this image'

Options

\-d, --description string (Optional) If set, changes the description of the new image. Defaults to 'Pulled from REMOTE_IMAGE'. -h, --help help for pull

(Deprecated) Orka Remote-ISO

🚧
CAUTION
This functionality will be removed in future releases. MacStadium recommends using OCI registries for image storage and management. the orka3 imagecache command should be used as a replacement to load images into the cluster.

List or pull ISOs from the remote repository.

Synopsis

List or pull ISOs from the remote repository (also referred to as remote ISOs).

MacStadium maintains a remote repository with ISOs that can be used to perform a fresh macOS install on an empty Intel-based disk. To use a remote ISO, it msut have been pulled locally to the Orka Cluster.

Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

orka3 remote-iso [flags]

Options

-h, --help help for remote-iso

Sub-commands

orka3 - Manage Orka
orka3 remote-iso list - List ISOs in the remote repository
orka3 remote-iso pull - Pull an ISO from the remote repository

(Deprecated) Orka Remote-ISO List

🚧
CAUTION
This functionality will be removed in future releases. MacStadium recommends using OCI registries for image storage and management. the orka3 imagecache command should be used as a replacement to load images into the cluster.

List ISOs in the remote repository.

Synopsis

List the available ISOs in the remote repository or look for specific ISOs in the remote repository. ISOs in the remote repository are also referred to as remote ISOs.

MacStadium maintains a remote repository with ISOs that can be used to perform a fresh macOS install on an empty Intel-based disk. To use a remote ISO, it must have been pulled locally to the Orka cluster.

Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

orka3 remote-iso list [ISO_NAME_1 [ISO_NAME_2 ...]] [--output wide|json] [flags]

Examples

# List the available ISOs in the remote repository

orka3 remote-iso list

# Check if the specified ISO exists in the remote repository

orka3 remote-iso list ventura.iso

# Check if the specified ISOs exist in the remote repository

orka3 remote-iso list ventura.iso monterey.iso

# Search for all remote ISOs that contain 'monterey' in the name

orka3 remote-iso list | grep "monterey"

# List the available ISOs in the remote repository and print the output as JSON

orka3 remote-iso list --output json

Options

-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

(Deprecated) Orka Remote-ISO Pull

🚧
CAUTION
This functionality will be removed in future releases. MacStadium recommends using OCI registries for image storage and management. the orka3 imagecache command should be used as a replacement to load images into the cluster.

Pull an ISO from the remote repository.

Synopsis

Copy an ISO from the remote repository (also referred to as remote ISO) and store it locally in the Orka cluster. it is possible to keep the original name or set a new name in the local cluster storage. Note that pulling a remote ISO locally takes up from the available cluster storage.

If set, the new local name for the ISO must meet the following requirements:

Does not exceed 63 characters including the extension (if set)
Consists of lowercase alphanumeric characters, dashes (-) or periods (.)
Must be unique to the cluster

Pulling a remote ISO is an async operation. To check the status of the operation, run:
orka3 iso list PULLED_ISO_NAME

MacStadium maintains a remote repository with ISOs, which can be used to perform a fresh macOS install on an empty Intel-based disk. To use a remote ISO, it must have been pulled locally to the Orka Cluster.

Working with ISOs is applicable only to Intel-based VMs. Remote and local ISOs are accessible from all namespaces.

orka3 remote-iso pull REMOTE_ISO_NAME [LOCAL_ISO_NAME] [--set-description 'DESCRIPTION'] [flags]

Examples

# Pull the specified ISO from the remote repository

orka3 remote-iso pull ventura.iso

# Pull 'ventura.iso' from the remote repository and rename it to 'ventura2023.iso'

orka3 remote-iso pull ventura.iso ventura2023.iso

# Pull 'ventura.iso' from the remote repository and set a custom description

orka3 remote-iso pull ventura.iso --description '[[email protected]](mailto:[email protected]) pulled this ISO'

Options

-d, --description string (Optional) If set, changes the description of the new ISO. Defaults to 'Pulled from REMOTE_ISO'. -h, --help help for pull

Orka Rolebinding

(Admin-only) Manage rolebindings (used for user access management).

Synopsis

Manage rolebindings in the Orka Cluster. This group of operations requires administrative privileges.

Orka relies on RBAC (role-based access control) for the management of user access to resources. In Orka, RBAC consists of the following elements:

Roles: a set of permissions. Roles are managed by MacStadium.
Subjects: users and service accounts which can be bound to a role. Subjects are managed by Orka users with administrative privileges.
Namespaces: groups of resources dedicated to specific users or service accounts. Namespaces are managed by Orka users with administrative privileges.
Rolebindings: K8s objects describing which subjects belong to which role and which subjects can access which namespaces. Rolebindings are managed by Orka users with administrative privileges.

By default, all admin users have access to all namespaces.
All non-admin users have user access to the 'orka-default' namespace.

To grant a user access to a specific namespace, add that user as a subject to the rolebinding for the namespace.
Service accounts automatically have access to the namespace where they were created. To grant a service account access to a specific namespace, add that service account as a subject to the rolebinding for the namespace.

orka3 rolebinding [flags]

Options

\-h, --help help for rolebinding -n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Sub-commands

orka3 - Manage Orka
orka3 rolebinding add-subject - (Admin-only) Add a subject to a rolebinding
orka3 rolebinding list-subjects - (Admin-only) List rolebinding subjects
orka3 rolebinding remove-subject - (Admin-only) Remove a subject from a rolebinding

Orka Rolebinding Add-Subject

(Admin-only) Add a subject to a rolebinding.

Synopsis

Add a subject to the rolebinding for the specified namespace. This grants the user or the service account access to the specified namespace. This operation requires administrative privileges.

If --namespace is not set, assumes it is adding subjects to the rolebinding for the orka-default namespace.

orka3 rolebinding add-subject --namespace TARGET_NAMESPACE --user EMAIL_1[,EMAIL_2,...] AND/OR --serviceaccount SA_NAMESPACE_1:SERVICE_ACCOUNT_1[,SA_NAMESPACE_2:SERVICE_ACCOUNT_2,...] [flags]

Examples

# Grant '[[email protected]](mailto:[email protected])' access to the 'orka-test' namespace

orka3 rb add-subject --namespace orka-test --user [[email protected]](mailto:[email protected])

# Grant multiple users access to the 'orka-test' namespace

orka3 rb add-subject --namespace orka-test --user [[email protected]](mailto:[email protected]),[[email protected]](mailto:[email protected])

# Grant the 'sa-jenkins' service account, created in the 'orka-default' namespace, access to the 'orka-test' namespace

orka3 rb add-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins

# Grant multiple service accounts access to the 'orka-test' namespace

orka3 rb add-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds

# Grant multiple users and service accounts access to the 'orka-test' namespace

orka3 rb add-subject --namespace orka-test --user [[email protected]](mailto:[email protected]),[[email protected]](mailto:[email protected]) --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds

Options

-h, --help help for add-subject -s, --serviceaccount strings One or more service accounts to add as subjects to the rolebinding. Should be in the NAMESPACE:SERVICE_ACCOUNT format. Accepts comma-separated values. -u, --user strings One or more users to add as subjects to the rolebinding. Should be an email address. Accepts comma-separated values.

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Rolebinding List-Subjects

(Admin-only) List rolebinding subjects.

Synopsis

List all rolebinding subjects, along with their kind, in the orka-default namespace or another specified namespace. This operation requires administrative privileges.

If --namespace is not set, operates in the orka-default namespace.

orka3 rolebinding list-subjects [--namespace TARGET_NAMESPACE] [flags]

Examples

# List the subjects in the rolebinding for the 'orka-default' namespace

orka3 rb list-subjects

# List the subjects in the rolebinding for the 'orka-test' namespace

orka3 rb list-subjects --namespace orka-test

# List only subjects which are service accounts

orka3 rb list-subjects | grep 'ServiceAccount'

Options

-h, --help help for list-subjects -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Rolebinding Remove-Subject

(Admin-only) Remove a subject from a rolebinding.

Synopsis

Remove a subject from a rolebinding. This revokes the user or service account access to the specified namespace. This operation requires administrative privileges.

If --namespace is not set, assumes that it is removing subjects from the rolebinding for the orka-default namespace.

orka3 rolebinding remove-subject --user EMAIL_1[,EMAIL_2,...] AND/OR --serviceaccount SA_NAMESPACE_1:SERVICE_ACCOUNT_1[,SA_NAMESPACE_2:SERVICE_ACCOUNT_2,...] [--namespace TARGET_NAMESPACE] [flags]

Examples

# Revoke access to the 'orka-test' namespace for '[[email protected]](mailto:[email protected])'

orka3 rb remove-subject --namespace orka-test --user [[email protected]](mailto:[email protected])

# Revoke access to the 'orka-test' namespace for multiple users

orka``3 rb remove-subject --namespace orka-test --user [email protected],[email protected]

# Revoke access to the 'orka-test' namespace for the 'sa-jenkins' service account, created in the 'orka-default' namespace

orka3 rb remove-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins

# Revoke access to the 'orka-test' namespace for multiple service accounts

orka3 rb remove-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds

# Revoke access to the 'orka-test' namespace for multiple users and service accounts

orka3 rb remove-subject --namespace orka-test --user [[email protected]](mailto:[email protected]),[[email protected]](mailto:[email protected]) --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds

Options

-h, --help help for remove-subject -s, --serviceaccount strings One or more service accounts to remove from the rolebinding. Should be represented as NAMESPACE:SERVICE_ACCOUNT. Accepts comma-separated values. -u, --user strings One or more users to remove from the rolebinding. Should be an email address. Accepts comma-separated values.

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

orka3 serviceaccount

(Admin-only) Manage service accounts.

Synopsis

Manage the service accounts, including any authentication tokens for them, for any CI/CD integrations. All operations in this group require administrative privileges.

Service accounts are intended for use by CI/CD integrations. To use the cluster with one of the available Orka integrations, a service account must be created, obtain an authentication token for it, and configure the token in the preferred integration.

If --namespace is not set, then it creates the service account with access to the orka-default namespace.

orka3 serviceaccount [flags]

Options

-h, --help help for serviceaccount -n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Sub-commands

orka3 - Manage Orka
orka3 serviceaccount create - (Admin-only) Create a service account
orka3 serviceaccount delete - (Admin-only) Delete the specified service account(s)
orka3 serviceaccount list - (Admin-only) List service accounts
orka3 serviceaccount token - (Admin-only) Obtain a service account token

Orka Service Account Create

(Admin-only) Create a service account.

Synopsis

Create a service account with the specified name in the orka-default namespace or in another specified namespace. After the service account is created, it cannot be move it across namespaces. This operation requires administrative privileges.

Your service account name must meet the following requirements:

Does not exceed 253 characters
Consists of lowercase alphanumeric characters, dashes (-) or periods (.)
Begins and ends with a lowercase alphanumeric character
Must be unique to the namespace

To use the newly created service account, obtain a token for it by running:
orka3 sa token SERVICE_ACCOUNT_NAME

If --namespace is not set, then it creates the service account with access to the orka-default namespace.

orka3 serviceaccount create SERVICE_ACCOUNT_NAME [--namespace TARGET_NAMESPACE] [flags]

Examples

# Create a service account in the 'orka-default' namespace

orka3 sa create sa-jenkins

# Create a service account in the specified namespace

orka3 sa create sa-jenkins-test --namespace orka-test

Options

-h, --help help for create

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Service Account Delete

(Admin-only) Delete the specified service accounts.

Synopsis

Delete one or more service accounts in the orka-default namespace or another specified namespace. This operation requires administrative privileges.

🚧
CAUTION:
Deleting the service account also invalidates any tokens associated with it. This cannot be undone.

If --namespace is not set, the it operates in the orka-default namespace.

orka3 serviceaccount delete SERVICE_ACCOUNT_NAME [SERVICE_ACCOUNT_NAME_2 ...] [--namespace TARGET_NAMESPACE] [flags]

Examples

# Delete the specified service account in the 'orka-default' namespace

orka3 sa delete sa-jenkins

# Delete the specified service account in the 'orka-test' namespace

orka3 sa delete sa-jenkins --namespace orka-test

# Delete multiple service accounts

orka3 sa delete sa-jenkins sa-jenkins-test

Options

\-h, --help help for delete

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Service Account List

(Admin-only) List service accounts.

Synopsis

List the service accounts in the orka-default namespace or another specified namespace. It is also possible to use this command to check if a specific service account already exists (see examples). This operation requires administrative privileges.

If --namespace is not set, then it operates in the orka-default namespace.

orka3 serviceaccount list [SERVICE_ACCOUNT_NAME_1] [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]

Examples

# List the existing service accounts in the 'orka-default' namespace

orka3 sa list# List the existing service accounts for the specified namespace

orka3 sa list --namespace orka-test# Check if the specified service account already exists in the 'orka-default' namespace

orka3 sa list sa-jenkins# Check if the specified service account already exists in the specified namespace

orka3 sa list sa-jenkins --namespace orka-test

Options

-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka Service Account Token

(Admin-only) Obtain a service account token.

Synopsis

Obtain an authentication token for the specified service account name. This operation requires administrative privileges.

If --duration is not set, then the token is valid for 8760 hours (1 year). Note that even when set, Orka might return a token with a shorter or a longer lifetime.
If --namespace is not set, then it assumes that the specified service account is located in the orka-default namespace.

orka3 serviceaccount token SERVICE_ACCOUNT_NAME [--duration DURATION] [--namespace TARGET_NAMESPACE] [flags]

Examples

# Obtain a token for the specified service account in the 'orka-default' namespace

orka3 sa token sa-jenkins

# Obtain a token for the specified service account in the specified namespace

orka3 sa token sa-jenkins-test --namespace orka-test

# Obtain a token for the specified service account with the specified duration (must be in minutes or hours)

orka3 sa token sa-jenkins --duration 1h

Options

--duration duration If set, requests that the token is created with the specified lifetime (in minutes or hours). Orka might return a token with a longer or a shorter lifetime. (default 8760h0m0s) -h, --help help for token --no-expiration If set, requests that the token is created with no expiration. This flag is mutually exclusive with '--duration'.

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka User

Manage your authentication with Orka.

Synopsis

Manage your authentication with Orka.

Options

-h, --help help for user

Sub-commands

orka3 - Manage Orka
orka3 user get-token - Print your authentication token
orka3 user login - Log in to your Orka cluster or create a new user
orka3 user logout - Log out of the Orka cluster
orka3 user set-token - Log in with a valid authentication token

Orka User Get-Token

Print your authentication token.

Synopsis

If you are logged in, then print your authentication token from your ~/.kube/config. You can use the token to log in to the Web UI or work with the Orka API.

orka3 user get-token [flags]

Examples

# Print your authentication token from your '~/.kube/config'

orka3 user get-token

Options

-h, --help help for get-token

Orka User Login

Synopsis

Log in to your Orka cluster with your MacStadium Customer Portal credentials. This operation launches a browser window with a login form.

You must already be an administrator or a member of your company account in the MacStadium Customer Portal. If you can't access the MacStadium Customer Portal, contact your account administrator and request to be invited to the account.

After you log in successfully, Orka generates an authentication token and stores it in ~/.kube/config.

Alternatively, you can log in with a valid authentication token ( a service account token):
orka3 user set-token

orka3 user login [flags]

Examples

# Log in to your Orka cluster with your MacStadium Customer Portal credentials

orka3 user login

Options

-h, --help help for login

Orka User Logout

Log out of the Orka Cluster.

Synopsis

Log out of the Orka cluster.

orka3 user logout [flags]

Examples

# Log out of your Orka cluster

orka3 user logout

Options

-h, --help help for logout

Orka User Set-Token

Synopsis

You can print your authentication token from ~/.kube/config by running:
orka3 user get-token

Or, you can generate a valid service account token by running:
orka3 serviceaccount token SERVICE_ACCOUNT_NAME

orka3 user set-token VALID_TOKEN [flags]

Examples

# Log in with a valid authentication token

orka3 user set-token VALID_TOKEN

Options

-h, --help help for set-token

Orka Version

Print the current version of the Orka CLI.

Synopsis

Print the current version of the Orka CLI.

orka3 version [flags]

Examples

# Print the current version of the Orka CLI

orka3 version

Options

-h, --help help for version

Orka VM-Config

Manage VM configurations.

Synopsis

Manage VM configurations (templates for deploying virtual machines). All VM configurations reside in the orka-default namespace and are available to all users and service accounts with access to orka-default.

To deploy a VM from a VM configuration, run:
orka3 vm deploy VM_NAME --config VM_CONFIG

orka3 vm-config [flags]

Examples

# List extended information about the available VM configurations

orka3 vmc list --output wide

# Create a template for a VM with 6CPU and using the 90gbventurassh image

orka3 vmc create medium-ventura-vm --image 90gbventurassh --cpu 6

# Delete multiple VM configurations

orka3 vmc delete medium-ventura-vm medium-ventura-arm-vm

Options

-h, --help help for vm-config

Orka VM-Config Create

Create a VM configuration.

Synopsis

Create a VM configuration (template for deploying virtual machines) with the specified settings. The required minimum configuration consists of base image to use.

Orka creates the VM configuration in the orka-default namespace. It will be available to all users and service accounts with access to orka-default.

The name of the Vm configuration must meet the following requirements:

Does not exceed 50 characters
Consists of lowercase alphanumeric characters or dashes (-)
Starts with an alphabetic character and ends with an alphanumeric character
Must be unique to the cluster

To deploy a VM from a newly created VM configuration, run:
orka3 vm deploy VM_NAME --config VM_CONFIG

orka3 vm-config create VM_CONFIGURATION_NAME [flags]

Examples

# Create a template for an Intel-based VM with 6CPU and using the '90gbventurassh.img' image

orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --cpu 6

# Create a template for an Apple silicon-based VM using an OCI-compatible image from GitHub Packages

orka3 vmc create -i ghcr.io/my-organization/orka-images/orka-arm:latest --cpu 4

# Create a template for an Apple silicon-based VM with 4CPU and using the '90gbventurassh.orkasi' image

orka3 vmc create small-ventura-arm-vm --image 90gbventurassh.orkasi --cpu 4

# Create a template for a VM with 5GB RAM

orka3 vmc create medium-ventura-arm-vm --image 90gbventurassh.orkasi --memory 5

# (Intel-only) Create a template for a blank VM ready for OS install from ISO

orka3 vmc create fresh-ventura-vm --image 90gbempty.img --iso ventura.iso

# (Intel-only) Create a template for a VM with a custom valid serial number

orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --system-serial A00BC123D4

# Create a template for a VM with flexible node affinity

orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --tag jenkins-builds --tag-required=false

# Create a template for a VM with strict node affinity

orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --tag jenkins-builds --tag-required=true

# Create a template for a VM that will use a custom scheduler for deployment (most-allocated)

orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --scheduler most-allocated

# (Intel-only) Create a template for a VM with GPU passhtrough (GPU passthrough must be enabled on the environment)

orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --gpu=true --disable-vnc

# Create a template for a VM with disabled VNC (make sure that SSH or Apple Screen Sharing are already enabled on the image)

orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --gpu=true --disable-vnc

# (Intel-only) Create a template for a VM, running macOS Monterey or earlier, with disabled network performance boost (Ventura VMs must have network boost enabled)

orka3 vmc create medium-ventura-vm --image 90gbmontereyssh.img --disable-net-boost

Options

\-c, --cpu int (Optional) The number of CPU cores for the VM. If not set, the default value is 3. (default 3) --disable-net-boost (Optional) (Intel-only) Disables network performance boost for your VMs. Note that on Apple silicon-based VMs network boost is always enabled and cannot be disabled. --disable-vnc (Optional) Disable VNC. Make sure that any deployed VMs will be accessible via SSH or Apple Screen Sharing or you will be locked out of the VM. Note that if you've set '--gpu=true', you need to disable VNC. -g, --gpu (Optional) (Intel-only) Applicable only to environments with enabled GPU passthrough. Enable GPU passthrough for the deployed VM. When set, you also need to disable VNC ('--disable-vnc'). On Apple silicon-based VMs, GPU passthrough is always enabled and cannot be disabled. -h, --help help for create -i, --image string (Required) The base image that you want to use for the VM. You can specify an Orka image stored locally in the cluster (by name) or an OCI-compatible ARM image from an OCI registry (by full path, including image name and image tag). --iso string (Optional) (Intel-only) The name of the ISO to attach to the VM. When set, make sure that you're using an empty base image as well. -m, --memory float (Optional) The number of gigabytes of memory for the VM. Must not exceed 32GB on 32GB nodes, 60GB on 64GB, or 60GB on 128GB nodes. If not set, defaults to a value based on the node with the least memory. --scheduler string (Optional) Sets which scheduler to use when deploying VMs from the VM configuration. Valid values are 'default' and 'most-allocated'. When set to 'default', Orka deploys in such a way that it keeps the used and free resources balanced across nodes. When set to 'most-allocated', Orka deploys the VMs in such a way that it uses up the resources of one node before moving on to the next. --system-serial string (Optional) (Intel-only) Sets a custom serial number for the VM. You must own the serial number and it must be a valid serial number. --tag string (Optional) Configures node affinity. When set, Orka first attempts to deploy to the node(s) with the specified tag. Based on the '--tag-required' setting, Orka might attempt to deploy on other nodes if it cannot deploy on the tagged node(s). --tag-required (Optional) When 'true', Orka attempts to deploy only on nodes with the specified tag. When 'false', Orka first attempts to deploy on the nodes with the specified tag. If the deployment fails, Orka will then attempt to deploy on the remaining nodes in the environment.

Orka VM-Config Delete

Delete VM configurations.

Synopsis

Delete the specified VM configurations (templates for deploying virtual machines).

All VM configurations reside in the orka-default namespace and are available to all users and service accounts with access to orka-default.

orka3 vm-config delete VM_CONFIGURATION_NAME [VM_CONFIGURATION_NAME_2 ...] [flags]

Examples

# Delete the VM configurations with the specified name

orka3 vmc delete small-ventura-arm-vm

# Delete multiple VM configurations

orka3 vmc delete medium-ventura-vm medium-ventura-arm-vm

Options

-h, --help help for delete

Orka VM-Config List

List the available VM configurations.

Synopsis

Show basic or extended information about the available VM configurations (templates for deploying virtual machines). It is possible to list all available configurations or show information about one or more specified VM configurations.

All VM configurations reside in the orka-default namespace and are available to all users and service accounts with access to orka-default.

To deploy a VM from a VM configuration, run:
orka3 vm deploy VM_NAME --config VM_CONFIG

If --output is not set, then it prints only the essential information in a table format.
You can also print an extended table or JSON.

orka3 vm-config list [VM_CONFIGURATION_1 [VM_CONFIGURATION_2 ...]] [--output wide|json] [flags]

Examples

# List basic information about the available VM configurations

orka3 vmc list

# List extended information about the available VM configurations

orka3 vmc list --output wide

# Find all VM configurations belonging to the specified owner

orka3 vmc list --output wide | '[[email protected]](mailto:[email protected])'

# Show basic information about the specified VM configuration

orka3 vmc list small-ventura-vm

# Show extended information about the specified VM configuration

orka3 vmc list small-ventura-vm --output wide

# Show basic information about the specified multiple VM configurations (separated with a space)

orka3 vmc list small-monterey small-ventura

# Show extended information about the specified multiple VM configurations (separated with a space)

orka3 vmc list small-monterey-vm small-ventura-vm --output wide

# Return the output of the command as JSON

orka3 vmc list --output json

Options

-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Orka VM

Manage VMs.

Synopsis

Spin up or manage VMs in your Orka cluster.

orka3 vm [flags]

Options

-h, --help help for vm -n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Sub-commands

orka3 - Manage Orka
orka3 vm commit - Update an existing image from a running VM
orka3 vm delete - Delete the specified VM(s)
orka3 vm deploy - Deploy a VM
orka3 vm get-push-status - (Apple silicon-only) View the status of an image being pushed to an OCI-compatible registry
orka3 vm list - Show information about the specified VM(s)
orka3 vm push - (Apple silicon-only) Push an image from a running VM to an OCI-compatible registry
orka3 vm resize - Resize the disk of a running VM
orka3 vm resume - (Intel-only) Resume a suspended VM
orka3 vm revert - (Intel-only) Revert a VM to the latest state of its image
orka3 vm save - Save a new image from a running VM
orka3 vm start - (Intel-only) Power ON a stopped VM
orka3 vm stop - (Intel-only) Power OFF a running VM
orka3 vm suspend - (Intel-only) Suspend a running VM

Orka VM Commit

Update an existing image from a running VM.

Synopsis

Take the changes from the specified deployed VM and commit them back to its respective base image. For Intel-based VMs, the image must not be in use by any other VMs.

This operation applies any file system changes and the state of the OS, including any running applications, to the original image. This way you can deploy new VMs with the applied changes from the same image.

Committing changes to an existing image is an async operation. To check the status of the operation, run:
orka3 image list IMAGE_NAME

This operation restarts the VM.

orka3 vm commit VM_NAME [--namespace CURRENT_VM_NAMESPACE] [--description 'DESCRIPTION'] [flags]

Examples

# Commit any changes from 'small-ventura-vm' to its original image

orka3 vm commit small-ventura-vm

# Commit any changes from 'small-ventura-vm' running in the 'orka-test' namespace to its original image

orka3 vm commit small-ventura-vm --namespace orka-test

# Commit any changes from 'small-ventura-vm' to its original image and set a new description for the image

orka3 vm commit small-ventura-vm --description 'This image was updated by [[email protected]](mailto:[email protected])'

Options

\-d, --description string (Optional) If set, changes the description of the original image. -h, --help help for commit

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Delete

Delete the specified VMs.

Synopsis

Delete the specified VMs. This frees up the respective resources and ports on the respective Orka node.

🚧
CAUTION:
This operation cannot be undone. You will not be able to restore any unsaved or uncommitted data from the VM.

If --namespace is not set, then it operates in the orka-default namespace.

orka3 vm delete VM_NAME [VM_NAME_2 ...] [--namespace CURRENT_VM_NAMESPACE] [flags]

Examples

# Delete the specified VM from the 'orka-default' namespace

orka3 vm delete small-ventura-vm

# Delete the specified VMs from the 'orka-test' namespace

orka3 vm delete small-ventura-vm small-ventura-arm-vm --namespace orka-test

Options

\-h, --help help for delete

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Deploy

Deploy a VM.

Synopsis

Deploy a VM with the specified configuration.

The minimum required configuration consists of an image and a number of CPU cores to assign to the VM.

Setting a VMNAME is optional:

When VMNAME is not provided, Orka generates a unique name consisting of 'vm-' and a unique suffix.
When VM_NAME is provided, Orka attempts to create the VM using the provided name. If the name is not unique, the VM will not be deployed.When both VM_NAME and '--generate-name' are provided, Orka generates a uniqe name based on the VM_NAME and a unique suffix.

When provided, the VMNAME must meet the following requirements:

Does not exceed 63 characters (including the '-suffix' generated with '--generate-name', if set)
Consists of lowercase alphanumeric characters or dashes
Starts with an alphabetic character and ends with an alphanumeric character
Must be unique to the namespace

NOTE: Some settings are Intel-only amd64 architecture and that some settings might be mutually exclusive.

If --output is not set, then it prints only the essential information about the newly deployed VM in a table format. It is also possible to print an extended table or JSON.

orka3 vm deploy [VM_NAME] --image IMAGE_NAME orka3 vm deploy [VM_NAME] --config VM_CONFIGURATION_NAME [flags]

Examples

## Basic Deployments

# Deploy a VM from an Orka image stored locally in the cluster

orka3 vm deploy -i 90gbventurassh.orkasi

# Deploy a VM from an OCI-compatible image in GitHub Packages

orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest

# Deploy 'small-ventura-vm' with the specified image and CPU

orka3 vm deploy small-ventura-vm -i 90gbventurassh.orkasi -c 4

# Deploy 'small-ventura-vm' with the specified image and request a uniquely generated suffix for the name (to avoid conflicts with any existing VMs)

orka3 vm deploy small-ventura-vm -i 90gbventurassh.orkasi --generate-name

# Deploy a VM with the specified image and memory and a randomly generated name

orka3 vm deploy -i 90gbventurassh.orkasi -m 10

# Deploy a VM and display extended information about the deployed VM

orka3 vm deploy -i 90gbventurassh.orkasi --output wide

# Deploy a VM and change the output of the deployment information to JSON

orka3 vm deploy -i 90gbventurassh.orkasi --output json

# Deploy a VM and change the default timeout of 10 minutes to 1 minute

orka3 vm deploy -i 90gbventurassh.orkasi --timeout 1

## Targeted Deployments

# Deploy a VM on a selected node in the 'orka-default' namespace

orka3 vm deploy -i 90gbventurassh.orkasi --node mini-arm-14

# Deploy a VM on a selected node in the 'orka-test' namespace

orka3 vm deploy -i 90gbventurassh.orkasi --node mini-arm-14 --namespace orka-test

# Deploy a VM in the 'orka-test' namespace

orka3 vm deploy -i 90gbventurassh.orkasi --namespace orka-test

# Deploy a VM with flexible node affinity

orka3 vm deploy -i 90gbventurassh.orkasi small-ventura-config 6 --tag jenkins-builds --tag-required=false

# Deploy a VM with strict node affinity

orka3 vm deploy -i 90gbventurassh.orkasi --tag jenkins-builds --tag-required=true

# Deploy a VM that will use a custom scheduler for deployment ('most-allocated')

orka3 vm deploy -i 90gbventurassh.orkasi --scheduler most-allocated

## Advanced Deployments

# Deploy a VM with disabled VNC (make sure that SSH or Apple Screen Sharing are enabled on the image)

orka3 vm deploy -i 90gbventurassh.img --disable-vnc

# Deploy a VM with custom metadata

orka3 vm deploy -i 90gbventurassh.img --metadata 'foo=1,baz=<https://example.com'>

# Deploy a VM with custom port mapping (node port 9000 will be mapped to VM port 4000 and node port 9001 will be mapped to VM port 4001)

orka3 vm deploy -i 90gbventurassh.img --ports 9000:4000,9001:4001

## Intel-Only Deployments

# (Intel-only) Deploy a VM with an empty disk and an attached ISO for a fresh macOS install

orka3 vm deploy -i emptydisk.img --iso ventura.iso

# (Intel-only) Deploy a VM with a custom valid serial number

orka3 vm deploy -i 90gbventurassh.img --system-serial A00BC123D4

# (Intel-only) Deploy a VM with GPU passhtrough (GPU passthrough must be enabled on the environment)

orka3 vm deploy -i 90gbventurassh.img --gpu=true --disable-vnc

# (Intel-only) Deploy a VM, running macOS Monterey or earlier, with disabled network performance boost (Ventura VMs must have network boost enabled)

orka3 vm deploy -i 90gbmontereyssh.img --disable-net-boost

## VM Configuration Deployments

# Deploy VM from an existing VM config with a randomly generated name

orka3 vm deploy --config small-ventura-config

# Deploy VM from an existing VM config with the specified name

orka3 vm deploy small-ventura-vm --config small-ventura-config

# Deploy VM from an existing VM config and override the CPU and memory settings

orka3 vm deploy --config small-ventura-config -c 6 --memory 16

Options

--config string (Optional) The name of the VM template that you want to deploy. This will set the default values for the VM. All values can be overridden by the flags.

\-c, --cpu int (Optional) The number of CPU cores for the VM. --disable-net-boost (Optional) (Intel-only) Disables network performance boost for your VMs. Note that on Apple silicon-based VMs network boost is always enabled and cannot be disabled. --disable-vnc (Optional) Disable VNC. Make sure that any deployed VMs will be accessible via SSH or Apple Screen Sharing or you will be locked out of the VM. Note that if you've set '--gpu=true', you need to disable VNC. --generate-name (Optional) Generate a name for the VM starting with the provided 'VM_NAME'. If this flag is not set and a 'VM_NAME' is not provided, Orka generates a name starting with 'vm-'. -g, --gpu (Optional) (Intel-only) Applicable only to environments with enabled GPU passthrough. Enable GPU passthrough for the deployed VM. When set, you also need to disable VNC ('--disable-vnc'). On Apple silicon-based VMs, GPU passthrough is always enabled and cannot be disabled. -h, --help help for deploy -i, --image string (Required) The base image that you want to use for the VM. You can specify an Orka image stored locally in the cluster (by name) or an OCI-compatible ARM image from an OCI registry (by full path, including image name and image tag). --iso string (Optional) (Intel-only) The name of the ISO to attach to the VM. When set, make sure that you're using an empty base image as well. -m, --memory float (Optional) The number of gigabytes of memory for the VM. Must not exceed 32GB on 32GB nodes, 60GB on 64GB, or 60GB on 128GB nodes. If not set, defaults to a value based on the node with the least memory. --metadata stringToString (Optional) Injects custom metadata to the VM in the following format: 'key1=value1,key2=value2'. IMPORTANT: Keys and values cannot contain commas (,) or equal signs (=). (default \[]) --node string (Optional) The node on which to deploy the VM. -o, --output string output format. One of: json|wide -p, --ports strings (Optional) Forwards traffic from the specified 'NODE_PORT' to the specified 'VM_PORT'. Provide the port mapping in the following format: '\<NODE_PORT>:\<VM_PORT>'.You can specify multiple ports by separating them with commas. IMPORTANT: Mapping the VM and node ports does not automatically open a port on your VM. You need to handle the incoming traffic on the VM separately. --scheduler string (Optional) Sets which scheduler to use when deploying VMs from the VM configuration. Valid values are 'default' and 'most-allocated'. When set to 'default', Orka deploys in such a way that it keeps the used and free resources balanced across nodes. When set to 'most-allocated', Orka deploys the VMs in such a way that it uses up the resources of one node before moving on to the next. --system-serial string (Optional) (Intel-only) Sets a custom serial number for the VM. You must own the serial number and it must be a valid serial number. --tag string (Optional) Configures node affinity. When set, Orka first attempts to deploy to the node(s) with the specified tag. Based on the '--tag-required' setting, Orka might attempt to deploy on other nodes if it cannot deploy on the tagged node(s). --tag-required (Optional) When 'true', Orka attempts to deploy only on nodes with the specified tag. When 'false', Orka first attempts to deploy on the nodes with the specified tag. If the deployment fails, Orka will then attempt to deploy on the remaining nodes in the environment. --timeout int (Optional) If set, indicates the length of time to wait for the deployment to complete. (default 10)

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Get-Push-Status

(Apple silicon-only) View the status of an image being pushed to an OCI-compatible registry.

Synopsis

View the status of an image being pushed to an OCI-compatible registry. This operation is applicable only to Apple silicon-based VMs.

The status is viewable for one (1) hour after finishing, after which point the underlying job is cleaned up.

If a job name is not provided, the status of all current image push operations is shown.
The job name is initially shown when the image push operation is started.
For more information, run:
orka3 vm push --help

orka3 vm get-push-status [JOB_NAME] [flags]

Examples

# View the status of all images being pushed

orka3 vm get-push-status

# View the status for a specific image by job name

orka3 vm get-push-status vm-push-qxjjf

Options

-h, --help help for get-push-status -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM List

Show information about the specified VMs.

Synopsis

Show basic or extended information about the specified VM(s).

INFO: Stopped or suspended VMs appear as 'Running' when listed.

If --output is not set, prints only the essential information in a table format.
You can also print an extended table or JSON.

If --namespace is not set, operates in the orka-default namespace.

orka3 vm list \[VM_NAME_1 [VM_NAME_2 ...]] [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]

Examples

# List all VMs in the 'orka-default' namespace

orka3 vm list

# List all VMs in the specified namespace (extended table)

orka3 vm list --output wide

# List all VMs deployed on a specific node in the 'orka-default' namespace

orka3 vm list --output wide | grep 'mini-arm-14'

# List all VMs in the 'orka-test' namespace

orka3 vm list --namespace orka-test

# List all VMs in the 'orka-test' namespace (extended table)

orka3 vm list --namespace orka-test --output wide

# Show basic information about the specified VM

orka3 vm list small-ventura-vm

# Show detailed information about the specified VM

orka3 vm list small-ventura-vm --output wide

# Show basic information about the specified VMs

orka3 vm list small-ventura-vm small-monterey-vm

# Show detailed information about the specified VMs

orka3 vm list small-ventura-vm small-monterey-vm --output wide

# Print the information in JSON output format

orka3 vm list --output json

Options

\-h, --help help for list -o, --output string (Optional) If set, changes the output format of the printed information. One of: table (default)|wide|json.

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Push

(Apple silicon-only) Push an image from a running VM to an OCI-compatible registry

Synopsis

The state of a running VM is saved on the host and pushed to an OCI-compatible registry. This operation is applicable only to Apple silicon-based VMs.

The provided image must be in the following format: 'server.com/repository/image:tag'.
The :tag portion of the image path is optional. If not provided, defaults to latest.

If --namespace is not set, assumes that the VM is running in the orka-default namespace.
Registry credentials must exist in the same namespace as the VM.

Registry credentials are required to authenticate to the registry for the push operation.
For more information, run:
orka3 regcred --help

Pushing an OCI image is an async operation. To check the status of the operation, run:
orka3 vm get-push-status JOB_NAME

orka3 vm push VM_NAME IMAGE[:TAG] [flags]

Examples

# Push an image to GitHub Packages from the running 'vm-5rjn4' VM

orka3 vm push vm-5rjn4 ghcr.io/myorg/orka-images/base:latest

# Push an image to GitHub Packages from the running 'vm-fxwj5' VM in the 'orka-test' namespace

orka3 vm push vm-fxwj5 ghcr.io/myorg/orka-images/base:latest --namespace orka-test

Options

-h, --help help for push

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Resize

Resize the disk of a running VM.

Synopsis

Resize the disk of a running VM; but only increase the size of the disk.

For Apple silicon-based VMs (arm64 architecture), nothing is needed after the command completes.

For Intel-based VMs (amd64 architecture), provide SSH access credentials for Orka to complete the resize and repartition automatically. If not provided, it must be completed manually. See 'https://orkadocs.macstadium.com/docs/disk-image-resize'

For Intel-based VMs, it is possible to save or commit the modified image manually:
orka3 vm save VM_NAME NEW_IMAGE_NAME
orka3 vm commit VM_NAME

Resize always assumes working in GB.

This operation restarts the VM.

orka3 vm resize VM_NAME NEW_DISK_SIZE [flags]

Examples

# Resize the disk of 'small-ventura-vm' to 100GB

orka3 vm resize small-ventura-vm 100

# Resize the disk of 'small-ventura-vm', running in the 'orka-test' namespace, to 100GB

orka3 vm resize my-vm --namespace orka-test 100

# (Intel-only) Resize the disk of the Intel-based 'small-intel-vm' to 100GB and repartition it automatically (requires credentials for SSH access to the VM)

orka3 vm resize small-intel-vm 100 --user admin --password admin

Options

-h, --help help for resize -p, --password string (Optional) (Intel-only) The SSH password used to connect to the VM for automatic repartition -u, --user string (Optional) (Intel-only) The SSH user used to connect to the VM for automatic repartition

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Resume

(Intel-only) Resume a suspended VM.

Synopsis

Resume a suspended VM. This operation resumes all suspended processes on the VM, without turning it on. This operation is applicable only to Intel-based VMs.

INFO: Suspended VMs appear as Running when listed with orka vm list VM_NAME.

The orka vm suspend and orka vm resume sequence acts as putting the VM on hold then resuming it.

orka3 vm resume VM_NAME [flags]

Examples

# Resume a suspended VM

orka3 vm resume small-ventura-vm

# Resume a suspended VM deployed in the 'orka-test' namespace

orka3 vm resume small-ventura-vm --namespace orka-test

Options

-h, --help help for resume

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Revert

(Intel-only) Revert a VM to the latest state of its image.

Synopsis

Revert VM to the latest state of its image. This operation restarts the VM. This operation is applicable only to Intel-based VMs.

🚧
CAUTION:
This operation cannot be undone. Any unsaved or uncommitted data will be lost and unable to be retrieved.

orka3 vm revert VM_NAME [flags]

Examples

# Revert the specified VM

orka3 vm revert small-ventura-vm

# Revert the specified VM deployed in the 'orka-test' namespace

orka3 vm revert small-ventura-vm --namespace orka-test

Options

-h, --help help for revert

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Save

Save a new image from a running VM.

Synopsis

Save a new image from a running VM. This saves the file system and the state of the OS, including any running applications.

It is possible to preserve the original image and deploy new VMs with the applied changes from the new image.

The name for the new image must meet the following 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

Saving a new image is an async operation. To check the status of the operation, run:
orka3 image list NEW_IMAGE_NAME

This operation does not affect the original image of the VM.

This operation restarts the VM.

orka3 vm save VM_NAME NEW_IMAGE_NAME [flags]

Examples

# Save a new image '120gbmodifiedventura' from the running 'medium-ventura-vm' VM

orka3 vm save medium-ventura-vm 120gbmodifiedventura

# Save a new image '120gbmodifiedventura' from the 'medium-ventura-vm' VM running in the 'orka-test' namespace

orka3 vm save medium-ventura-vm 120gbmodifiedventura --namespace orka-test

# Save a new image '120gbmodifiedventura' from the running 'medium-ventura-vm' VM and set a custom description for the image

orka3 vm save medium-ventura-vm 120gbmodifiedventura --description 'This image was saved by [[email protected]](mailto:[email protected])'

Options

\-d, --description string (Optional) If set, changes the description of the new image. Defaults to 'Saved from VM_NAME in namespace NAMESPACE_NAME.' -h, --help help for save

Options Inherited from Parent Commands

\-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Start

(Intel-only) Power ON a stopped VM.

Synopsis

Power ON a stopped VM. This operation is applicable only to Intel-based VMs.

INFO: Stopped VMs appear as Running when listed with orka vm list VM_NAME.

The orka vm stop and orka vm start sequence acts as a VM reboot.

orka3 vm start VM_NAME [flags]

Examples

# Power ON a stopped VM

orka3 vm start small-ventura-vm

# Power on a stopped VM deployed in the 'orka-test' namespace

orka3 vm start small-ventura-vm --namespace orka-test

Options

-h, --help help for start

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Stop

(Intel-only) Power OFF a running VM.

Synopsis

Power OFF a stopped VM. This operation is applicable only to Intel-based VMs.

INFO: Stopped VMs appear as 'Running' when listed with 'orka vm list VM_NAME'.

The orka vm stop and orka vm start sequence acts as a VM reboot.

orka3 vm stop VM_NAME [flags]

Examples

# Power off a running VM

orka3 vm stop small-ventura-vm

# Power off a running VM deployed in the 'orka-test' namespace

orka3 vm stop small-ventura-vm --namespace orka-test

Options

-h, --help help for stop

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Orka VM Suspend

(Intel-only) Suspend a running VM.

Synopsis

Suspend a running VM. This operation freezes all running processes on the VM, without turning it off. This operation is applicable only to Intel-based VMs.

INFO: Suspended VMs appear as Running when listed with orka vm list VM_NAME.

The orka vm suspend and orka vm resume sequence acts as putting the VM on hold then resuming it.

orka3 vm suspend VM_NAME [flags]

Examples

# Suspend a running VM

orka3 vm suspend small-ventura-vm

# Suspend a running VM deployed in the 'orka-test' namespace

orka3 vm suspend small-ventura-vm --namespace orka-test

Options

-h, --help help for suspend

Options Inherited from Parent Commands

-n, --namespace string (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

  -h, --help   help for suspend

Options inherited from parent commands

  -n, --namespace string   (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

Overview

Orka 3.2 Cluster

Manage Orka

Options

Sub-commands

Commands for Managing Orka Cluster

Orka Completion

Synopsis

Options

Sub-commands

Orka Completion Bash

Synopsis

Options

Orka Completion Fish

Synopsis

Options

Orka Completion Powershell

Synopsis

Options

Orka Completion Zsh

Synopsis

Linux

macOS

Options

Orka Config

Synopsis

Options

Sub-commands

Orka Config Set

Synopsis

Examples

Options

Orka Config View

Synopsis

Examples

Options

Orka Image

Synopsis

Options

Sub-commands

Orka Image Copy

Synopsis

Examples

Options

Orka Image Delete

Synopsis

🚧CAUTION:

Examples

Options

Orka Image Generate

Synopsis

Examples

Options

Orka Image List

Synopsis

Examples

Options

Orka Image Set-Description

Synopsis

🚧CAUTION:

Examples

Options

Orka ISO

Synopsis

Options

Sub-commands

Orka ISO Copy

Synopsis

Examples

Options

Orka ISO Delete

Synopsis

🚧CAUTION:

Examples

Options

Orka ISO List

Synopsis

Examples

Options

Orka Set-Description

🚧
CAUTION:

🚧
CAUTION:

🚧
CAUTION:

🚧
CAUTION:

🚧
CAUTION: