GuidesAPI Reference
Guides
Join the Mailing List

VMs

How to create, manage, and remove VMs and VM configurations with the Orka CLI.

Suggest Edits

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

  1. 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.
2276
  1. 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>"
}'
2276

👍

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

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>'
1700

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>"
}'
2450

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>"
}'
2450

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>"
}'
2514

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>"
}'
2514

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>"
}'
2514

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>"
}'
2514

👍

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>"
}'
2514

See also

Updated over 1 year ago

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