Guides
GuidesAPI ReferenceJoin the Mailing ListMake a Suggestion

VMs

The orka vm group of commands in the Orka CLI. These commands are used for VM and VM configuration management.

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 <USER>

Output

3512

Options

You can pass the following option with orka vm configs in direct mode:

OptionShorthand optionDescriptionSample value
--filter-fList the VM configuration with the specified name. The specified name must be an exact match for the VM configuration you're looking for.myorkavm
--jsonReturns the output of the command in JSON.
--rawReturns 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

3282

Options

You can pass the following options with orka vm list in direct mode:

OptionShorthand optionDescriptionSample value
--filter-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]
--jsonReturns the output of the command in JSON.
--expandReturns a list of all your VM configs and VMs, including any replicas.
--rawReturns 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 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 <SCHEDULER> -y

Output

1132

πŸ“˜

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

You can pass the following options with orka vm create-config in direct mode:

OptionShorthand optionDescriptionSample value
--vm-vA 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-bThe base image that you want to use for the VM.Mojave.img
--cpu-cThe number of CPU cores for the VM.3
--vcpu-CThe 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-MThe amount of memory in Gigabytes.

Must not exceed 32GB on 32GB nodes, and 60GB on 64GB and 128GB nodes.

If not specified, defaults to a calculated value based on the "weakest" node.
24
--iso-iAttaches the specified ISO. You must provide the name of the ISO.

* Intel nodes only.
Catalina.iso
--disk-dAttaches the specified storage. You must provide the image name.

* Intel nodes only.
myemptystorage.img
--vncEnables or disables VNC access when running orka vm deploy.yes OR no
--io-boostEnables or disables IO performance boost for your VMs.

* Intel nodes only.
yes OR no
--net-boostEnables or disable Network performance boost for your VMs.

* Intel nodes only
yes OR no
--gpuWith environments that have GPU passthrough enabled, enables or disables GPU passthrough for a vm.

* Intel nodes only.
yes OR no
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.
--tagRequests deployment to a node with a specific tagpool-1
--tag-requiredSets whether or not the VM must deploy to the requested tag. Defaults to no.yes OR no
--scheduler(Only available in direct mode)
Sets the scheduler to be used when deploying VMs from the config. default scheduler schedules the VMs in way that keeps used and free resources balanced between the nodes. most-allocated scheduler schedules the VMs in way that uses resources from one node first before starting scheduling to the other nodes.
default OR most-allocated
  • This option is supported or applicable to Intel-based nodes only. Read more about Apple ARM-based Support to see which commands and options are supported for Apple ARM-based nodes.

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_IN_GB> -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 Net 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 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 <SCHEDULER> -y

Output

794

Options

You can pass the following options with orka vm create in direct mode:

OptionShorthand optionDescriptionSample value
--vm-vA 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-bThe base image that you want to use for the VM.Mojave.img
--cpu-cThe number of CPU cores for the VM.3
--vcpu-CThe 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-MThe amount of memory in Gigabytes.

Must not exceed 32GB on 32GB nodes, and 60GB on 64GB and 128GB nodes.

If not specified, defaults to a calculated value based on the "weakest" node.
24
--node-nThe node on which to deploy the VM. The specified node must have sufficient free computational resource to accommodate the VM.

To let Orka choose a node, leave blank.
macpro-1
--iso-image-iAttaches the specified ISO. You must provide the name of the ISO.

* Intel nodes only.
Catalina.iso
--disk-dAttaches the specified storage. You must provide the image name.

* Intel nodes only.
myemptystorage.img
--vncEnables or disables VNC access (and port mapping) for the VM configuration. You can override the setting when running orka vm deploy.yes OR no
--io-boostEnables or disables IO performance boost for your VMs.

* Intel nodes only.
yes OR no
--net-boostEnables or disables Network performance boost for your VMs.

* Intel nodes only.
yes OR no
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.
--tagRequests deployment to a node with a specific tagpool-1
--tag-requiredSets whether or not the VM must deploy to the requested tag. Defaults to no.yes OR no
--scheduler(Only available in direct mode)
Sets the scheduler to be used when deploying VMs from the config. default scheduler schedules the VMs in way that keeps used and free resources balanced between the nodes. most-allocated scheduler schedules the VMs in way that uses resources from one node first before starting scheduling to the other nodes.
default OR most-allocated
  • This option is supported or applicable to Intel-based nodes only. Read more about Apple ARM-based Support to see which commands and options are supported for Apple ARM-based nodes.

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 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 <SCHEUDLER> -y

Output

1200

Options

You can pass the following options with orka vm deploy in direct mode:

OptionShorthand optionDescriptionSample value
--vm-vThe name of the VM configuration that you want to deploy.myorkavm
--node-nThe node on which to deploy the VM. The specified node must have sufficient free computational resource to accommodate the VM.

