VMs
How to create, manage, and remove VMs and VM configurations with the Orka CLI.
Orka 2.4.x content
This page has not been updated to reflect the changes introduced in Orka 3.0. Some of the information might be outdated or incorrect. Use 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping to figure out the correct endpoints and commands.
This page discusses VM workflows in the Orka CLI. For more information about VM workflows with the Orka API, see Orka API Reference: VMs.
Quick navigation
Jump to: Create and deploy VMs | Basic VM actions | Advanced VM actions
Quick command summary
Orka CLI
orka vm create-config orka vm deploy orka vm create orka node list orka vm list orka vm [stop / start / suspend / resume] orka vm revert orka vm delete orka vm purge
Orka API
POST /resources/vm/create POST /resources/vm/deploy GET /resources/node/list GET /resources/vm/list POST /resources/vm/exec/stop POST /resources/vm/exec/start POST /resources/vm/exec/suspend POST /resources/vm/exec/resume POST /resources/vm/exec/revert DEL /resources/vm/delete DEL /resources/vm/purge
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.
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. 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.
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
curl --location 'http://<ORKA_API_IP>/resources/vm/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>",
"orka_base_image": "<IMAGE>",
"orka_image": "<VM_NAME>",
"orka_cpu_core": <CPU_AMOUNT>,
"vcpu_count": <VCPU_AMOUNT>
}'
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
curl --location 'http://<ORKA_API_IP>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>"
}'
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 combinesorka vm create-config
andorka 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
curl --location 'http://<ORKA_API_IP>/resources/node/list' \
--header 'Authorization: Bearer <TOKEN>'
CPU utilizitation
Intel-based VMs require fewer cores during deployment (scheduling) than the amount specified in the configuration. For example, Orka might be able to deploy a 24-CPU VM on a node with 22 free CPU.
After the deployment is complete, the Intel-based VM will use up the complete amount of the configured CPU.
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
curl --location 'http://<ORKA_API_IP>/resources/vm/list' \
--header 'Authorization: Bearer <TOKEN>'
Stop VM
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
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
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/stop' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_ID>"
}'
OR
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/stop' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>",
"orka_node_name": "<NODE_NAME>"
}'
Start VM
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
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
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/start' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_ID>"
}'
OR
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/start' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>",
"orka_node_name": "<NODE_NAME>"
}'
Suspend VM
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
Suspend a running VM.
orka vm suspend
OR
orka vm suspend -v <NAME> -n <NODE> -y
OR
orka vm suspend -v <VM_ID> -y
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/suspend' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_ID>"
}'
OR
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/suspend' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>",
"orka_node_name": "<NODE_NAME>"
}'
Resume VM
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
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
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/resume' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_ID>"
}'
OR
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/resume' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>",
"orka_node_name": "<NODE_NAME>"
}'
Revert VM
Known limitation
This command is applicable only to Intel-based VMs.
For more information, see Apple Silicon-Based Support.
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.
TIP: 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
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/revert' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_ID>"
}'
OR
curl --location 'http://<ORKA_API_IP>/resources/vm/exec/revert' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>",
"orka_node_name": "<NODE_NAME>"
}'
Advanced VM actions
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
curl --location --request DELETE 'http://<ORKA_API_IP>/resources/vm/delete' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_ID>"
}'
OR
curl --location --request DELETE 'http://<ORKA_API_IP>/resources/vm/delete' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>"
}'
OR
curl --location --request DELETE 'http://<ORKA_API_IP>/resources/vm/delete' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>",
"orka_node_name": "<NODE_NAME>"
}'
TIP: 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
curl --location --request DELETE 'http://<ORKA_API_IP>/resources/vm/purge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"orka_vm_name": "<VM_NAME>"
}'
See also
Updated 11 months ago