vRA Developer: Part 4 – Working with vCAC Virtual Machine Entities


In the first post in this series, vRA Developer: Part 1 – IaaS & Understanding The Entity Framework I detailed how you can view the vCAC entities and their associated properties. In this post I am going to cover how you can find a virtual machine entity using different property references and get/update their properties in your vRO workflows. I had intended to provide a single post for this, but felt it would be useful to provide a number of posts, for each specific vCAC entity type. In this post I am going to be looking at the vCAC virtual machine entities.

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

Finding vCAC Virtual Machine Entities

When I need to find a vCAC virtual machine entity, there are 4 search references that work well for all of my use cases. These are to search by:

  • VirtualMachineID – The entity ID.
  • VirtualMachineName – The VM name. Take caution as it’s possible to have duplicate entities with the same VirtualMachineName.
  • VMUniqueID – The unique identifier for the vm (i.e. vCenter VM instance UUID).
  • ExternalReferenceId – The external reference id (i.e. vCenter VM Id (MoRef)).

I have provided all the Actions below which perform these searches and an example log output for each.

Find Virtual Machine By Entity Id

The following code can be used to get the virtual machine entity by its entity id.

Log output:

Find Virtual Machine By Name

The following code can be used to get the virtual machine entity by its name.

Log output:

Find Virtual Machine By Instance UUID

The following code can be used to get the virtual machine entity by its instance uuid.

Log output:

Find Virtual Machine By Managed Object Reference (MoRef)

The following code can be used to get the virtual machine entity by its managed object reference.

Log output:

Get Virtual Machine Property Values

The virtual machine entity object has a method ‘.getProperty(“key_string”)‘ that can be used to retrieve a value for a specified property key. When I need to retrieve a value for a property on a virtual machine, I use a helper Action that calls this method and does the main part of the work. I then wrap other Actions around this for the specific property that I need the value for. This can seem a little repetitive but with all the Actions in place, I simply drop them onto my workflows without any thought.

I have created Actions that can retrieve the value for the following virtual machine properties where the correct data type is returned (note this is not the complete set of properties available but the only ones you are ever going to need).

Property Data Type Description
VirtualMachineID string The virtual machine entity id
VirtualMachineName string The virtual machine name
Expires Date The date the virtual machine will expire (if set to expire)
InitiatorType string Will set how the virtual machine was provisioned (i.e. Created)
Notes string The virtual machine description
GuestOS string The Guest OS (i.e. Microsoft Windows Server 2012 (64-bit))
VMUniqueID string The virtual machine unique id (i.e. for VMware this would be the vCenter VM instance uuid)
VMCreationDate Date The date the virtual machine was created
OwnerExists boolean True of the owner (vm) exists
IsDeleted boolean Set to true if the virtual machine has been deleted (but entity still exists in the database)
IsMissing boolean Set to true if the virtual machine is missing (but item still exists in vRA and can be re-provisioned)
IsRunning boolean Set to true if the virtual machine is running on the host platform
VMCPUs number The number of vCPUs assigned to the virtual machine
VMTotalMemoryMB number The amount of vRAM in MB assigned to the virtual machine
VMTotalStorageGB number The amount of storage in GB assigned to the virtual machine
GuestOSFamily string The guest OS family (i.e. for vCenter this would be the OS code e.g. windows7Server64Guest)
VirtualMachineState string The virtual machine state (as it would appear under managed machines in vRA)
CurrentTask string The current task being performed on the virtual machine
IsTemplate boolean Set to true if the virtual machine is a template
VMDNSName string The DNS name of the virtual machine (i.e. in vCenter this would be what is reported by VMware Tools)
VMUsedStorageGB number The amount of storage in GB that is used by the virtual machine
ExpireDays number The amount of days until the virtual machine expires (if set to expire)
StoragePath string The default storage path (i.e. the datastore cluster name)
IsManaged boolean Set to true if the virtual machine is managed by vRA
ExternalReferenceId string The virtual machine external reference id (i.e. for vCenter this would be the virtual machine id/moref)
HostReservationID string The entity id of the reservation that the virtual machine is consuming
HostID string The entity id of the host/cluster that the virtual machine is hosted on
BlueprintName string The name of the blueprint that the virtual machine is assigned to/was provisioned from
ComponentName string The name of the component within the blueprint that the virtual machine is assigned to

There are of course too many properties here to provide code for. Each Action pretty much looks the same and I’ll provide a couple of examples below. The package link at the beginning of this post will provide Actions for all the above properties.

The following code is the main helper action that retrieves the property value.

This is an example of one of the Actions which act as a wrapper for the above, that is used to get the number of vCPUs assigned to the virtual machine. I have also provided some log output of this being used in a workflow.

Log output:

Update Virtual Machine Property Values

I have a helper Action that can be used to update a property value on a virtual machine entity. This can be useful if you want to assign the virtual machine to a new blueprint or change the reference for the virtual machine on the parent platform.

Most of the properties can’t or don’t make sense to be updated (as they would get reset during a data collection). The following are valid properties that can be updated and I have provided Actions for.

  • BlueprintName
  • ComponentName
  • ExternalReferenceId
  • isManaged
  • Notes
  • OwnerExists
  • VMUniqueID

I also like to take an idempotent approach when performing update operations. Therefore, this helper Action will first check if the current value is the same as the value to be set. If the values are the same, then no update operation is carried out.

This is an example of one of the Actions which acts as a wrapper for the above, that is used to change the blueprint that the virtual machine is assigned to. I have also provided some log output of this being used in a workflow.

Update Blueprint Name

The following code can be used to update the blueprint that the virtual machine is assigned to.

Log output when the value being set is different to the current value:

Log output when the value being set is the same as the current value:

Update Component Name

The following code can be used to update the component name that the virtual machine is assigned to inside the blueprint.

Update Virtual Machine Description

The following code can be used to update the virtual machine description (this will in turn update the object, for example, in vCenter).

Update Virtual Machine Instance UUID

The Following code can be used to update the virtual machine instance uuid. This is useful if the virtual machine has changed locations or has been restored with a new instance uuid (note that the ‘VirtualMachine.Admin.UUID’ custom property would also need to be updated that is detailed in a followup post).

Update Virtual Machine Managed Object Reference

The following code can be used to update the virtual machine Id (MoRef). This is useful if the virtual machine has changed locations or has been restored with a new id.

I hope this has been useful. The original post was quite large and in the end I had to break down into 3 separate posts.

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.

Please rate this post!

Average rating / 5. Vote count:

2
Leave a Reply

avatar
2 Comment threads
0 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
0 Comment authors
Recent comment authors
  Subscribe  
newest oldest most voted
Notify of
trackback

[…] my previous post vRealize Automation: Part 4 – Working with vCAC Virtual Machine Entities, I demonstrated how you could find vCAC virtual machine entities and retrieve and update their […]

trackback

[…] vRealize Automation: Part 4 – Working with vCAC Virtual Machine Entities […]