VMs

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]

Create and deploy VMs

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

OR

orka vm create-config -v <NAME> -b <IMAGE_NAME> -c <CPU_COUNT> -C <vCPU_COUNT> --json

📘
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.

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

OR

orka vm deploy -v <NAME> --json

👍
TIP: How to spin up a new VM with a single command
Use orka vm create if you want to create a VM configuration and deploy it immediately. This command combines orka vm create-config and 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.

Basic VM actions

List VMs

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 Not Deployed.

orka vm list

Stop VM

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 stop -v <VM_ID> -y

OR 

orka vm stop -v <NAME> -n <NODE> --json

OR

orka vm stop -v <VM_ID> --json

Start VM

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

OR

orka vm start -v <NAME> -n <NODE> --json

OR

orka vm start -v <VM_ID> --json

Suspend VM

Suspend a running VM.

orka vm suspend 

OR

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

OR

orka vm suspend -v <VM_ID> -y

OR

orka vm suspend -v <NAME> -n <NODE> --json

OR

orka vm suspend -v <VM_ID> --json

Resume VM

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

OR

orka vm resume -v <NAME> -n <NODE> --json

OR

orka vm resume -v <VM_ID> --json

Revert VM

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

OR

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

OR

orka vm revert -v <VM_ID> --json

Advanced VM actions

Clone VM

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

OR

orka vm clone -v <VM_ID> -n <CURRENT_NODE> --to-node <DESTINATION_NODE> --json

Migrate VM

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

OR

orka vm migrate -v <VM_ID> -n <CURRENT_NODE> --to-node <DESTINATION_NODE> --json

Delete VM

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

OR

orka vm delete -v <NAME> --json

OR

orka vm delete -v <NAME> -n <NODE> -json

OR

orka vm delete -v <VM_ID> --json

📘
Is your VM instance in an ERROR state?
Always delete VMs in an ERROR state by ID.

Purge VM

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

OR

orka vm purge -v <NAME> --json

OR

orka vm purge -v <NAME> -n <NODE> --json

OR

orka vm purge -v <VM_ID> --json