This page discusses VM workflows in the Orka CLI. For more information about VM workflows with the Orka API, see Orka API Reference: VMs.
On this page, you will learn how to:
- Create VM configurations and deploy VMs.
- Perform basic VM operations such as start, stop, suspend, and resume.
- Perform more advanced VM operations such as delete, purge, and migrate.
A VM configuration is a template configuration (a container template) consisting of a base image, a snapshot image, and the number of CPU cores to be used. To become a VM that you can run in the cloud, a VM configuration needs to be deployed to a node.
A VM is a virtual machine deployed on a node from an existing VM configuration or cloned from an existing virtual machine. In the case of macOS VMs, this is a full macOS VM inside of a Docker container.
You can deploy multiple VMs from a single VM configuration. Once created, you can no longer modify a VM configuration.
Quick command summary
orka vm create-config
orka vm deploy [specify node]
orka vm create
orka node list
orka vm list
orka vm [stop / start / suspend / resume]
orka vm revert
orka vm clone
orka vm migrate
orka vm [delete / purge]
- To create a VM configuration from which you can spin up VMs, run the following command.
orka vm create-config OR orka vm create-config -v <NAME> -b <IMAGE_NAME> -c <CPU_COUNT> -C <vCPU_COUNT> -y
VM name limitations
The name you specify under
VM Namemust 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.
- To spin up a VM from the configuration, run the following command. You can leave the Node name empty. This lets Orka determine a node on its own. You can also skip filling in the remaining optional fields to attach an ISO, an additional disk, and to enable or disable VNC (enabled by default).
orka vm deploy OR orka vm deploy -v <NAME> -y
TIP: How to spin up a new VM with a single command
orka vm createif you want to create a VM configuration and deploy it immediately. This command combines
orka vm create-configand
orka vm deploy.
If you want to deploy the VM on a specific node, you can set Node name. However, the node must have enough free resources to accommodate the VM. To check the available nodes, run the following command.
orka node list
VM cores needed
VMs require fewer cores to operate than the specified during configuration but will use up to their max if the cores are free. For example, a VM with 24 CPU specified only requires 22 CPU to be shown as available, but will use up to 24 if they are free.
Hence, you might still be able to deploy a VM even if the listed available CPU is less than the specified in the VM configuration.
List all VMs that you have created in your Orka environment. VM configurations that don't have any VMs deployed from them are listed as
orka vm list
Fully stop the VM. This operation is equal to hitting the power button on a physical machine.
orka vm stop OR orka vm stop -v <NAME> -n <NODE> -y OR orka vm start -v <VM_ID> -y
Start a completely stopped VM. This operation is equal to turning a physical machine on from the power button.
orka vm start OR orka vm start -v <NAME> -n <NODE> -y OR orka vm start -v <VM_ID> -y
Suspend a running VM.
orka vm suspend OR orka vm suspend -v <NAME> -n <NODE> -y OR orka vm suspend -v <VM_ID> -y
Resume a suspended VM, putting it into a running state.
orka vm resume OR orka vm resume -v <NAME> -n <NODE> -y OR orka vm resume -v <VM_ID> -y
Revert a VM to the latest state of its base image. This operation restarts the VM.
As opposed to redeploying a VM from its initial configuration, this operation preserves the VM IP and connection ports.
What if the base image was modified?
In this case, the VM will revert to the current state of the base image. For example, if changes were committed to the base image (such as adding new files to the Desktop), the reverted VM will also have these changes.
orka vm revert OR orka vm revert -v <NAME> -n <NODE> -y OR orka vm revert -v <VM_ID> -y
Clone a VM to the same or another node. The node must provide enough resources to accommodate the clone.
The clone receives a new ID and might receive a new IP and new ports, based on the destination node.
orka vm clone OR orka vm clone -v <VM_ID> -n <CURRENT_NODE> --to-node <DESTINATION_NODE> -y
Move a VM to another node. The destination node must provide enough resources to accommodate the VM.
This operation removes the clone from the source node. On the destination node, the VM receives a new IP and might be assigned new ports.
orka vm migrate OR orka vm migrate -v <VM_ID> -n <CURRENT_NODE> --to-node <DESTINATION_NODE> -y
Delete a VM. You can specify VM name (deletes all VMs with that name) or VM ID (deletes the specified VM only). You can also specify a node that the VM occupies to further limit the operation.
This operation stops the VM, frees up the associated Orka resources, and retains the VM configuration.
orka vm delete OR orka vm delete -v <NAME> -y OR orka vm delete -v <NAME> -n <NODE> -y OR orka vm delete -v <VM_ID> -y
Is your VM instance in an ERROR state?
Always delete VMs in an
ERRORstate by ID.
Delete all VMs with the specified name and the associated VM configuration.
This operation stops the VMs with the specified name, frees up the associated Orka resources, and removes the VM configuration.
orka vm purge OR orka vm purge -v <NAME> -y OR orka vm purge -v <NAME> -n <NODE> -y OR orka vm purge -v <VM_ID> -y
Updated 2 months ago