vRA Developer: Part 6 – Working with vCAC Virtual Machine Custom Properties


In part 4 and part 5, I covered a lot of ground on how to work with vcac virtual machine objects, such as getting property values and discovering relationships to other entities. This post will continue exploring vcac virtual machines and will focus on custom properties.

Custom Properties are key/value pairs of data that are associated with the virtual machine. There are many default/built-in custom properties that provide the compute cluster, storage cluster, disk, cpu, network information and much more.

It’s also possible to create your own custom properties and associate these with your virtual machine deployments. This allows great flexibility as you can apply any key/value to your deployments and use this information in your workflows. An example might be to set a site identifier that associates the virtual machine to a specific site.

VMware provides a Custom Properties Reference, which details all the built-in custom properties that are available.

All code that I have provided or talked about in this post can be downloaded as a vRO package for your consumption here.

Retrieving Custom Properties Assigned to a Virtual Machine

There are two main ways to retrieve the custom properties that have been associated with a virtual machine deployment. The first, is during the build process, where an Event Broker Subscription is used to call a vRO workflow, to perform some task. The second, is by reading the custom properties from the vcac database (via the entities) for those that are related to the virtual machine.

Here is an example of a default set of Custom Properties associated with a deployed virtual machine:

The first set are prefixed with a double underscore (__), which denotes that these are ‘hidden’ properties that are used by the system and provide object references to the reservation and the request (note that these properties will not be referenced in the official VMware Custom Properties Reference).

The remaining properties are the key/values associated with the virtual machine and can provide cpu count, amount of assigned memory, used storage, etc. and any user-defined custom properties that you have created. Unlike the hidden properties. you will find a reference to all of these in the VMware Custom Properties Reference.

One important thing to note, is that when you are working with custom property values, these are always returned as a string, regardless of what data is being stored. I.e. if a custom property has a value of ‘false’, this is the literal string “false” and not Boolean false.

Retrieve Custom Properties Using vCAC Entities

This method of retrieving custom properties accesses them directly from the vcac entities (the data sources) by finding custom properties that are ‘linked’ to the virtual machine. This is really useful when you need to use custom properties in your workflows. Note that the Extensibility Lifecycle properties do not affect how this works and you will be able to retrieve all custom properties, including hidden ones.

I have provided Actions in the download package that can be used to retrieve all of the following:

  • Blueprint Id;
  • Blueprint Name;
  • Component Id;
  • Cloned From (the template that was used for the new vm);
  • Compute Resource Name (Host/Cluster);
  • Guest Customization specification used;
  • CPU count, memory size;
  • disk sizes, total disk usage, disk device Id;
  • Attached networks;
  • Guest OS Identifier;
  • Host Name;
  • Storage Cluster Name;
  • vCenter Folder;
  • Virtual Machine UUID;
  • Reservation Policy ID.

Get Custom Properties Set

The following code will accept a vcac entity object as an input and will return a Properties object that contains all the key/value pairs of the custom properties. I find this useful as it allows me to ‘cache’ the properties in my workflow when I need to retrieve multiple values without constantly requested the full payload.

Log output (truncated):

Get a Specific Custom Property Value from the Set

The following contains 2 code examples that are used to retrieve a value from a custom property. The first code example is a helper Action, that will do the work of retrieving the value. The helper Action accepts the Custom Properties payload (the Properties object that was created from the code, above) as an input along with a property key. It will then return the value for that property, as a string.

The idea of this action is that is will be used with wrappers for specific custom property lookups. These wrappers will then return the expected data type that is more useful, such as a Number when retrieving the number of cpu’s.

The next Action is an example of a wrapper that uses the helper, above. As I previously stated, although the return value from the Custom Property is always a string, I will change this in the wrapper to the correct data type. This makes it far cleaner and convenient when I use these Actions in my workflows. This Action also accepts the Custom Properties payload and property key, which it passes through to the helper Action.

Below is what my workflow would look like to retrieve the number of CPUs assigned to the virtual machine taken from the custom properties.

I first get the default vcacHost from the inventory. I then find the virtual machine entity by its entity id. Once I have the virtual machine entity, I get the custom properties payload and then finally extract the number of CPUs from a property that exists in that payload.

Log output:

Retrieve Custom Properties Using an Event Broker Subscription

When I am working with the event broker, I have an action that will get the custom properties payload. I can then use the Actions that I described above with this payload as an input. I like to maintain compatibility between my Actions. In a future post I will cover the Event Broker in more detail.

Add or Update Custom Properties

When adding new custom properties to a virtual machine, or updating existing ones, I again use a helper Action that does the bulk of the work. This Action is designed to be used with a wrapper Action that provides its values.

The helper Action will detect if a custom property exists and if it does not, then the custom property is created, with the specified value. If the custom property already exists then the value is checked against the specified value to update. If the values match then no update is made, otherwise, the custom property is updated with the specified value.

The code below is the helper Action:

As an example, I would use a wrapper Action that will update the Blueprint name that a virtual machine is assigned to, using the helper action above.

Below is what my workflow would look like to update the custom properties to change the blueprint name (not that updating the entities blueprintName property is also required).

Log output:

I hope this has been useful. If you discover bugs with any of my code, require some help or simply need an ad-hoc solution, then please drop me a message via the Drift app.

Series Navigation<< vRA Developer: Part 5 – Working with vCAC Virtual Machine Linked Entities

Leave a Reply

avatar
  Subscribe  
Notify of