The Brinkster Cloud Orchestrator metadata service allows customers and image providers to supply data to running Virtual Machines and to the subsequent users of the API.
Classes of metadata
Metadata falls into 4 classes: public, restricted, private and system. The difference between these classes of metadata is who may access them and how. Public metadata may be read through the API by anyone who has permission to make the API call concerned, whereas restricted and private metadata can only be read through the API by the owner of the object to which the metadata is attached. Public and restricted metadata is presented to the VM (in addition to being made available in the API in the manner described above), whereas private metadata is not presented to the VM.
For example, Joe User is using an image provided by ImageCorp. ImageCorp’s image is set up to disable VNC access and with no user logins (i.e. it is an appliance). ImageCorp wishes to provide metadata (e.g. a shared secret) to the VM, but does not wish Joe to be able to read this. ImageCorp thus sets the metadata as restricted.
System metadata is read-only; it is created by Brinkster Cloud Orchestrator and cannot be set by the user; it is available to the VM and can be read through the API (but not written) only by the user owning the object, i.e. it behaves like read-only restricted metadata. This means (using the above example) that Joe User cannot read ImageCorp’s image’s system metadata using the API, even when the image is running on Joe’s virtual machine.
This is represented in tabular form as follows:
| Available to the VM | Yes | Yes | No | Yes |
| Customer can read using API if customer owns object | Yes | Yes | Yes | Yes |
| Customer can write using API if customer owns object | Yes | Yes | Yes | No |
| Customer can read using API if object not owned by customer | Yes | No | No | No |
| Customer can write using API if object not owned by customer | No | No | No | No |
Metadata of any class can be attached to customers, servers, images, and runtime instance. Private, public and restricted metadata attached to any of these types may be set and read through the API. Read-only metadata may be read through the API, but not written.
- Metadata attached to a customer (unless it is private) is presented to all VMs of that customer. Customer metadata is set and read through the SetCustomerMetadata andGetCustomerMetadata API calls.
- Metadata attached to a server (unless it is private) is presented to any running instance of that server (and will persist across a stop and start). Server metadata is set and read through the SetServerMetadata and GetServerMetadata API calls.
- Metadata attached to a runtime instance of a server (unless it is private) is presented to that runtime instance of that server (and will not persist across a stop and start). Runtime metadata is set through the StartServer or CreateServerScheduledJob API calls, and returned through the GetRuntimeMetadata API call.
- Metadata attached to an image (unless it is private) is presented to all VMs using that image; it may be read through the API by the image owner, and, if the image itself is accessible to a given user, may also be read via the API by that user if it is public (but not if it is restricted, private or system). Image metadata is set and read through theGetImageTemplateMetadata and SetImageTemplateMetadata API calls.
The VM can query metadata using a request to the following address:
http://169.254.169.254/metadata
The VM does not need to have an IP route to the metadata server. It will, however, need to be able to resolve DNS queries (if using a host name rather than IP address).
This will return an XML file including a “meta” block at the root level, and beneath that blocks for customer, server, image and runtime. Each of these blocks in turn contains sections for public, restricted and system (as private is not visible). So the format is roughly as follows:
[header information]
<CONFIG>
[other information]
<meta>
<customer>
<public>
[public customer information]
</public>
<restricted>
[restricted customer information]
</restricted>
<system>
[system customer information]
</system>
</customer>
<server>
<public>
[public server information]
</public>
<restricted>
[restricted server information]
</restricted>
<system>
[system server information]
</system>
</server>
<image>
<public>
[public image information]
</public>
<restricted>
[restricted image information]
</restricted>
<system>
[system image information]
</system>
</image>
<runtime>
<public>
[public runtime information]
</public>
<restricted>
[restricted runtime information]
</restricted>
<system>
[system image information]
</system>
</runtime>
</meta>
</CONFIG>
[trailer information]
|
Note that the metadata that can be obtained by a VM is cached, and thus may be out of date. It is only guaranteed to be accurate as at the time of the last server start.
It is up to the image concerned to process this information. It is suggested that one processing route would be to allow a given tag in one section to be overridden by the same tag in another section, for instance to allow image information to be overridden by customer information, in turn to be overridden by server information, and in turn to be overridden by runtime information. However, image providers may not wish customers to be able to override certain image information (particularly information in the restricted class) at all.
Note that whilst the XML should be well formed correctly (i.e. it will parse correctly, will contain only properly encoded characters, the element tags which delimit the elements will be correctly nested and will balance), as there is no DTD for the user specified elements, it will not have been validated against a DTD by Brinkster Cloud Orchestrator.
Contents of the system metadata sections
Whilst the contents of the public, restricted and private sections are a matter solely for the customer and (in the case of Image objects) the image provider, the contents of the System sections are pre-determined. The following is a list of tags which may be added to over time.
| Customer/System | |
| sshkeys | An blob describing the public ssh keys to be added to a server on first boot in the following format: <sshkeys>
<user name="alice">
</user>
<user name="bob">
</user>
<user name="">
</user>
</sshkeys>
|
Each “<key>” line is a line representing an ssh key for the user concerned in the format of authorized_keys. A blank or absent username represents the default username for the image concerned. Note that the above lines have been abbreviated (at the ellipsis) for legibility. |
| Image/System | |
| image | An XML blob of type OperatingSystemImage (note the CanModify field will refer to whether the owner of the image can modify). |
| default_username | The initial user for the image. |
| Server/System | |
| As per GetServer | The Server/System metadata corresponds to the returned XML from the GetServer API call. |
| Runtime/System | |
| Runtime information | Runtime information. Reserved for additions at a later date. |
Note that the XML also contains some elements within “config” other than “meta”. Use of these fields is deprecated.