Development Archives - SimplyGeek.co.uk

vRealize Automation: Part 5 – Working with vCAC Virtual Machine Linked Entities

February 15, 2019February 15, 2019 Gavin Stephens

This entry is part 5 of 5 in the series vRealize Automation Developer Master Series

In 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 properties. In this post I am going to focus on linked entities.

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

There are additional properties that can be retrieved which are part of other entities that the virtual machine has a relationship with. Here are some examples of information that can be retrieved through linked entities (the code for all of these examples is included in the package link provided at the beginning of this post).

Host/Cluster Name
Reservation Name
Owner Username
IPv4 Addresses
Snapshots
Networks

The virtual machine entity object has a method ‘.getLink(vcacHost, “linkKey_string”)‘ that can be used to get the linked entity objects. The ‘.getProperty(“key_string”)‘ can then be used on these entities to get a specific property value, such as the reservation name.

Get the Host or Cluster Name

The following code can be used to get the host or cluster name that the virtual machine (this is referred to as the compute resource within the vRA portal) is hosted on.

/**
 * Get the compute resource name for the vcac virtual machine entity.
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {string} Returns the compute resource name.
 */

/**
 * This function validates input parameters.
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 */
function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join('\n');
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "getComputeResourceNameForVirtualMachineEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var hostEntities = [];
var hostEntity;
var hostName = "";
var hostId = "";
var vmEntityName = "";
var numHostEntities = 0;

try {
    checkParams(vcacHost, vcacVmEntity);
    vmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Getting compute resource name for virtual machine entity: " + vmEntityName);
    hostEntities = vcacVmEntity.getLink(vcacHost, "Host");
    numHostEntities = hostEntities.length;
    if (numHostEntities > 1 ) {
        log.error("More than one compute resource was found.");
    } else if (numHostEntities > 0) {
        hostEntity = hostEntities[0];
        hostName = hostEntity.getProperty("HostName");
        hostId = hostEntity.getProperty("HostID");
        log.log("Found compute resource '" + hostName + "' with entity id '" + hostId + "'");
    } else {
        log.error("No compute resource was found.");
    }
} catch (e) {
    log.error("Action failed to get compute resource name for virtual machine entity.",e);
}

return hostName;

/**

* Get the compute resource name for the vcac virtual machine entity.

* @param {vCAC:VCACHOST} vcacHost - The vCAC Host.

* @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.

* @returns {string} Returns the compute resource name.

/**

* This function validates input parameters.

* @param {vCAC:VCACHOST} vcacHost - The vCAC Host.

* @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.

function checkParams(vcacHost, vcacVmEntity) {

var inputErrors = [];

var errorMessage;

if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {

inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");

}

if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {

inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");

}

if (inputErrors.length > 0) {

errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join('\n');

log.error(errorMessage);

}

var logType = "Action";

var logName = "getComputeResourceNameForVirtualMachineEntity"; // This must be set to the name of the action

var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);

var log = new Logger(logType, logName);

var hostEntities = [];

var hostEntity;

var hostName = "";

var hostId = "";

var vmEntityName = "";

var numHostEntities = 0;

try {

checkParams(vcacHost, vcacVmEntity);

vmEntityName = vcacVmEntity.getProperty("VirtualMachineName");

log.log("Getting compute resource name for virtual machine entity: " + vmEntityName);

hostEntities = vcacVmEntity.getLink(vcacHost, "Host");

numHostEntities = hostEntities.length;

if (numHostEntities > 1 ) {

log.error("More than one compute resource was found.");

} else if (numHostEntities > 0) {

hostEntity = hostEntities[0];

hostName = hostEntity.getProperty("HostName");

hostId = hostEntity.getProperty("HostID");

log.log("Found compute resource '" + hostName + "' with entity id '" + hostId + "'");

} else {

log.error("No compute resource was found.");

}

} catch (e) {

log.error("Action failed to get compute resource name for virtual machine entity.",e);

}

return hostName;

Log output:

[] [I] [Action: getComputeResourceNameForVirtualMachineEntity] Getting compute resource name for virtual machine entity: SG-BG-Deliv0005
[] [I] [Action: getComputeResourceNameForVirtualMachineEntity] Found compute resource 'SITEA-CLS-CLOUD-01' with entity id '355c617e-f9e0-4726-abcf-81f5748c50db'

1 2	[] [I] [Action: getComputeResourceNameForVirtualMachineEntity] Getting compute resource name for virtual machine entity: SG-BG-Deliv0005 [] [I] [Action: getComputeResourceNameForVirtualMachineEntity] Found compute resource 'SITEA-CLS-CLOUD-01' with entity id '355c617e-f9e0-4726-abcf-81f5748c50db'

Continue reading →

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

February 15, 2019February 15, 2019 Gavin Stephens

This entry is part 4 of 5 in the series vRealize Automation Developer Master Series

In the first post in this series, vRealize Automation: 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.

/**
 * Searches for a vcac virtual machine entity by its entity id.
 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 * @param {string} virtualMachineId - The virtual machine entity id.
 * @returns {vCAC:Entity} Returns the virtual machine entity.
 */

