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.
orka3 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:
orka3 vm-config create VM_CONFIGURATION_NAME [flags]
-c, --cpu int (Optional) Number of CPU cores for the VM (default 3)
--disable-net-boost (Optional) (Intel-only) Disables network performance boost
--disable-vnc (Optional) Disable VNC (ensure SSH/Screen Sharing is enabled)
-g, --gpu (Optional) (Intel-only) Enable GPU passthrough
-h, --help Display help for create
-i, --image string (Required) Base image (local or OCI)
--iso string (Optional) (Intel-only) ISO name to attach
-m, --memory float (Optional) RAM in gigabytes
--scheduler string (Optional) Scheduler: 'default' or 'most-allocated'
--system-serial string (Optional) (Intel-only) Custom serial number
--tag string (Optional) Node affinity tag
--tag-required (Optional) Require tagged nodes for deployment
# Create a template for an Intel-based VM
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --cpu 6
# Create a template for an Apple silicon VM using an OCI image
orka3 vmc create small-arm-vm -i ghcr.io/my-org/orka-images/orka-arm:latest --cpu 4
# Create a template with 5GB RAM
orka3 vmc create medium-ventura-arm-vm --image 90gbventurassh.orkasi --memory 5
# (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
# Create a template with flexible node affinity
orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --tag jenkins-builds --tag-required=false
# Create a template with strict node affinity
orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --tag jenkins-builds --tag-required=true
# Create a template that uses the most-allocated scheduler
orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --scheduler most-allocated
# (Intel-only) Create a template with GPU passthrough
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --gpu=true --disable-vnc
# Create a template with disabled VNC
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --disable-vnc
orka3 vm-config list [VM_CONFIGURATION_1 [VM_CONFIGURATION_2 ...]] [--output wide|json] [flags]
-h, --help Display help for list
-o, --output string (Optional) Output format: table (default)|wide|json
# List basic information about available VM configurations
orka3 vmc list
# List extended information
orka3 vmc list --output wide
# Show basic information about a specific VM configuration
orka3 vmc list small-ventura-vm
# Show extended information about a specific VM configuration
orka3 vmc list small-ventura-vm --output wide
# Show information about multiple VM configurations
orka3 vmc list small-monterey small-ventura
# Return output as JSON
orka3 vmc list --output json
orka3 vm-config delete VM_CONFIGURATION_NAME [VM_CONFIGURATION_NAME_2 ...] [flags]
-h, --help Display help for delete
# Delete a VM configuration
orka3 vmc delete small-ventura-arm-vm
# Delete multiple VM configurations
orka3 vmc delete medium-ventura-vm medium-ventura-arm-vm
Deploying VMs
orka3 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
Note: Some settings are Intel-only (amd64 architecture) and some settings might be mutually exclusive.
Syntax:
orka3 vm deploy [VM_NAME] --image IMAGE_NAME [flags]
orka3 vm deploy [VM_NAME] --config VM_CONFIGURATION_NAME [flags]
--config string (Optional) VM template name
-c, --cpu int (Optional) Number of CPU cores
--disable-net-boost (Optional) (Intel-only) Disable network boost
--disable-vnc (Optional) Disable VNC
--generate-name (Optional) Generate unique name with suffix
-g, --gpu (Optional) (Intel-only) Enable GPU passthrough
-h, --help Display help for deploy
-i, --image string (Required) Base image (local or OCI)
--iso string (Optional) (Intel-only) ISO name
-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)
--scheduler string (Optional) Scheduler: 'default' or 'most-allocated'
--system-serial string (Optional) (Intel-only) Custom serial number
--tag string (Optional) Node affinity tag
--tag-required (Optional) Require tagged nodes
--timeout int (Optional) Deployment timeout in minutes (default 10)
-n, --namespace string (Optional) Namespace scope (default "orka-default")
# Deploy a VM from a local Orka image
orka3 vm deploy -i 90gbventurassh.orkasi
# Deploy a VM from an OCI image
orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest
# Deploy with specified name, image, and CPU
orka3 vm deploy small-ventura-vm -i 90gbventurassh.orkasi -c 4
# Deploy with unique name generation
orka3 vm deploy small-ventura-vm -i 90gbventurassh.orkasi --generate-name
# Deploy with specified memory and random name
orka3 vm deploy -i 90gbventurassh.orkasi -m 10
# Deploy and display extended information
orka3 vm deploy -i 90gbventurassh.orkasi --output wide
# Deploy with custom timeout
orka3 vm deploy -i 90gbventurassh.orkasi --timeout 1
# Deploy on a selected node
orka3 vm deploy -i 90gbventurassh.orkasi --node mini-arm-14
# Deploy on a selected node in a specific namespace
orka3 vm deploy -i 90gbventurassh.orkasi --node mini-arm-14 --namespace orka-test
# Deploy in a specific namespace
orka3 vm deploy -i 90gbventurassh.orkasi --namespace orka-test
# Deploy with flexible node affinity
orka3 vm deploy -i 90gbventurassh.orkasi --tag jenkins-builds --tag-required=false
# Deploy with strict node affinity
orka3 vm deploy -i 90gbventurassh.orkasi --tag jenkins-builds --tag-required=true
# Deploy using the most-allocated scheduler
orka3 vm deploy -i 90gbventurassh.orkasi --scheduler most-allocated
# Deploy with disabled VNC
orka3 vm deploy -i 90gbventurassh.img --disable-vnc
# Deploy with custom metadata
orka3 vm deploy -i 90gbventurassh.img --metadata 'foo=1,baz=https://example.com'
# Deploy with custom port mapping
orka3 vm deploy -i 90gbventurassh.img --ports 9000:4000,9001:4001
# Deploy with ISO for fresh macOS install
orka3 vm deploy -i emptydisk.img --iso ventura.iso
# Deploy with custom serial number
orka3 vm deploy -i 90gbventurassh.img --system-serial A00BC123D4
# Deploy with GPU passthrough
orka3 vm deploy -i 90gbventurassh.img --gpu=true --disable-vnc
# Deploy with disabled network boost
orka3 vm deploy -i 90gbmontereyssh.img --disable-net-boost
# Deploy from existing VM config with random name
orka3 vm deploy --config small-ventura-config
# Deploy from existing VM config with specified name
orka3 vm deploy small-ventura-vm --config small-ventura-config
# Deploy from VM config and override CPU and memory
orka3 vm deploy --config small-ventura-config -c 6 --memory 16
Listing VMs
orka3 vm list
Show basic or extended information about the specified VM(s).
Stopped or suspended VMs appear as ‘Running’ when listed. Do not rely on the displayed status to confirm a VM is active before scheduling work against it.
orka3 vm list [VM_NAME_1 [VM_NAME_2 ...]] [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]
-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")
# List all VMs in the 'orka-default' namespace
orka3 vm list
# List all VMs (extended table)
orka3 vm list --output wide
# List all VMs in a specific namespace
orka3 vm list --namespace orka-test
# List all VMs in a specific namespace (extended table)
orka3 vm list --namespace orka-test --output wide
# Show basic information about a specific VM
orka3 vm list small-ventura-vm
# Show detailed information about a specific VM
orka3 vm list small-ventura-vm --output wide
# Show information about multiple VMs
orka3 vm list small-ventura-vm small-monterey-vm
# Print information in JSON format
orka3 vm list --output json
Deleting VMs
orka3 vm delete
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.
Syntax:
orka3 vm delete VM_NAME [VM_NAME_2 ...] [--namespace CURRENT_VM_NAMESPACE] [flags]
-h, --help Display help for delete
-n, --namespace string (Optional) Namespace scope (default "orka-default")
# Delete a VM from the 'orka-default' namespace
orka3 vm delete small-ventura-vm
# Delete VMs from a specific namespace
orka3 vm delete small-ventura-vm small-ventura-arm-vm --namespace orka-test
