A neat little feature that I have been exploring with in vCloud Director is Custom Properties for a vApp and Virtual Machine. This was one of the new features in the vCloud Director 1.5 release which allows users to easily pass data into the guest OSes using OVF descriptors. I found the Custom Properties to be a very interesting capability as it allows users to dynamically provision a vApp and present variety of custom data for the guestOS to access such as guestOS customization, asset tag information as well as application startup parameters. This last use case is really cool in my opinion as it allows you to customize how an application should be configured and startup based on some criteria.
Though it may not be apparent on how Custom Properties work, especially if you have seen the empty tab in the vCloud Director UI. Hopefully after this article, you may want to give Custom Properties a try.
As mentioned earlier, Custom Properties are exposed through the use of OVF descriptors stored as a key/value pair. You have two ways of accessing Custom Properties for a vApp/Virtual Machine in vCloud Director.
Modify existing Custom Properties which have already been defined and imported from an OVF into vCloud Director using the vCloud Director UI.
Create new Custom Properties by using the vCloud API’s ProductSection element and then manage them using either the vCloud Director UI or API.
Custom Properties can be defined at the vApp level which will then be cascaded down to all Virtual Machines within the vApp and can also be defined on an individual Virtual Machine. In the example below, we have a vApp called WebApplication which contains contains two Virtual Machines called Loadbalancer-01 and WebServer-01 and they do not contain any Custom Properties. We will walk through the process of creating new Custom Properties for both a vApp and Virtual Machine.
To create Custom Properties at a vApp level, we will be using the PUT operation on a vApp’s /productSections. We will create two Custom Properties called sys_owner and asset_tag which will not be “user configurable” which means the property will not be visible via the vCloud Director UI and can only be set using the vCloud API.
We will need to create a file that contains the request body for the Custom Properties and it’s respective values, in this example I created a file called vapp-custom-properties which looks like the following:
To retrieve the Custom Properties, we just need to perform a GET operation on the /productSections of the vApp and as you can see below, we have our two Custom Properties along with their defined values. You can also create a Custom Property without assigning it a value and modify it later on.
If we take a look at the vCloud Director UI for our vApp, we will see there are no visible Custom Properties, but as we can see from the previous steps, they do exists via the vCloud API.
Next we will take a look at creating a few Custom Properties for a Virtual Machine, you will be using the same PUT operation but for a Virtual Machine’s productSections instead. For the Virtual Machine we will create three Custom Properties: webserver_port, webserver_image and dev_contact which will be “user configurable” and visible via the vCloud Director UI. We will not be assigning any values to these properties.
We will need to create a file that contains the request body for the Custom Properties and it’s respective values, in this example I created a file called vm-custom-properties which looks like the following:
<ProductSectionList xmlns=”http://www.vmware.com/vcloud/v1.5″ xmlns:ovf=”http://schemas.dmtf.org/ovf/envelope/1″> <ovf:ProductSection ovf:required=”true”> <ovf:Info>Information about the installed software</ovf:Info> <ovf:Category>Application Configuration</ovf:Category> <ovf:Property ovf:userConfigurable=”true” ovf:type=”int” ovf:password=”false” ovf:key=”webserver_port” ovf:value=””> <ovf:Label>Web Server Port</ovf:Label> <ovf:Description>Web Server Port</ovf:Description> </ovf:Property> <ovf:Property ovf:userConfigurable=”true” ovf:type=”string” ovf:password=”false” ovf:key=”webserver_image” ovf:value=””> <ovf:Label>Web Server Image</ovf:Label> <ovf:Description>Background image to display</ovf:Description> </ovf:Property> <ovf:Category>Developer Contact</ovf:Category> <ovf:Property ovf:userConfigurable=”true” ovf:type=”string” ovf:password=”false” ovf:key=”dev_contact” ovf:value=””> <ovf:Label>Dev Contact</ovf:Label> <ovf:Description>Developer Email Address</ovf:Description> </ovf:Property> </ovf:ProductSection> </ProductSectionList>
As you can see above, you can specify different categories which will allow you to group the Custom Properties and you can also control the type of property (string/int) and whether it’s a password field or not.
Now, if we head over to one of the Virtual Machines in the vCloud Director UI that we just updated, right click on the Virtual Machine and view its properties and you should see some editable fields under “Custom Properties” tab.
Since we created “user configurable” Custom Properties for the Virtual Machine, users who have permissions to modify the Virtual Machine can now add/modify the values of a Custom Property field. In this example, after creating the Custom Properties, I added the vApp to the vCloud Director Catalog so that I can now deploy new vApps that contains these new Custom Properties. I then deployed two new vApps from the Catalog and assigned them values using the vCloud Director UI, you can also use the vCloud API for automated provisioning.
Here is a screenshot for the two different WebServer Virtual Machine and their respective Custom Property values:
So now that we have created some Custom Properties and assigned them values, how do we go about accessing the properties within the Virtual Machine? The easiest way to access these properties is to leverage VMware Tools and using the vmtoolsd utility on either a supported Linux or Windows guestOS as noted in the documentation here. You will need to power on your vApp/Virtual Machine and then run the following command:
vmtoolsd –cmd “info-get guestinfo.ovfenv”
For a Windows system, it should be located under C:Program FilesVMwareVMware Toolsvmtoolsd.exe
You will see the Custom Properties that you have defined for both a vApp which have been cascaded down to the Virtual Machine as well as the Virtual Machine specific Custom Properties. You will also see other properties that are defined by vCloud Director depending on the additional guest customization or network configurations.
Now if you recall earlier, we talked about using Custom Properties to dynamically provision a vApp and customize application configurations. Using all the information above and vCloud Director’s Guest Customization Script, I was able to deploy two vApps that had an Apache Web Server and was able to specify during deployment the port number Apache would bind to as well as a default image to display on the index.html. The following customization script was used to read the values from the Custom Properties and configure a few things before starting Apache:
#!/bin/sh
if [ x$1 == x”precustomization” ]; then echo Do Precustomization tasks elif [ x$1 == x”postcustomization” ]; then WEB_SERVER_IMAGE=$(vmtoolsd –cmd “info-get guestinfo.ovfenv” | grep “key=”webserver_image”” | awk -F “value=” ‘{print $2}’ | sed ‘s//>//g’) WEB_SERVER_PORT=$(vmtoolsd –cmd “info-get guestinfo.ovfenv” | grep “key=”webserver_port”” | awk -F “value=” ‘{print $2}’ | sed ‘s//>//g’)
sed -i “s/background=.*/background=$WEB_SERVER_IMAGE>/g” /var/www/html/index.html sed -i “s/^Listen.*/Listen $WEB_SERVER_PORT/g” /etc/httpd/conf/httpd.conf
service httpd start fi
The net result are two web servers configured with specific parameters defined by a user prior to deployment and here is a screenshot of the two web pages:
Hopefully this simplified example gave you a better idea on how you can leverage this very powerful feature to dynamically pass in application configuration/parameters or any type of data that you wish to be accessible to the guestOS within vCloud Director. The really nice thing about this feature is you only need to do this once and add the vApp to your Catalog and all subsequent deployments will contain either default or configurable options during deployment.
Additional Resources:
Here are some nice videos on using VMware Studio to create your own vApp/Virtual Machines to include Custom Properties that can then be deployed to vCloud Director. Thanks to Massimo for the links.
Get notification of new blog postings and more by following lamw on Twitter: @lamw
Hopefully this simplified example gave you a better idea on how you can leverage this very powerful feature to dynamically pass in application configuration/parameters or any type of data that you wish to be accessible to the guestOS within vCloud Director. The really nice thing about this feature is you only need to do this once and add the vApp to your Catalog and all subsequent deployments will contain either default or configurable options during deployment.
