VM Deployment and Configuration

VM Configuration Templates

VM configurations (templates) allow you to define reusable settings 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. The shorthand alias for vm-config is vmc.

orka vm-config create

Create a VM configuration (template) with the specified settings. The required minimum configuration consists of a base image to use. VM Configuration Name 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

Syntax:

orka vm-config create VM_CONFIGURATION_NAME [flags]

Options:

-c, --cpu int                (Optional) Number of CPU cores for the VM (default 3)
--disable-vnc                (Optional) Disable VNC (ensure SSH/Screen Sharing is enabled)
--display-dpi int            (Optional) DPI of the VM's virtual display
--display-height int         (Optional) Height of the VM's virtual display
--display-width int          (Optional) Width of the VM's virtual display
-h, --help                   Display help for create
-i, --image string           (Required) Base image (local or OCI)
-m, --memory float           (Optional) RAM in gigabytes
--node string                (Optional) Node on which to deploy the VM
--scheduler string           (Optional) Scheduler: 'default' or 'most-allocated'
--tag string                 (Optional) Node affinity tag
--tag-required               (Optional) Require tagged nodes for deployment

Examples:

# Create a template for a VM using an OCI image
orka vmc create my-small-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --cpu 4

# Create a template using an image from your own OCI registry
orka vmc create my-oci-vm-config -i ghcr.io/my-organization/orka-images/orka-arm:latest --cpu 4

# Create a template with 5GB RAM
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --memory 5

# Create a template with flexible node affinity
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=false

# Create a template with strict node affinity
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=true

# Create a template that uses the most-allocated scheduler
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --scheduler most-allocated

# Create a template with disabled VNC
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --disable-vnc

# Create a template with a custom display size and DPI
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --display-width 2920 --display-height 1380 --display-dpi 100

Intel-only options (Orka 3.6 and earlier)

These options apply only to Intel-based (amd64) VMs on Orka 3.6 and earlier. They were removed in Orka 4.0, which supports Apple silicon only.

--disable-net-boost          (Optional) (Intel-only) Disables network performance boost
-g, --gpu                    (Optional) (Intel-only) Enable GPU passthrough
--iso string                 (Optional) (Intel-only) ISO name to attach
--legacy-io                  (Optional) (Intel-only) Enable legacy IO, for High Sierra and Mojave VMs
--system-serial string       (Optional) (Intel-only) Custom serial number

# (Intel-only) Create a template for an Intel-based VM
orka vmc create medium-ventura-vm --image 90gbventurassh.img --cpu 6

# (Intel-only) Create a template for OS install from ISO
orka3 vmc create fresh-ventura-vm --image 90gbempty.img --iso ventura.iso

# (Intel-only) Create a template with a custom serial number
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --system-serial A00BC123D4

# (Intel-only) Create a template with GPU passthrough
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --gpu=true --disable-vnc

orka vm-config list

Show basic or extended information about the available VM configurations. You can list all available configurations or show information about one or more specified VM configurations. Syntax:

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

Options:

-h, --help            Display help for list
-o, --output string   (Optional) Output format: table (default)|wide|json

Examples:

# List basic information about available VM configurations
orka vmc list

# List extended information
orka vmc list --output wide

# Show basic information about a specific VM configuration
orka vmc list small-ventura-vm

# Show extended information about a specific VM configuration
orka vmc list small-ventura-vm --output wide

# Show information about multiple VM configurations
orka vmc list small-ventura small-sonoma

# Return output as JSON
orka vmc list --output json

orka vm-config delete

Delete the specified VM configurations (templates). Syntax:

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

Options:

-h, --help   Display help for delete

Examples:

# Delete a VM configuration
orka vmc delete small-ventura-arm-vm

# Delete multiple VM configurations
orka vmc delete medium-ventura-vm medium-ventura-arm-vm

Deploying VMs

orka vm deploy

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. VM Name Behavior:

When VM_NAME 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 (must be unique)
When both VM_NAME and —generate-name are provided: Orka generates a unique name based on VM_NAME with a unique suffix

VM Name Requirements (when provided):

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

Syntax:

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

Options:

--config string              (Optional) VM template name
-c, --cpu int                (Optional) Number of CPU cores
--disable-vnc                (Optional) Disable VNC
--display-dpi int            (Optional) DPI of the VM's virtual display
--display-height int         (Optional) Height of the VM's virtual display
--display-width int          (Optional) Width of the VM's virtual display
--generate-name              (Optional) Generate unique name with suffix
-h, --help                   Display help for deploy
-i, --image string           (Required) Base image (local or OCI)
-m, --memory float           (Optional) RAM in gigabytes
--metadata stringToString    (Optional) Custom metadata (key1=value1,key2=value2)
--node string                (Optional) Specific node for deployment
-o, --output string          (Optional) Output format: json|wide
-p, --ports strings          (Optional) Port mapping (NODE_PORT:VM_PORT, optionally /tcp or /udp)
--scheduler string           (Optional) Scheduler: 'default' or 'most-allocated'
--tag string                 (Optional) Node affinity tag
--tag-required               (Optional) Require tagged nodes
--timeout int                (Optional) Deployment timeout in minutes (default 10)
--userdata string            (Optional) Bootstrap script run as root on the VM's first boot (file path or base64 string)
-n, --namespace string       (Optional) Namespace scope (default "orka-default")

