I recently have been exploring a really neat feature in the vCloud API (introduced in vCloud Director 1.5) which allows users to create custom metadata (key/value pair) for various objects such as a Virtual Machine, vApp, Provider vDC, etc. in vCloud Director.
Here are two possible use cases for using the metadata feature:
When a new vApp is requested, there is generally some associated “business” or “environmental” information such as the purpose, requestor, asset tag, ticket number, contact information, etc. with the new vApp request. This information can not easily be associated with the vApp other than selecting a descriptive name for the new vApp during deployment. You would normally rely on an external system to store all this additional information and it may require access to several systems to get the all details for a given vApp. By having the ability to associate additional metadata information, it provides a single location for administrators/users to get complete details about their vApps. It also provides for an easy way to create custom reports that can be used during support triages or general inventory reporting, all within vCloud Director.
Administrators can also benefit from the use of metadata tags as way to perform batch operations on specific vCloud Director objects. Let’s say we have a metadata tag called “business-unit” and all vApps are tagged with their respective business units and we received a request to power off all vApps for the Marketing group. Administrators can now easily check the metadata for all vApps that are owned by a specific business unit and perform the operation without having to correlate which users are in the business unit and who owns a vApp. Additionally, administrators can also tag vCloud objects such as a Provider vDC or Organization vDC and leverage these tags in their provisioning logic for placing specific workloads. An example of this could be metadata defining site, location, SLA level, service provider, etc. that an administrator can use when deciding where to deploy a new vApp.
This metadata feature is currently only available using the vCloud API which can also be accessed through one of our three vCloud SDKs (Java, .NET, and PHP) as well as using the vCloud Director cmdlets and the vCloud Director vCO Plugin.
Users can create, update or delete metadata on a variety of vCloud Director objects. Below is a table of the objects and their associated user context (tenant or provider) for metadata creation. Users will need the edit permission on an object to be able to modify the metadata. Without the edit permission, the information will be marked as ‘read-only’ for that user and will not be modifiable.
Note: When copying/cloning a vApp, vAppTemplate or Media, all associated metadata is also copied.
Below is an example of creating custom metadata for a vApp using curl and the vCloud API. If you are not familiar with the vCloud API, take a look here and here for an introduction on using the vCloud API.
To check whether a vCloud Director object has any existing metadata, you can perform GET operation on the href metadata URL of a given object: https://vcloud-url/api/[vcloud-object]/metadata
Create Metadata for vApp
You will need the href URL for the vApp you are interested in creating a metadata entry for and a file containing the request body which contains a list of the key/value entry(s) which support full Unicode character set. In this example, we will create a file called metadata-request that contains the following 4 key/value pairs:
Note: Case-sensitivity for the metadata key is based on the vCloud Director backend database. If you are using an Oracle DB, the metadata key is case-sensitive, but if you are using a MSSQL DB, the metadata key is case-insensitive. An example of case-sensitivity is if you have a metadata key called “app-owner” and “App-owner”, both of these would be considered different entries. It should be a best practice to form a naming standard and whether or not upper/lowercase is used.
As per the vCloud API documentation for a vApp, we will be performing a POST operation to create the new metadata:
We can also retrieve a specific metadata key, by specifying metadata URL with the key. In this example, we are extracting the value for the “asset-tag” key:
If you want to update an existing metadata entry, we just need to perform a PUT operation along with the request body of the changed value. In this example, we will create a file called metadata-request that contains a new value for our metadata key “asset-tag”:
There are a few things to keep in mind when working with metadata in vCloud Director and their limits, please refer to the vCloud API Metadata section for more details.
As you can see, the new metadata feature can be quite useful if you need to add custom data to objects within vCloud Director and not have to rely on an external system to store and retrieve this information. The possibilities are endless on how you can leverage this feature in your own environment.
Get notification of new blog postings and more by following lamw on Twitter: @lamw
