by Nigel Boulton
This blog post describes how VMware vRealize Automation (vRA) and vRealize Orchestrator (vRO) can be used to complete a typical virtual machine provisioning task.
Scenario
A common action required after provisioning a new Windows Server virtual machine is to apply the latest Windows patches. In this scenario, I will apply patches to virtual machines based on the Active Directory group membership of their computer objects.
Assumptions
- You are running vRA 6.x and vRO 6.x
- You have one or more published Windows virtual machine blueprints in vRA, which can successfully deploy domain-joined VMs via the vCenter Server in your environment with virtual machine customisation (e.g. Sysprep)
- The vCAC Plug-in has been installed and configured in vRO (if this is a separate installation)
- The AD Plug-in has been installed in vRO and configured to communicate with your AD with the appropriate rights
- An endpoint for vRO has been configured in your vRA system, and the appropriate tenant has been configured to use the correct vRO instance
Activity Overview
The steps covered are:
- Prepare the Active Directory Groups
- Configure vRealize Automation
- Configure Extensibility in vRO
- Create the Custom Workflow
- Create the code
- Assign the workflow to the blueprint
We will create the appropriate ‘patching groups’ in AD and configure vRA so that it requires the user to select, during deployment, the patching group to be used for a given VM. We will then use the vRealize’ extensibility features to hook into the machine lifecycle to run a custom vRO workflow during provisioning, passing in the name of the VM and the patching group selected. This custom workflow (which will include some bespoke scripting) will add the computer object to the AD group.
1. ****Prepare the Active Directory Groups
First, create the required patching groups in AD
2. ****Configure vRealize Automation
In vRA the user deploying a VM from a blueprint will see a drop-down list of the patching groups that they can select from. For the sake of simplicity this list will be defined within vRA, and not built dynamically from AD.
The first step within vRA is to create an object in the Property Dictionary, in order to utilise it as a custom property in a blueprint. In this example, we’ll call this VirtualMachine.PatchingGroup.
a) Go to Infrastructure – Blueprints – Property Dictionary and add a new property definition:
b) Set a suitable display name and an optional description, and select DropDownList for the control type
c) Select the Required check box (as we want this to be a mandatory selection) and save the definition
d) Edit the property attributes and create a new property attribute named Select Group whose type is ValueList
e) Provide a comma-separated list of the patching group names as the value of this attribute, as shown below:
Note the list items must exactly match the names of the patching groups that you created in AD earlier, as this is the data that will be passed to vRO during the MachineProvisioned stage.
f) Next add a custom property to the appropriate blueprint(s) in vRA which uses the property definition just created. Edit the blueprint and on the Properties tab, add a new custom property. Use the property name defined in the definition (this must match exactly). Leave the Value field blank but select the Prompt User check box, then save the custom property.
The next time this blueprint is used to deploy a VM, the user will be prompted to select a mandatory patching group:
3. ****Configure Extensibility in vRO
Next configure vRO to hook into the machine lifecycle managed by vRA and run a custom workflow. To do this, run the VMware provided Install vCO customization workflow. This workflow installs vRO customisation, including customised state change workflow stubs and vRO menu operation workflows. It can be found in the vCAC Plug-in under vCloud Automation Center – Infrastructure Administration – Extensibility – Installation.
Note that it is only necessary to run this workflow if that has not been done previously, so check for a previous successful run first.
This workflow may take a while to complete
4. ****Create the Custom Workflow
Next step is to create a custom workflow to process the data from vRA and add the VM’s computer object to the AD group.
a) First, create a new workflow in the desired vRO library folder. In this example I will call it Add vRA VM to AD group. The quickest way to do this for a workflow that will be triggered by a state change workflow is to duplicate the Workflow template workflow that can be found under vCloud Automation Center – Infrastructure Administration – Extensibility. This will pre-set a number of input parameters for you, and save a lot of time.
b) Edit the new Add vRA VM to AD group workflow to add a scriptable task. You can name this task whatever you like. In this example I will call it Process vRA VM data. Delete the default Display inputs scriptable task.
c) Add the inputs for the scriptable task that are shown as selected in the screenshot below, i.e. vCACVm and vCACVmProperties. These parameters will be used to provide input from vRA to the scriptable task. The list of parameters that you can select comes from the template workflow, but we don’t require any of the others for this example:
a) Create the following outputs for the scriptable task:
An attribute of type AD:UserGroupAD called userGroupAD
An array attribute of type Array/AD:ComputerAD called arrayComputerAD
These attributes will ultimately contain the AD representation of the computer object and the group to which it is to be added. Later we will pass these values into the next element of the workflow that we are building.
The bindings for the scriptable task should now look like this:
5. ****Create the code
Now, on to the code itself!
a) In the Scripting tab, paste in the JavaScript code shown below:
A quick run through of what the above code does follows:
The function findADGroupByName will be used by the scriptable task to search AD for a group matching the name passed in via the groupName parameter, and return an array of AD groups. As an exact match search is used, there should only ever be a maximum of one element in this array.
First, the script reads the vCACVm.virtualMachineName property to determine the VM name, in order to locate the computer object in AD later.
It then iterates the vCACVmProperties property collection to find the patching group name. Note that this property has the name of the custom property we created in vRA: VirtualMachine.PatchingGroup.
The script then uses the getComputerAD() method of the ActiveDirectory object to locate the computer account object in AD, and then pushes it into the array arrayComputerAD. This is necessary because the next element of our workflow, the out-of-the-box workflow Add computers to group members, expects an array of ComputerAD objects to be passed in to it.
Finally, the script uses the previously discussed findADGroupByName function to locate the group object in AD, which it places into the userGroupAD variable. This is an output which is passed to the next element of the workflow to actually add the computer to the group.
You will note that I have included a fair amount of debug logging in the code to assist in troubleshooting, but in order to make it short enough to describe in this blog post, no significant error handling. If desired, you can extend the code to include error handling that is suitable for your environment.
b) Save the scriptable task and then add the out-of-the-box workflow Add computers to group members, (which can be found under Microsoft – Active Directory – User Group) after the scriptable task:
c) Configure the bindings for this element as shown below:
Add computers to group members workflow input
In Attribute
userGroup
userGroupAD
computers
arrayComputerAD
d) Finally, validate the Add vRA VM to AD group workflow. There will be a number of unused parameters flagged up. Simply delete these parameters and then save and close the workflow.
**6. **
Assign the workflow to the blueprint
So now we have the custom workflow completed, the next step is to assign it to the appropriate stage in the virtual machine lifecycle. The stage we are interested in is when vRA reports the deployment process as having reached a state known as MachineProvisioned. At this point in the lifecycle, the operating system of the VM is up and running, the machine has joined the domain, and depending on timings, is likely to be applying the final VM customisations. Note that the procedure outlined below will be similar whether the custom workflow assigned is being used to add the computer to a group (as in this case), or a for more advanced activity such as adding the new virtual machine’s details to an asset management system.
In vRO, the ‘workflow stubs’ that are executed at the various stages of virtual machine provisioning can be seen in the vCAC Plug-in under vCloud Automation Center – Infrastructure Administration – Extensibility – Workflow stubs:
In order to assign our custom workflow to the WFStubMachineProvisioned workflow stub, we need to run the VMware provided Assign a state change workflow to a blueprint and its virtual machines workflow. This can be found at the same level as the workflow stubs folder. Do this as follows:
a) Start the Assign a state change workflow to a blueprint and its virtual machines workflow, select MachineProvisioned as the vCAC workflow stub to enable, and select the appropriate vRA IaaS server as the vCAC host:
b) Browse to and Add the required blueprint(s):
c) Select the Add vRA VM to AD group workflow as the End user workflow to run:
In this case, there is no need to add the vCO workflow inputs or the last vCO workflow run input values as blueprint properties values, as the blueprint already has the required properties – i.e. the name of our patching group.
d) Submit the form and once the workflow completes, we are ready to deploy a VM from the blueprint and check that it gets added successfully to the patching group. Before doing that however, review the blueprint properties in vRA and note that a new property called ExternalWFStubs.MachineProvisioned has been created, whose value is set to the ID of the Add vRA VM to AD group workflow (this ID is visible in the vRO client).
Note that this is a handy troubleshooting tip, and the first thing to check if your custom workflow doesn’t get executed during provisioning.
**7. **
Deploy a Virtual Machine from the Blueprint
Finally, deploy a virtual machine from the blueprint, selecting the required patching group when prompted, and verify that the computer account gets added to the patching group in AD. During the provisioning process, you can observe within the vRO client when the various workflows are executed, and whether they are successful. The vRA audit log (Infrastructure – Monitoring – Audit Log) can be used to identify the points at which the VM moves through each provisioning state:
Summary
This post has described an automation and orchestration approach that can be adopted to add a computer account to an AD group specified by the user at deployment time, in this case for the purposes of managing Windows patching. Of course, an almost identical process could be used to add the computer to a group for any number of other reasons.
Nigel Boulton joined the Xtravirt consulting team in November 2014. As well contributing to the Xtravirt blog, Nigel blogs on his own site at www.nigelboulton.co.uk.
If you’d like any assistance with an automation project or simply want to learn more about it please _contact us, and we’ll be more than happy to use our real world experiences to support you._
kyleclements
