GuidesAPI ReferenceJoin the Mailing List

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 keyDescription
`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.


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.


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.

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

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