Accessing the VM metadata service (and user data fields) from within the VM

The metadata service lets a VM access its metadata without communicating with the public REST API. This capability is useful in automation scenarios, where an application or a script running inside the VM needs metadata to configure itself. You can also customize select metadata fields to pass custom data or scripts to a VM.

The metadata service can only be used on VMs attached to automatic networks.

Metadata overview

Every VM has Skytap metadata associated with it. The metadata describes the characteristics of the VM (such as VM name, hardware and network settings, labels). The metadata also includes two user data fields that you can customize to pass additional data or scripts to the VM.

This metadata presented to the VM is the REST representation of the VM, similar to what is obtained from the Skytap REST API.

Accessing the metadata service

The metadata service must be accessed from within the VM.

To retrieve the VM metadata, make an HTTP GET request to one of the following addresses:

http://gw/skytap; the hostname gw automatically maps to the gateway IP address.
http://<network-gateway-IP-address>/skytap; for example, if the gateway IP address is 10.0.0.254, use http://10.0.0.254/skytap. For help, see Finding the network gateway IP address.

Metadata service is also always available at a link-local address: http://169.254.169.254/skytap.

Sample request and response:

GET http://gw/skytap

{
    "id": "123456",
    "name": "Database Server",
    ...
    "user_data": "Here is the VM user data.",
    "configuration_user_data": "Here is the environment user data."
}

By default, the response is formatted in JSON. However, you can also provide an Accept header of “application/xml” if you prefer XML format.

Entering custom metadata (user data)

Each VM has access to two Metadata fields. These are free-form text fields you can use to pass custom data to the VM as part of the metadata service.

Each VM has a unique user_data field, which can be edited to include information or scripts that are specific to that VM. For instance, you can pass connection strings for databases to the database component, or pass entire scripts that you need to run on the VM.
The VM also has access to the environment’s configuration_user_data field, which can be edited to include information or scripts that need to be shared across all VMs in the environment.

Editing VM metadata

Edit the VM user_data field from the VM Settings page or from the Environment VMs resource in the REST API. The data you enter here is returned in any metadata request as the user_data element of the VM metadata.

This field is limited to 16,384 characters.

VM Settings - metadata

Editing environment metadata

Edit the environment configuration_user_data field from the Environment Settings page or from the Environments resource in the REST API. The data you enter here is returned in any metadata request as the configuration_user_data element in the metadata representation of the VM.

This field is limited to 16,384 characters.

Environment Settings - metadata

Example workflow that uses the metadata service

For an example workflow that uses the metadata service and user data fields, see Getting started with Puppet in Skytap. In this workflow, a startup script triggers a GET request to the VM metadata service. Information in the user data field helps the Puppet agent VMs call back to the Puppet master VM for additional configuration information.