VMs
The orka vm
group of commands in the Orka CLI. These commands are used for VM and VM configuration management.
Quick navigation
Listing and info: List VM configurations | List VMs and VM configurations | Check the status of a VM
Deployment: Create VM configuration | Create VM | Deploy VM | Delete VM | Purge VM
Storage: Attach non-bootable disk | List VM disks
Management: Stop, start, suspend, or resume a VM
State: Revert VM | Save VM State | Delete VM State
Quick command summary
orka vm configs orka vm list -f [all / <USER>] orka vm status -v [<NAME> / <ID>] orka vm create-config orka vm create orka vm deploy -v <NAME> orka vm delete -v [<NAME> / <ID>] orka vm purge -v <NAME> orka vm attach-disk -v <VM_ID> -d <ADDITIONAL_STORAGE> orka vm list-disks -v <VM_ID> orka vm [stop / start / suspend / resume] -v [<NAME> / <ID>] orka vm revert -v [<NAME> / <ID>] orka vm save-state -v [<NAME> / <ID>] orka vm delete-state -v <VM_ID>
List VM configurations
Command
List all your VM configurations. Orka provides detailed information about the VM configuration.
orka vm configs
OR
orka vm configs -f <NAME>
Output
Options
You can pass the following option with orka vm configs
in direct mode:
Option | Description | Sample value |
---|---|---|
-f | Returns information about the VM configuration with the specified name. The specified name must be an exact match for the VM configuration you're looking for. | myorkavm |
--raw | Returns the output of the command in raw, greppable format. |
List VMs and VM configurations
List your VMs and VM configurations. If you are running this command in administrative mode, you can list the VMs and VM configurations of a specified user or for all users.
Command
orka vms
OR
orka vm list
OR
orka vm list -f <USER>
OR
orka vm list -f all
OR (with replicas expanded)
orka vm list --expand
Output
Options
You can pass the following options with orka vm list
in direct mode:
Option | Description | Sample value |
---|---|---|
-f | (Administrative-only) Set to all to list all VMs and VM configurations by all users in the Orka environment.Set to the email address of an Orka user to list their VMs and VM configurations. | all [email protected] |
--json | Bypasses the interactive prompt, executes the command with the specified parameters, and returns the output of the command in JSON . | |
--expand | Returns a list of all your VM configs and VMs, including any replicas. | |
--raw | Returns the output of the command in raw, greppable format. |
Create VM configuration
Command
Create a VM configuration from which you can deploy virtual machines.
orka vm create-config
OR (create basic config)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -y
OR (create config with custom VM memory)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -M <MEMORY_IN_GB> -y
OR (create config with attached ISO)
orka vm create-config -v <NAME> -b <EMPTY_BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -i <ISO> -y
OR (create config with attached additional storage)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -d <ADDITIONAL_STORAGE> -y
OR (create config with disabled VNC)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --vnc no -y
OR (create config with disabled IO boost)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --io-boost no -y
OR (create config with disabled Net boost)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --net-boost no -y
OR (create config with enabled GPU passthrough)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --gpu yes -y
OR (create config with custom serial number)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --system-serial <SERIAL> -y
OR (create config with a required tag)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --tag <TAG> --tag-required yes -y
OR (create config with a custom scheduler)
orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --scheduler most-allocated -y
Output
VM name limitations
The name you specify under
VM Name
must meet the following requirements:
- Doesn't exceed 38 characters.
- Contains only lowercase Latin alphanumeric characters (0-9, a-z) and dashes (-).
- Begins and ends with an alphanumeric character.
Options
Unless noted otherwise, all options apply to Intel and Apple silicon-based VMs.
You can pass the following options with orka vm create-config
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | A name for the VM configuration. All VMs deployed from this configuration will have this name. The string must consist of lowercase Latin alphanumeric characters or the dash ( - ). The string must begin and end with an alphanumeric character. The string must not exceed 38 characters. | myorkavm |
--base-image | -b | The base image that you want to use for the VM. | 90GBVenturaSSH.orkasi |
--cpu | -c | The number of CPU cores for the VM. | 3 |
--vcpu | -C | The number of vCPU cores for the VM. Must equal the number or half the number of CPU cores specified. When the number of CPU is 3, must be 3. | 3 |
--memory | -M | 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 specified, defaults to a value based on the node with the least memory. | 24 |
--iso | -i | (Intel-only) Attaches the specified ISO. You must provide the name of the ISO. | Ventura.iso |
--disk | -d | (Intel-only) Attaches the specified storage. You must provide the image name. | myemptystorage.img |
--vnc | Enables or disables VNC access when running orka vm deploy .When you enable GPU passthrough for the VM, this automatically disables VNC. | yes OR no | |
--io-boost | (Intel-only) (Only available in direct mode) Enables or disables IO performance boost for your VMs. (Apple silicon) I/O boost is always enabled on Apple silicon VMs and cannot be disabled. | yes OR no | |
--net-boost | (Intel-only) (Only available in direct mode) Enables or disables network performance boost for your VMs. (Apple silicon) Network boost is always enabled on Apple silicon VMs and cannot be disabled. | yes OR no | |
--gpu | (Intel-only) In environments with enabled GPU passthrough, enables or disables GPU passthrough for the VM. When you enable GPU passthrough for the VM, this automatically disables VNC. (Apple silicon) GPU passthrough is always enabled on Apple silicon VMs and cannot be disabled. | yes OR no | |
--system-serial | (Intel-only) (Only available in direct mode) Sets a custom serial number for the VM. You must provide a valid serial own that you own. | ||
--tag | 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 to other nodes if it cannot deploy on the tagged node(s).The string cannot exceed 32 characters. It must consist of lowercase and/or uppercase Latin alphanumeric characters, dashes ( - ), underscores (_ ), or periods (. ). The string must begin and end with an alphanumeric character.You can override any existing node affinity settings in the VM config during deployment. | myPool | |
--tag-required | When yes , Orka attempts to deploy only on nodes with the specified tag.When no , 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.You can override any existing node affinity settings in the VM config during deployment. | yes OR no | |
--scheduler | (Only available in direct mode) Sets which scheduler to use when deploying VMs from the config. 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. | default OR most-allocated |
Create VM
Command
Create a VM configuration and deploy a VM from it. This command is shorthand for orka vm create-config && orka vm deploy
.
orka vm create
OR (create and deploy basic VM)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -y
OR (create and deploy basic VM with custom memory)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -M <MEMORY> -y
OR (create and deploy VM on a specified node)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -n <NODE> -y
OR (create and deploy VM with attached ISO)
orka vm create -v <NAME> -b <EMPTY_BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -i <ISO> -y
OR (create and deploy VM with attached additional storage)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -d <ADDITIONAL_STORAGE> -y
OR (create and deploy VM with disabled VNC)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --vnc no -y
OR (create and deploy VM with disabled IO boost)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --io-boost no -y
OR (create and deploy VM with disabled network boost)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --net-boost no -y
OR (create and deploy VM with enabled GPU passthrough)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --gpu yes -y
OR (create and deploy VM with custom serial number)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --system-serial <SERIAL> -y
OR (create and deploy VM with required tag)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --tag <TAG> --tag-required yes -y
OR (create and deploy VM with a custom scheduler)
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> --scheduler most-allocated -y
Output
Options
Unless noted otherwise, all options apply to Intel and Apple silicon-based VMs.
You can pass the following options with orka vm create
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | A name for the VM configuration. All VMs deployed from this configuration will have this name. | myorkavm The string must consist of lowercase Latin alphanumeric characters or the dash ( - ). The string must begin and end with an alphanumeric character. The string must not exceed 38 characters. |
--base-image | -b | The base image that you want to use for the VM. | 90GBVenturaSSH.orkasi |
--cpu | -c | The number of CPU cores for the VM. | 3 |
--vcpu | -C | The number of vCPU cores for the VM. Must equal the number or half the number of CPU cores specified. When the number of CPU is 3, must be 3. | 3 |
--memory | -M | 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 specified, defaults to a value based on the node with the least memory. | 24 |
--node | -n | The node on which to deploy the VM. The specified node must have sufficient free computational resource to accommodate the VM. The node hardware must match the VM type (i.e. Intel- or Apple silicon-based). To let Orka choose a node, leave blank. | mini-1 |
--iso-image | -i | (Intel-only) Attaches the specified ISO. You must provide the name of the ISO. | Ventura.iso |
--disk | -d | (Intel-only) Attaches the specified storage. You must provide the image name. | myemptystorage.img |
--vnc | Enables or disables VNC access when running orka vm deploy .When you enable GPU passthrough for the VM, this automatically disables VNC. | yes OR no | |
--io-boost | (Intel-only) (Only available in direct mode) Enables or disables IO performance boost for your VMs. (Apple silicon) I/O boost is always enabled on Apple silicon VMs and cannot be disabled. | yes OR no | |
--net-boost | (Intel-only) (Only available in direct mode) Enables or disables network performance boost for your VMs. (Apple silicon) Network boost is always enabled on Apple silicon VMs and cannot be disabled. | yes OR no | |
--gpu | (Intel-only) In environments with enabled GPU passthrough, enables or disables GPU passthrough for the VM. When you enable GPU passthrough for the VM, this automatically disables VNC. (Apple silicon) GPU passthrough is always enabled on Apple silicon VMs and cannot be disabled. | yes OR no | |
--system-serial | (Intel-only) (Only available in direct mode) Sets a custom serial number for the VM. You must provide a valid serial own that you own. | ||
--tag | 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 to other nodes if it cannot deploy on the tagged node(s).You can override any existing node affinity settings in the VM config during subsequent deployments. | myPool The tag cannot exceed 32 characters. It must consist of lowercase and/or uppercase Latin alphanumeric characters, dashes ( - ), underscores (_ ), or periods (. ). The string must begin and end with an alphanumeric character. | |
--tag-required | When yes , Orka attempts to deploy only on nodes with the specified tag.When no , 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.You can override any existing node affinity settings in the VM config during subsequent deployments. | yes OR no | |
--scheduler | (Only available in direct mode) Sets which scheduler to use when deploying VMs from the config. 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. | default OR most-allocated |
Deploy VM
Command
Deploy a new virtual machine from the specified VM configuration.
orka vm deploy
OR
orka vm deploy -v <NAME> -y
OR (deploy on a specified node)
orka vm deploy -v <NAME> -n <NODE> -y
OR (deploy a scaled VM)
orka vm deploy -v <NAME> -r <NUMBER_OF_REPLICAS> -y
OR (deploy with additional ports)
orka vm deploy -v <NAME> -p <NODE_PORT>:<VM_PORT> -y
OR (deploy with attached ISO)
orka vm deploy -v <NAME> -i <ISO> -y
OR (deploy with additional storage)
orka vm deploy -v <NAME> -d <ADDITIONAL_STORAGE> -y
OR (deploy with disabled VNC)
orka vm deploy -v <NAME> --vnc no -y
OR (deploy with enabled GPU passthrough)
orka vm deploy -v <NAME> --gpu yes -y
OR (deploy with custom serial number)
orka vm deploy -v <NAME> --system-serial <SERIAL> -y
OR (deploy with required tag)
orka vm deploy -v <NAME> --tag <TAG> --tag-required yes -y
OR (deploy with a custom scheduler)
orka vm deploy -v <NAME> --scheduler most-allocated -y
Output
Options
Unless noted otherwise, all options apply to Intel and Apple silicon-based VMs.
You can pass the following options with orka vm deploy
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | The name of the VM configuration that you want to deploy. | myorkavm |
--node | -n | The node on which to deploy the VM. The specified node must have sufficient free computational resource to accommodate the VM. The node hardware must match the VM type (i.e. Intel- or Apple silicon-based). To let Orka choose a node, leave blank. | macpro-1 |
--replicas | -r | (Intel-only) The scale at which to deploy the VM configuration. If not specified, defaults to 1 .All replicas share the same ID. Some operations are not available for scaled VMs ( orka image save , orka image commit ). | 3 |
--iso-image | -i | (Intel-only) Attaches the specified ISO. You must provide the name of the ISO. | Ventura.iso |
--disk | -d | (Intel-only) Attaches the specified storage. You must provide the image name. | myemptystorage.img |
--vnc | Enables or disables VNC access when running orka vm deploy .When you enable GPU passthrough for the VM, this automatically disables VNC. You can override the VNC setting of the VM configuration. | yes OR no | |
--ports | -p | (Only available in direct mode) Forwards traffic to the specified port. You need to map a port on the node (host) to a port on the VM (guest). Use the following format: <NODE PORT>:<VM PORT> | 1337:3000 |
--system-serial | (Intel-only) (Only available in direct mode) Sets a custom serial number for the VM. You must provide a valid serial own that you own. | ||
--gpu | (Intel-only) In environments with enabled GPU passthrough, enables or disables GPU passthrough for the VM. When you enable GPU passthrough for the VM, this automatically disables VNC. (Apple silicon) GPU passthrough is always enabled on Apple silicon VMs and cannot be disabled. | yes OR no | |
--tag | 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 to other nodes if it cannot deploy on the tagged node(s).You can use this option to override any existing node affinity settings in the VM config. | myPool The tag cannot exceed 32 characters. It must consist of lowercase and/or uppercase Latin alphanumeric characters, dashes ( - ), underscores (_ ), or periods (. ). The string must begin and end with an alphanumeric character. | |
--tag-required | When yes , Orka attempts to deploy only on nodes with the specified tag.When no , 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.You can use this option to override any existing node affinity settings in the VM config. | yes OR no | |
--scheduler | (Only available in direct mode) Sets which scheduler to use when deploying VMs from the config. 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. | default OR most-allocated |
Check the status of a VM
Command
Get deployment status and system information for the specified VM. If you are running this command in administrative mode, you can get the status for another user's VM.
orka vm status
OR
orka vm status -v <NAME> -y
OR
orka vm status -v <VM_ID> -y
Output
Options
You can pass the following options with orka vm status
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | The name or ID of the VM. | myorkavm |
--raw | Returns the output of the command in raw, greppable format. |
Attach non-bootable disk
Command
Attach a non-bootable disk to the specified VM. The disk must be listed by the orka image list
command.
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
orka vm attach-disk
OR
orka vm attach-disk -v <VM_ID> -d <ADDITIONAL_STORAGE> -y
OR (if attaching a second or a third image to this VM)
orka vm attach-disk -v <VM_ID> -m <MOUNT_POINT> -d <ADDITIONAL_STORAGE> -y
Output
Options
You can pass the following options with orka vm attach-disk
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | The ID of the VM to which you want to attach the disk. | 99f88fc195d49 |
--mount-point | -m | The mount point to which you want to attach the disk. Valid values are in the sd[c-z] format. The mount point must not be in use. | sdc sdd sde |
--disk | -d | The name of the disk image that you want to attach. The image must be listed by the orka image list command. | myemptystorage.img |
List VM disks
Command
List the disks attached to the specified VM. You must specify the VM by ID.
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
orka vm list-disks
OR
orka vm list-disks -v <VM_ID> -y
Output
Options
You can pass the following option with orka vm list-disks
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | The ID of the VM for which you want to list attached disks. | 99f88fc195d49 |
--raw | Returns the output of the command in raw, greppable format. |
Stop, start, suspend, or resume a VM
Commands
Stop, start, suspend, or resume the specified VM. You can specify a VM by name and node, or by ID.
Known limitation
These commands are applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
orka vm [stop / start / suspend / resume]
OR
orka vm [stop / start / suspend / resume] -v <NAME> -n <NODE> -y
OR
orka vm [stop / start / suspend / resume] -v <VM_ID> -y
Options
You can pass the following options with orka vm stop
, orka vm start
, orka vm suspend
and orka vm resume
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | The name or the ID of the VM. When you specify a VM by name, you need to provide a node as well. | myorkavm 99f88fc195d49 |
--node | -n | The node on which the VM resides. | macpro-1 |
Revert VM
Command
Revert VM to the latest state of its base image. This operation restarts the VM. You can specify a VM by name, name and node, or by ID.
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
orka vm revert
OR
orka vm revert -v <NAME> -n <NODE> -y
OR
orka vm revert -v <VM_ID> -y
Output
Options
You can pass the following options with orka vm revert
in direct mode:
Option | Shorthand option | Description | Example |
---|---|---|---|
--vm | -v | The name or the ID of the VM. When you specify a VM by name and there are multiple VMs with that name, you need to provide a node as well. | myorkavm b45f105cd0789 |
--node | -n | The node on which the VM resides. | macpro-1 |
Save VM State
Command
Save the state (disk and memory) of the specified deployed VM. The VM should be running. The VM state is associated with the respective VM configuration. Every VM you deploy from the VM configuration after this operation, will use the saved VM state to boot. For more information, see Optimize VM Startup Time.
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
orka vm save-state
OR
orka vm save-state -v <VM_ID> -y
OR
orka vm save-state -v <VM_ID> --json
Output
Delete VM State
Command
Delete the saved state (disk and memory) of the specified VM configuration. Every VM you deploy from the VM configuration after this operation, will use the base image to boot. For more information, see Optimize VM Startup Time.
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
orka vm delete-state
OR
orka vm delete-state -v <VM_ID> -y
Output
Delete VM
Command
Remove the specified deployed VM(s) but retain the respective VM configuration. You will be able to continue deploying VMs from the VM configuration.
orka vm delete
OR (delete all VMs with the specified name)
orka vm delete -v <NAME> -y
OR (delete all VMs with the specified name from the specified node)
orka vm delete -v <NAME> -n <NODE> -y
OR (delete all VMs with the specified ID)
orka vm delete -v <VM_ID> -y
Is your VM instance in an ERROR state?
Always delete VMs in an
ERROR
state by ID.
Output
Options
You can pass the following options with orka vm delete
in direct mode:
Option | Shorthand option | Description | Sample value |
---|---|---|---|
--vm | -v | The name or ID of the VM that you want to delete. | myorkavm b45f105cd0789 |
--node | -n | The node from which you want to delete the specified VM. | macpro-1 |
Purge VM
Command
Delete all deployed VMs with the specified name and the respective VM configuration. You will not be able to continue deploying VMs from the VM configuration.
orka vm purge
OR
orka vm purge -v <NAME> -y
Output
Options
You can pass the following options with orka vm purge
in direct mode:
Option | Shorthand | Description | Sample value |
---|---|---|---|
--vm | -v | The name of the VMs and their respective VM configuration. | myorkavm |
Updated over 1 year ago