User Data: --userdata requires Orka 4.0 or later and the Orka 4.0 orka-vm-tools in the image. The script runs once per VM, in the background, and doesn’t delay the VM becoming available. Its output goes to /var/log/orka/userdata.log inside the VM, and orka vm list --output wide shows its progress in the USERDATA-PHASE column. For how the script runs, its limits, and an example, see Bootstrap VMs with User Data. Examples - Basic Deployments:

# Deploy a VM from an OCI image
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest

# Deploy a VM from an image in your own OCI registry
orka vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest

# Deploy with specified name, image, and CPU
orka vm deploy my-vm -i ghcr.io/macstadium/orka-images/tahoe:latest -c 4

# Deploy with unique name generation
orka vm deploy my-vm -i ghcr.io/macstadium/orka-images/tahoe:latest --generate-name

# Deploy with specified memory and random name
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest -m 10

# Deploy and display extended information
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --output wide

# Deploy with custom timeout
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --timeout 1

Examples - Targeted Deployments:

# Deploy on a selected node
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --node mini-arm-14

# Deploy on a selected node in a specific namespace
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --node mini-arm-14 --namespace orka-test

# Deploy in a specific namespace
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --namespace orka-test

# Deploy with flexible node affinity
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=false

# Deploy with strict node affinity
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=true

# Deploy using the most-allocated scheduler
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --scheduler most-allocated

Examples - Advanced Deployments:

# Deploy with disabled VNC
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --disable-vnc

# Deploy with custom metadata
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --metadata 'foo=1,baz=https://example.com'

# Deploy with a bootstrap script that runs on first boot (Orka 4.0 or later)
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --userdata ./bootstrap.sh

# Deploy with custom port mapping (9000 to 4000 over TCP, 9001 to 4001 over UDP)
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --ports 9000:4000,9001:4001/udp

Examples - VM Configuration Deployments:

# Deploy from existing VM config with random name
orka vm deploy --config my-vm-config

# Deploy from existing VM config with specified name
orka vm deploy my-vm --config my-vm-config

# Deploy from VM config and override CPU and memory
orka vm deploy --config my-vm-config -c 6 --memory 16

Intel-only options (Orka 3.6 and earlier)

These options apply only to Intel-based (amd64) VMs on Orka 3.6 and earlier, and some are mutually exclusive. They were removed in Orka 4.0, which supports Apple silicon only.

--disable-net-boost          (Optional) (Intel-only) Disable network boost
-g, --gpu                    (Optional) (Intel-only) Enable GPU passthrough
--iso string                 (Optional) (Intel-only) ISO name
--legacy-io                  (Optional) (Intel-only) Enable legacy IO, for High Sierra and Mojave VMs
--system-serial string       (Optional) (Intel-only) Custom serial number

# (Intel-only) Deploy with ISO for fresh macOS install
orka3 vm deploy -i emptydisk.img --iso ventura.iso

# (Intel-only) Deploy with custom serial number
orka3 vm deploy -i 90gbventurassh.img --system-serial A00BC123D4

# (Intel-only) Deploy with GPU passthrough
orka3 vm deploy -i 90gbventurassh.img --gpu=true --disable-vnc

# (Intel-only) Deploy with disabled network boost
orka3 vm deploy -i 90gbventurassh.img --disable-net-boost

Listing VMs

orka vm list

Show basic or extended information about the specified VM(s). The extended table (--output wide) includes the USERDATA-PHASE column for VMs deployed with --userdata: pending, success, failed, skipped, or timeout. The column is empty for VMs without User Data. See Bootstrap VMs with User Data. Syntax:

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

Options:

-h, --help               Display help for list
-o, --output string      (Optional) Output format: table (default)|wide|json
-n, --namespace string   (Optional) Namespace scope (default "orka-default")

Examples:

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

# List all VMs (extended table)
orka vm list --output wide

# List all VMs in a specific namespace
orka vm list --namespace orka-test

# List all VMs in a specific namespace (extended table)
orka vm list --namespace orka-test --output wide

# Show basic information about a specific VM
orka vm list small-ventura-vm

# Show detailed information about a specific VM
orka vm list small-ventura-vm --output wide

# Show information about multiple VMs
orka vm list small-ventura-vm small-sonoma-vm

# Print information in JSON format
orka vm list --output json

Deleting VMs

orka vm delete

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

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

Syntax:

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

Options:

-h, --help               Display help for delete
-n, --namespace string   (Optional) Namespace scope (default "orka-default")

Examples:

# Delete a VM from the 'orka-default' namespace
orka vm delete small-ventura-vm

# Delete VMs from a specific namespace
orka vm delete small-ventura-vm small-ventura-arm-vm --namespace orka-test

MacStadium

Orka

MacStadium VDI

IaaS

VM Deployment and Configuration

VM Configuration Templates

orka vm-config create

orka vm-config list

orka vm-config delete

Deploying VMs

orka vm deploy

Listing VMs

orka vm list

Deleting VMs

orka vm delete

​VM Configuration Templates

​orka vm-config create

​orka vm-config list

​orka vm-config delete

​Deploying VMs

​orka vm deploy

​Listing VMs

​orka vm list

​Deleting VMs

​orka vm delete

VM Configuration Templates

orka vm-config create

orka vm-config list

orka vm-config delete

Deploying VMs

orka vm deploy

Listing VMs

orka vm list

Deleting VMs

orka vm delete