VM Metadata

🚧

Quick navigation

Jump to:

Default VM metadata | Custom VM metadata | Limitations | Deploy a VM with custom metadata | Other VM related operations | How to use VM metadata in CI/CD

Starting with Orka 1.5.0 for Intel-based VMs and Orka 2.2.0 for ARM-based VMs, when you deploy a VM, Orka assigns default metadata to the VM. You can also add your own custom metadata during deployment. With VM metadata, you have more ways to identify and manage running VMs (in addition to the data visible with list and status operations).

Metadata is stored in the format {"key": "my key", "value": "my value"}. Every VM stores its metadata on a metadata server. You can query this metadata server to retrieve the metadata only from within the VM.

📘

IMPORTANT

To use VM metadata with Apple ARM-based VMs you need to use the latest version of Orka VM Tools. It comes out of the box with the latest .orkasi images.

You can also install it manually. For more information, see the downloads page.

Default VM metadata

Orka always defines a set of default metadata entries that provide information about your VM. Every VM has access to its default VM metadata.

All default metadata keys (reserved keys) are prefixed with orka_.

Custom VM metadata

Custom metadata is stored in the format {"key": "my key", "value": "my value"}. Usually, custom metadata is useful for passing in string values to your VM.

📘

IMPORTANT

You can set custom VM metadata only via the Orka API.
The metadata applies only to a specific instance.

Limitations

• Orka enforces a combined total limit of 100 KB for all body parameters.
• After a VM is deployed with a particular set of metadata, you can no longer edit the VM metadata.
• You cannot override the default VM metadata.
• VM metadata is available only for VMs deployed after updating to Orka 1.5.0 or later.

📘

IMPORTANT

Do not store sensitive data, such as passwords or long-lived encryption keys, as VM metadata.

Although accessible only from within the VM, the VM metadata is not protected by authentication or cryptographic methods. Anyone with direct access to the VM, and potentially any software running on the VM, can query and view the metadata.

Deploy a VM with custom metadata

1. Connect to your cluster via VPN. For more information, see VPN Connection
2. Make sure you have a VM configuration with enabled VNC, SSH, or Screen Sharing. See VNC, SSH and Screen Sharing for Orka Vms .
3. Send a POST request to http://<orka-api-url>/resources/vm/deploy with the vm_metadata option in the body of the request. Replace the <my_metadata_key> and <my_metadata_value> placeholders as needed.

curl --location -g --request POST 'http://<orka-api-ip>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_vm_name": "<vm-name>",
	"vm_metadata": { "items": [{"key": "<my metadata key>", "value": "<my metadata value>" }] }
}'

Replace with 10.221.188.20, 10.221.188.100 or your custom domain.

How other VM-related operations affect VM metadata

• migrate - Orka preserves your custom VM metadata when migrating a VM to another node.
• scale - Orka sets your custom VM metadata to all replicas. This is applicable only to VMs deployed with Orka 1.5.0 or later.
• revert - Orka preserves the custom VM metadata.
• start/ stop/ suspend/ resume - These operations do not affect your VM metadata.
• clone - Orka does not persist your custom VM metadata when cloning a VM. Your custom VM metadata will be lost and the default metadata might be overriden.
• image save - The VM metadata is not stored as part of the base image and will not be available to other VMs deployed from this image.
• image commit - The VM metadata is not stored as part of the base image and will not be available to other VMs deployed from this image.

How to use VM metadata in CI/CD

1. Pass the VM metadata when deploying the build agent instances OR use a permanent agent already deployed with VM metadata.
2. Retrieve the metadata as part of your CI/CD workflow.
3. Use the metadata values as needed to identify or manage the build agents.

What's next

Retrieve the VM metadata.