VM Metadata
How to work with Orka VM metadata.
Intel Nodes Only
This guide is applicable to VMs deployed on Intel nodes only. Read more about Apple ARM-based Support (Beta) to see which commands and options are supported for VMs deployed on Apple ARM-based nodes.
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, 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.
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.
Default metadata key | Description |
---|---|
orka_vm_id | The VM ID. This is a unique ID that is generated and assigned by Orka. |
orka_vm_name | The VM name, as specified by the VM configuration. |
orka_node_name | The name of the node where the VM is deployed. |
orka_base_image | The base image used by the VM. |
orka_cpu | The number of CPUs for the VM. |
orka_memory | The RAM memory for the VM. |
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
- Connect to your cluster via VPN. For more information, see VPN Connection
- Make sure you have a VM configuration with enabled VNC, SSH, or Screen Sharing. See VNC, SSH and Screen Sharing for Orka Vms .
- Send a POST request to
http://<orka-api-url>/resources/vm/deploy
with thevm_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-url>/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>" }] }
}'
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
- Pass the VM metadata when deploying the build agent instances OR use a permanent agent already deployed with VM metadata.
- Retrieve the metadata as part of your CI/CD workflow.
- Use the metadata values as needed to identify or manage the build agents.
What's next
Retrieve the VM metadata.
Updated over 1 year ago