/**
 * This function validates input parameters.
 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 * @param {string} virtualMachineId - The virtual machine id.
 */
function checkParams(vcacHost, virtualMachineId) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    if (!virtualMachineId || typeof virtualMachineId !== "string") {
        inputErrors.push(" - virtualMachineId missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join('\n');
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "findVirtualMachineEntityByVirtualMachineId"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var properties = new Properties();
var vcacVmEntity;
var vcacEntityFieldName = "VirtualMachineID";
var entitySetName = "VirtualMachines";
var vcacVmName = "";


try {
	checkParams(vcacHost, virtualMachineId);
    log.log("finding virtual machine entity with entity id: " + virtualMachineId);
	properties.put(vcacEntityFieldName, virtualMachineId);
	vcacVmEntity = System.getModule("com.simplygeek.library.vcac.entities").getVcacEntitiyByUniqieId(vcacHost, 
                                                                                                     entitySetName, 
                                                                                                     properties);
	vcacVmName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Found virtual machine entity: " + vcacVmName + " with entity id: " + virtualMachineId);
} catch (e) {
    log.error("Action failed to locate vCAC virtual machine entity.",e);
}

return vcacVmEntity;

/**

* Searches for a vcac virtual machine entity by its entity id.

* @param {vCAC:VCACHost} vcacHost - The vCAC Host.

* @param {string} virtualMachineId - The virtual machine entity id.

* @returns {vCAC:Entity} Returns the virtual machine entity.

/**

* This function validates input parameters.

* @param {vCAC:VCACHost} vcacHost - The vCAC Host.

* @param {string} virtualMachineId - The virtual machine id.

function checkParams(vcacHost, virtualMachineId) {

var inputErrors = [];

var errorMessage;

if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {

inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");

}

if (!virtualMachineId || typeof virtualMachineId !== "string") {

inputErrors.push(" - virtualMachineId missing or not of type 'string'");

}

if (inputErrors.length > 0) {

errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join('\n');

log.error(errorMessage);

}

var logType = "Action";

var logName = "findVirtualMachineEntityByVirtualMachineId"; // This must be set to the name of the action

var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);

var log = new Logger(logType, logName);

var properties = new Properties();

var vcacVmEntity;

var vcacEntityFieldName = "VirtualMachineID";

var entitySetName = "VirtualMachines";

var vcacVmName = "";

try {

checkParams(vcacHost, virtualMachineId);

log.log("finding virtual machine entity with entity id: " + virtualMachineId);

properties.put(vcacEntityFieldName, virtualMachineId);

vcacVmEntity = System.getModule("com.simplygeek.library.vcac.entities").getVcacEntitiyByUniqieId(vcacHost,

entitySetName,

properties);

vcacVmName = vcacVmEntity.getProperty("VirtualMachineName");

log.log("Found virtual machine entity: " + vcacVmName + " with entity id: " + virtualMachineId);

} catch (e) {

log.error("Action failed to locate vCAC virtual machine entity.",e);

}

return vcacVmEntity;

Log output:

[] [I] [Action: findVirtualMachineEntityByVirtualMachineId] finding virtual machine entity with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a
[] [I] [Action: findVirtualMachineEntityByVirtualMachineId] Found virtual machine entity: SG-BG-Deliv0005 with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a

[] [I] [Action: findVirtualMachineEntityByVirtualMachineId] finding virtual machine entity with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a

[] [I] [Action: findVirtualMachineEntityByVirtualMachineId] Found virtual machine entity: SG-BG-Deliv0005 with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a

Continue reading →

Advanced vRA Data Collection vRO Workflow

February 9, 2019February 9, 2019 Gavin Stephens

Data Collection in vRealize Automation is a process that keeps the vRA database in sync with endpoints such as vCenter Server. Most people reading this most likely already know how clunky this process is. Also, It’s not immediately obvious how this process can be automated from a vRO prospective. If you are performing any tasks against objects on your endpoints, such as day 2 actions that add or remove hard disks, networks, etc (and not using the OOTB reconfigure actions) then you almost certainly need to be able to programmatically invoke the data collection process to update all the information in vRA.

I have come across many different snippets of code that solved parts of the problem but were far from perfect and the code was ugly. I therefore decided to create something to make this process easy, whilst providing some additional quality of life features. So I present my Advanced Data Collection workflow for your pleasure.

Continue reading →

Implementing Process Locks in vRO Workflows

February 1, 2019February 14, 2019 Gavin Stephens

I discovered last week that a developer wasn’t aware that you could use a locking semaphore in vRO. They were writing some API calls and encountered a 409 (conflict) error when a workflow was attempting to concurrently update the same resource (a load balancer if I recall but can’t remember the exact details). I felt that there may be other developers out there who are also not aware so I have created two workflows that can be used to create and remove process locks in your vRO workflows.

vRO provides an always available Locking System that can be used to create a lock for a given id and owner. It does this by creating a record in the embedded PostgreSQL database. When an attempt is made to create another record in the database, a key constraint occurs and the lock fails.

You should consider using a process lock if you are updating any resources that could cause a conflict or data consistency problems. Some examples include, updating a load balancer, updating a vRA Reservation, or preventing a data collection task from running because there is already one in progress. It is also useful to create a lock between sections of code in your workflow, which could cause a problem if the workflow was executed multiple times, simultaneously. Note, that you don’t always need to lock the entire workflow, just between areas of code where updates are performed. Continue reading →

Resolve vRA/vCAC VM to vCenter VM

January 30, 2019February 15, 2019 Gavin Stephens

I wrote this post some time ago but I felt that it didn’t include some other use cases where you would want to resolve a vCenter virtual machine. I also previously used code that was provided by the vRO appliance that I wasn’t too keen on (logging was a bit light and there was code to search using the BIOS UUID, which we don’t care about). I have therefore updated this post to reflect the following use cases:

Find the vCenter VM by its instance Uuid when using the Event Broker;
Find the vCenter VM by its instance Uuid on a specific vCenter Server;
Find the vCenter VM by its name, on a specific vCenter Server and a specific folder;
Find the vCenter VM by its MoRef id on a specific vCenter Server;

Hopefully, there should be enough code provided here to help you achieve your goal no matter what your scenario. However, if you need something different, then feel free to contact me and I will try to help. Continue reading →

vRealize Automation: Part 3 – Performing CRUD Operations on IaaS Entity Objects

January 14, 2019February 15, 2019 Gavin Stephens

This entry is part 3 of 5 in the series vRealize Automation Developer Master Series

In a previous post vRealize Automation: Part 1 – IaaS & Understanding The Entity Framework I detailed what the Entity Framework is and how objects and their properties could be discovered using an application called LINQPad.

This post is going to detail how we can interact with the IaaS servers and work with the objects within the Entity Framework. I have also written a number of actions that provide a standard interface to use when working with the entities and perform CRUD (Create, Read, Update, Delete) operations on them.

Note: these actions are designed to be used with wrappers for your code (i.e. other actions performing a task, which call these actions) and not directly in your workflows (although there is no real harm if you want to, it’s just cleaner not to). Continue reading →

vRealize Automation: Part 2 – Dynamically Discover vCAC and vCACCAFE endpoints in vRO

October 30, 2018February 15, 2019 Gavin Stephens

This entry is part 2 of 5 in the series vRealize Automation Developer Master Series

When I work with endpoints in vRO, I like to use actions to discover these instead of hard coding them as attributes or within configuration elements. Hard coding of these endpoints requires manual configuration steps when moving code between environments, which is not ideal. I felt it would be a good idea to include this post early on within this series, as these hosts are often dependencies when working with a lot of my code.

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

Discover vRealize Automation Infrastructure (vCAC IaaS) Endpoint

You will generally only have a single vCAC IaaS endpoint in your vRO inventory. I have never worked in an environment where there was more than one. Therefore, the action I have created below requires no inputs and will attempt to discover this single vCAC IaaS endpoint. If you have more than one host for some reason then it should be fairly easy to incorporate this. Continue reading →

vRealize Orchestrator: Standardised Logger Action

March 7, 2018February 6, 2019 Gavin Stephens

I have updated this page on 22nd Jan 2019 to introduce enhancements over the original logging action. I have converted the original function calls to an object based approach. This allows a logger object to be used, which looks cleaner and is initialised once. I have also introduced JSDoc documentation styles into my code.

The actions used in this post have been packaged in a vRO package and can be downloaded here.

One bugbear that I have with vRO is the limitation around system (console) logging. There is currently no way to dynamically output the name of an action or sub-workflow (see end of the post). I like to see exactly which action or workflow is executing code. This makes it easier for me to troubleshoot a defect, when I am looking at the output logs.

It is possible to use ‘workflow.name’ or ‘this.name’ inside an action, but this will always be set to the name of the initial workflow that was executed. This is because the workflow object is implicitly passed to the action that is called. The result, is that it will look like all the code is executing from the workflow (which is technically true, but I needed more granularity).

I therefore created a standardised way that workflow and action logging should be handled. This is achieved by using an action that will actually handle all the logging for me. The idea is, that an action or workflow will call the ‘logger‘ action, providing some parameters, that allow for a consistent and useful logging experience. Continue reading →