To let Orka choose a node, leave blank.
macpro-1
--replicas-rThe 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).

* Intel nodes only.
3
--iso-image-iAttaches the specified ISO. You must provide the name of the ISO.

* Intel nodes only.
Catalina.iso
--disk-dAttaches the specified storage. You must provide the image name.

* Intel nodes only.
myemptystorage.img
--vncEnables or disables VNC access (and port mapping) for the VM configuration.

You can override the VNC setting of the VM configuration.
yes OR no
--ports-p(Only available in direct mode) Opens an additional port on the VM. 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>

* Intel nodes only.
1337:3000
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.
--tagRequests deployment to a node with a specific tagpool-1
--tag-requiredSets whether or not the VM must deploy to the requested tag. Defaults to no.yes OR no
--scheduler(Only available in direct mode)
Sets the scheduler to be used when deploying VMs from the config. default scheduler schedules the VMs in way that keeps used and free resources balanced between the nodes. most-allocated scheduler schedules the VMs in way that uses resources from one node first before starting scheduling to the other nodes.
default OR most-allocated
  • This option is supported or applicable to Intel-based nodes only. Read more about Apple ARM-based Support to see which commands and options are supported for Apple ARM-based nodes.

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

307

Options

You can pass the following options with orka vm status in direct mode:

OptionShorthand optionDescriptionSample value
--vm-vThe name or ID of the VM.myorkavm
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.

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.

🚧

Apple ARM-based nodes support

This command is not supported for Apple ARM-based nodes.
Read more about Apple ARM-based Support to see which commands and options are supported.

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

778

Options

You can pass the following options with orka vm attach-disk in direct mode:

OptionShorthand optionDescriptionSample value
--vm-vThe ID of the VM to which you want to attach the disk.b45f105cd0789
--mount-point-mThe 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-dThe name of the disk image that you want to attach. The image must be listed by the orka image list command.myemptystorage.img
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.

List VM disks

Command

List the disks attached to the specified VM. You must specify the VM by ID.

🚧

Apple ARM-based nodes support

This command is not supported for Apple ARM-based nodes.
Read more about Apple ARM-based Support to see which commands and options are supported.

orka vm list-disks

OR

orka vm list-disks -v <VM_ID> -y

Output

1514

Options

You can pass the following option with orka vm list-disks in direct mode:

OptionShorthand optionDescriptionSample value
--vm-vThe ID of the VM for which you want to list attached disks.b45f105cd0789
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.
--rawReturns 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.

🚧

Apple ARM-based nodes support

These commands are not supported for Apple ARM-based nodes.
Read more about Apple ARM-based Support to see which commands and options are supported.

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:

OptionShorthand optionDescriptionSample value
--vm-vThe name or the ID of the VM. When you specify a VM by name, you need to provide a node as well.myorkavm

b45f105cd0789
--node-nThe node on which the VM resides.macpro-1
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.

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.

🚧

Apple ARM-based nodes support

This command is not supported for Apple ARM-based nodes.
Read more about Apple ARM-based Support to see which commands and options are supported.

orka vm revert

OR

orka vm revert -v <NAME> -n <NODE> -y

OR

orka vm revert -v <VM_ID> -y

Output

1200

Options

You can pass the following options with orka vm revert in direct mode:

OptionShorthand optionDescriptionExample
--vm-vThe 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-nThe node on which the VM resides.macpro-1
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.

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.

🚧

Apple ARM-based nodes support

This command is not supported for Apple ARM-based nodes.
Read more about Apple ARM-based Support to see which commands and options are supported.

orka vm save-state

OR

orka vm save-state -v <VM_ID> -y

OR

orka vm save-state -v <VM_ID> --json

Output

1828

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.

🚧

Apple ARM-based nodes support

This command is not supported for Apple ARM-based nodes.
Read more about Apple ARM-based Support to see which commands and options are supported.

orka vm delete-state

OR

orka vm delete-state -v <VM_ID> -y

Output

1906

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

1514

Options

You can pass the following options with orka vm delete in direct mode:

OptionShorthand optionDescriptionSample value
--vm-vThe name or ID of the VM that you want to delete.myorkavm

b45f105cd0789
--node-nThe node from which you want to delete the specified VM.macpro-1
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.

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

1514

Options

You can pass the following options with orka vm purge in direct mode:

OptionShorthandDescriptionSample value
--vm-vThe name of the VMs and their respective VM configuration.myorkavm
--assume-yes-yBypasses the interactive prompt and executes the command with the specified parameters.
--jsonReturns the output of the command in JSON.

Β© 2019-2023 Copyright MacStadium, Inc. – Documentation built with readme.com. Orka is a registered trademark of MacStadium, Inc.