In this article by Daniel Langenhan, the author of VMware vRealize Orchestrator Cookbook, we will take a closer look at how Orchestrator interacts with vCenter Server and vRealize Automation (vRA—formerly known as vCloud Automation Center, vCAC). vRA uses Orchestrator to access and automate infrastructure using Orchestrator plugins. We will take a look at how to make Orchestrator workflows available to vRA.

We will investigate the following recipes:

• Unmounting all the CD-ROMs of all VMs in a cluster
• Provisioning a VM from a template
• An approval process for VM provisioning

(For more resources related to this topic, see here.)

There are quite a lot of plugins for Orchestrator to interact with VMware infrastructure and programs:

• vCenter Server
• vCloud Director (vCD)
• vRealize Automation (vRA—formally known as vCloud Automation Center, vCAC)
• Site Recovery Manager (SRM)
• VMware Auto Deploy
• Horizon (View and Virtual Desktops)
• vRealize Configuration Manager (earlier known as vCenter Configuration Manager)
• vCenter Update Manager
• vCenter Operation Manager, vCOPS (only example packages)

VMware, as of writing of this article, is still renaming its products. An overview of all plugins and their names and download links can be found at http://www.vcoteam.info/links/plug-ins.html.

There are quite a lot of plugins, and we will not be able to cover all of them, so we will focus on the one that is most used, vCenter. Sadly, vCloud Director is earmarked by VMware to disappear for everyone but service providers, so there is no real need to show any workflow for it.

We will also work with vRA and see how it interacts with Orchestrator.

vSphere automation

The interaction between Orchestrator and vCenter is done using the vCenter API. Here is the explanation of the interaction, which you can refer to in the following figure.

A user starts an Orchestrator workflow (1) either in an interactive way via the vSphere Web Client, the Orchestrator Web Operator, the Orchestrator Client, or via the API. The workflow in Orchestrator will then send a job (2) to vCenter and receive a task ID back (type VC:Task). vCenter will then start enacting the job (3). Using the vim3WaitTaskEnd action (4), Orchestrator pauses until the task has been completed. If we do not use the wait task, we can’t be certain whether the task has ended or failed. It is extremely important to use the vim3WaitTaskEnd action whenever we send a job to vCenter. When the wait task reports that the job has finished, the workflow will be marked as finished.

The vCenter MoRef

The MoRef (Managed Object Reference) is a unique ID for every object inside vCenter. MoRefs are basically strings; some examples are shown here:

VM	Network	Datastore	ESXi host	Data center	Cluster
vm-301	network-312 dvportgroup-242	datastore-101	host-44	data center-21	domain-c41

The MoRefs are typically stored in the attribute .id or .key of the Orchestrator API object. For example, the MoRef of a vSwitch Network is VC:Network.id.

To browse for MoRefs, you can use the Managed Object Browser (MOB), documented at https://pubs.vmware.com/vsphere-55/index.jsp#com.vmware.wssdk.pg.doc/PG_Appx_Using_MOB.20.1.html.

The vim3WaitTaskEnd action

As already said, vim3WaitTaskEnd is one of the most central actions while interacting with vCenter. The action has the following variables:

Category	Name	Type	Usage
IN	vcTask	VC:Task	Carries the reconfiguration task from the script to the wait task
IN	progress	Boolean	Write to the logs the progress of a task in percentage
IN	pollRate	Number	How often the action should be checked for task completion in vCenter
OUT	ActionResult	Any	Returns the task’s result

The wait task will check in regular intervals (pollRate) the status of a task that has been submitted to vCenter. The task can have the following states:

State	Meaning
Queued	The task is queued and will be executed as soon as possible.
Running	The task is currently running. If the progress is set to true, the progress in percentage will be displayed in the logs.
Success	The task is finished successfully.
Error	The task has failed and an error will be thrown.

Other vCenter wait actions

There are actually five waiting tasks that come with the vCenter Server plugin. Here’s an overview of the other four:

Task	Description
vim3WaitToolsStarted	This task waits until the VMware tools are started on a VM or until a timeout is reached.
Vim3WaitForPrincipalIP	This task waits until the VMware tools report the primary IP of a VM or until a timeout is reached. This typically indicates that the operating system is ready to receive network traffic. The action will return the primary IP.
Vim3WaitDnsNameInTools	This task waits until the VMware tools report a given DNS name of a VM or until a timeout is reached. The in-parameter addNumberToName is not used and can be set to Null.
WaitTaskEndOrVMQuestion	This task waits until a task is finished or if a VM develops a question. A vCenter question is related to user interaction.

vRealize Automation (vRA)

Automation has changed since the beginning of Orchestrator. Before, tools such as vCloud Director or vCloud Automation Center (vCAC)/vRealize Automation (vRA), Orchestrator was the main tool for automating vCenter resources.

With version 6.2 of vCloud Automation Center (vCAC), the product has been renamed vRealize Automation.

Now vRA is deemed to become the central cornerstone in the VMware automation effort. vRealize Orchestrator (vRO), is used by vRA to interact with and automate VMware and non-VMware products and infrastructure elements.

Throughout the various vCAC/vRA interactions, the role of Orchestrator has changed substantially. Orchestrator started off as an extension to vCAC and became a central part of vRA.

• In vCAC 5.x, Orchestrator was only an extension of the IaaS life cycle. Orchestrator was tied in using the stubs
• vCAC 6.0 integrated Orchestrator as an XaaS service (Everything as a Service) using the Advanced Service Designer (ASD)
• In vCAC 6.1, Orchestrator is used to perform all VMware NSX operations (VMware’s new network virtualization and automation), meaning that it became even more of a central part of the IaaS services.
• With vCAC 6.2, the Advance Service Designer (ASD) was enhanced to allow more complex form of designs, allowing better leverage of Orchestrator workflows.

As you can see in the following figure, vRA connects to the vCenter Server using an infrastructure endpoint that allows vRA to conduct basic infrastructure actions, such as power operations, cloning, and so on. It doesn’t allow any complex interactions with the vSphere infrastructure, such as HA configurations.

Using the Advanced Service Endpoints, vRA integrates the Orchestrator (vRO) plugins as additional services. This allows vRA to offer the entire plugin infrastructure as services to vRA. The vCenter Server, AD, and PowerShell plugins are typical integrations that are used with vRA.

Using Advance Service Designer (ASD), you can create integrations that use Orchestrator workflows. ASD allows you to offer Orchestrator workflows as vRA catalog items, making it possible for tenants to access any IT service that can be configured with Orchestrator via its plugins. The following diagram shows an example using the Active Directory plugin. The Orchestrator Plugin provides access to the AD services. By creating a custom resource using the exposed AD infrastructure, we can create a service blueprint and resource actions, both of which are based on Orchestrator workflows that use the AD plugin.

The other method of integrating Orchestrator into the IaaS life cycle, which was predominately used in vCAC 5.x was to use the stubs. The build process of a VM has several steps; each step can be assigned a customizable workflow (called a stub). You can configure vRA to run an Orchestrator workflow at these stubs in order to facilitate a few customized actions. Such actions could be taken to change the VMs HA or DRS configuration, or to use the guest integration to install or configure a program on a VM.

Installation

How to install and configure vRA is out of the scope of this article, but take a look at http://www.kendrickcoleman.com/index.php/Tech-Blog/how-to-install-vcloud-automation-center-vcac-60-part-1-identity-appliance.html for more information.

If you don’t have the hardware or the time to install vRA yourself, you can use the VMware Hands-on Labs, which can be accessed after clicking on Try for Free at http://hol.vmware.com.

The vRA Orchestrator plugin

Due to the renaming, the vRA plugin is called vRealize Orchestrator vRA Plug-in 6.2.0, however the file you download and use is named o11nplugin-vcac-6.2.0-2287231.vmoapp. The plugin currently creates a workflow folder called vCloud Automation Center.

vRA-integrated Orchestrator

The vRA appliance comes with an installed and configured vRO instance; however, the best practice for a production environment is to use a dedicated Orchestrator installation, even better would be an Orchestrator cluster.

Dynamic Types or XaaS

XaaS means Everything (X) as a Service. The introduction of Dynamic Types in Orchestrator Version 5.5.1 does exactly that; it allows you to build your own plugins and interact with infrastructure that has not yet received its own plugin.

Take a look at this article by Christophe Decanini; it integrates Twitter with Orchestrator using Dynamic Types at http://www.vcoteam.info/articles/learn-vco/282-dynamic-types-tutorial-implement-your-own-twitter-plug-in-without-any-scripting.html.

Read more…

To read more about Orchestrator integration with vRA, please take a look at the official VMware documentation.

Please note that the official documentation you need to look at is about vRealize Automation, and not about vCloud Automation Center, but, as of writing this article, the documentation can be found at https://www.vmware.com/support/pubs/vrealize-automation-pubs.html.

• The document called Advanced Service Design deals with vRO and Advanced Service Designer
• The document called Machine Extensibility discusses customization using subs

Unmounting all the CD-ROMs of all VMs in a cluster

This is an easy recipe to start with, but one you can really make it work for your existing infrastructure. The workflow will unmount all CD-ROMs from a running VM. A mounted CD-ROM may block a VM from being vMotioned.

Getting ready

We need a VM that can mount a CD-ROM either as an ISO from a host or from the client.

Before you start the workflow, make sure that the VM is powered on and has an ISO connected to it.

How to do it…

1. Create a new workflow with the following variables:
   

   Name	Type	Section	Use
   cluster	VC:ClusterComputerResource	IN	Used to input the cluster
   clusterVMs	Array of VC:VirtualMachine	Attribute	Use to capture all VMs in a cluster

2. Add the getAllVMsOfCluster action to the schema and assign the cluster in-parameter and the clusterVMs attribute to it as actionResult.
3. Now, add a Foreach element to the schema and assign the workflow Disconnect all detachable devices from a running virtual machine.
4. Assign the Foreach element clusterVMs as a parameter.
5. Save and run the workflow.

How it works…

This recipe shows how fast and easily you can design solutions that help you with everyday vCenter problems. The problem is that VMs that have CD-ROMs or floppies mounted may experience problems using vMotion, making it impossible for them to be used with DRS. The reality is that a lot of admins mount CD-ROMs and then forget to disconnect them.

Scheduling this script every evening just before the nighttime backups will make sure that a production cluster is able to make full use of DRS and is therefore better load-balanced.

You can improve this workflow by integrating an exclusion list.

See also

Refer to the example workflow, 7.01 UnMount CD-ROM from Cluster.

Provisioning a VM from a template

In this recipe, we will build a deployment workflow for Windows and Linux VMs. We will learn how to create workflows and reduce the amount of input variables.

Getting ready

We need a Linux or Windows template that we can clone and provision.

How to do it…

We have split this recipe in two sections. In the first section, we will create a configuration element, and in the second, we will create the workflow.

Creating a configuration

We will use a configuration for all reusable variables.

Build a configuration element that contains the following items:

Name	Type	Use
productId	String	This is the Windows product ID—the licensing code
joinDomain	String	This is the Windows domain FQDN to join
domainAdmin	Credential	These are the credentials to join the domain
licenseMode	VC:CustomizationLicenseDataMode	Example, perServer
licenseUsers	Number	This denotes the number of licensed concurrent users
inTimezone	Enums:MSTimeZone	Time zone
fullName	String	Full name of the user
orgName	String	Organization name
newAdminPassword	String	New admin password
dnsServerList	Array of String	List of DNS servers
dnsDomain	String	DNS domain
gateway	Array of String	List of gateways

Creating the base workflow

Now we will create the base workflow:

1. Create the workflow as shown in the following figure by adding the given elements:
   •      Clone, Windows with single NIC and credential
   •      Clone, Linux with single NIC
   •      Custom decision

   

2. Use the Clone, Windows… workflow to create all variables. Link up the ones that you have defined in the configuration as attributes. The rest are defined as follows:
   

   Name	Type	Section	Use
   vmName	String	IN	This is the new virtual machine’s name
   vm	VC:VirtualMachine	IN	Virtual machine to clone
   folder	VC:VmFolder	IN	This is the virtual machine folder
   datastore	VC:Datastore	IN	This is the datastore in which you store the virtual machine
   pool	VC:ResourcePool	IN	This is the resource pool in which you create the virtual machine
   network	VC:Network	IN	This is the network to which you attach the virtual network interface
   ipAddress	String	IN	This is the fixed valid IP address
   subnetMask	String	IN	This is the subnet mask
   template	Boolean	Attribute	For value No, mark new VM as template
   powerOn	Boolean	Attribute	For value Yes, power on the VM after creation
   doSysprep	Boolean	Attribute	For value Yes, run Windows Sysprep
   dhcp	Boolean	Attribute	For value No, use DHCP
   newVM	VC:VirtualMachine	OUT	This is the newly-created VM

3. The following sub-workflow in-parameters will be set to special values:
   

   Workflow	In-parameter	value
   Clone, Windows with single NIC and credential	host	Null
   	joinWorkgroup	Null
   	macAddress	Null
   	netBIOS	Null
   	primaryWINS	Null
   	secondaryWINS	Null
   	name	vmName
   	clientName	vmName
   Clone, Linux with single NIC	host	Null
   	macAddress	Null
   	name	vmName
   	clientName	vmName

4. Define the in-parameter VM as input for the Custom decision and add the following script. The script will check whether the name of the OS contains the word Microsoft:

   guestOS=vm.config.guestFullName;
   System.log(guestOS);
   if (guestOS.indexOf("Microsoft") >=0){
   return true;
   } else {
   return false
   }

5. Save and run the workflow.

This workflow will now create a new VM from an existing VM and customize it with a fixed IP.

How it works…

As you can see, creating workflows to automate vCenter deployments is pretty straightforward. Dealing with the various in-parameters of workflows can be quite overwhelming. The best way to deal with this problem is to hide away variables by defining them centrally using a configuration, or define them locally as attributes.

Using configurations has the advantage that you can create them once and reuse them as needed. You can even push the concept a bit further by defining multiple configurations for multiple purposes, such as different environments.

While creating a new workflow for automation, a typical approach is as follows:

1. Look for a workflow that you need.
2. Run the workflow normally to check out what it actually does.
3. Either create a new workflow that uses the original or duplicate and edit the one you tried, modifying it until it does what you want.

A fast way to deal with a lot of variables is to drag every element you need into the schema and then use the binding to create the variables as needed.

You may have noticed that this workflow only lets you select vSwitch networks, not distributed vSwitch networks.

You can improve this workflow with the following features:

• Read the existing Sysprep information stored in your vCenter Server
• Generate different predefined configurations (for example DEV or Prod)

There’s more…

We can improve the workflow by implementing the ability to change the vCPU and the memory of the VM. Follow these steps to implement it:

1. Move the out-parameter newVM to be an attribute.
2. Add the following variables:
   

   Name	Type	Section	Use
   vCPU	Number	IN	This variable denotes the amount of vCPUs
   Memory	Number	IN	This variable denotes the amount of VM memory
   vcTask	VC:Task	Attribute	This variable will carry the reconfiguration task from the script to the wait task
   progress	Boolean	Attribute	Value NO, vim3WaitTaskEnd
   pollRate	Number	Attribute	Value 5, vim3WaitTaskEnd
   ActionResult	Any	Attribute	vim3WaitTaskEnd

3. Add the following actions and workflows according to the next figure:
   •      shutdownVMAndForce
   •      changeVMvCPU
   •      vim3WaitTaskEnd
   •      changeVMRAM
   •      Start virtual machine

   

4. Bind newVM to all the appropriate input parameters of the added actions and workflows.
5. Bind actionResults (VC:tasks) of the change actions to vim3WaitTasks.

See also

Refer to the example workflows, 7.02.1 Provision VM (Base), 7.02.2 Provision VM (HW custom), as well as the configuration element, 7 VM provisioning.

An approval process for VM provisioning

In this recipe, we will see how to create a workflow that waits for an approver to approve the VM creation before provisioning it. We will learn how to combine mail and external events in a workflow to make it interact with different users.

Getting ready

For this recipe, we first need the provisioning workflow that we have created in the Provisioning a VM from a template recipe. You can use the example workflow, 7.02.1 Provision VM (Base).

Additionally, we need a functional e-mail system as well as a workflow to send e-mails. You can use the example workflow, 4.02.1 SendMail as well as its configuration item, 4.2.1 Working with e-mail.

How to do it…

We will split this recipe in three parts. First, we will create a configuration element then, we will create the workflow, and lastly, we will use a presentation to make the workflow usable.

Creating a configuration element

We will use a configuration for all reusable variables.

Build a configuration element that contains the following items:

Name	Type	Use
templates	Array/VC:VirtualMachine	This contains all the VMs that serve as templates
folders	Array/VC:VmFolder	This contains all the VM folders that are targets for VM provisioning
networks	Array/VC:Network	This contains all VM networks that are targets for VM provisioning
resourcePools	Array/VC:ResourcePool	This contains all resource pools that are targets for VM provisioning
datastores	Array/VC:Datastore	This contains all datastores that are targets for VM provisioning
daysToApproval	Number	These are the number of days the approval should be available for
approver	String	This is the e-mail of the approver

Please note that you also have to define or use the configuration elements for SendMail, as well as the Provision VM workflows. You can use the examples contained in the example package.

Creating a workflow

1. Create a new workflow and add the following variables:
   

   Name	Type	Section	Use
   mailRequester	String	IN	This is the e-mail address of the requester
   vmName	String	IN	This is the name of the new virtual machine
   vm	VC:VirtualMachine	IN	This is the virtual machine to be cloned
   folder	VC:VmFolder	IN	This is the virtual machine folder
   datastore	VC:Datastore	IN	This is the datastore in which you store the virtual machine
   pool	VC:ResourcePool	IN	This is the resource pool in which you create the virtual machine
   network	VC:Network	IN	This is the network to which you attach the virtual network interface
   ipAddress	String	IN	This is the fixed valid IP address
   subnetMask	String	IN	This is the subnet mask
   isExternalEvent	Boolean	Attribute	A value of true defines this event as external
   mailApproverSubject	String	Attribute	This is the subject line of the mail sent to the approver
   mailApproverContent	String	Attribute	This is the content of the mail that is sent to the approver
   mailRequesterSubject	String	Attribute	This is the subject line of the mail sent to the requester when the VM is provisioned
   mailRequesterContent	String	Attribute	This is the content of the mail that is sent to the requester when the VM is provisioned
   mailRequesterDeclinedSubject	String	Attribute	This is the subject line of the mail sent to the requester when the VM is declined
   mailRequesterDeclinedContent	String	Attribute	This is the content of the mail that is sent to the requester when the VM is declined
   eventName	String	Attribute	This is the name of the external event
   endDate	Date	Attribute	This is the end date for the wait of external event
   approvalSuccess	Boolean	Attribute	This checks whether the VM has been approved

2. Now add all the attributes we defined in the configuration element and link them to the configuration.
3. Create the workflow as shown in the following figure by adding the given elements:
   •      Scriptable task
   •      4.02.1 SendMail (example workflow)
   •       Wait for custom event
   •       Decision
   •       Provision VM (example workflow)
4. Edit the scriptable task and bind the following variables to it:
   

   In	Out
   vmName ipAddress mailRequester template approver days to approval	mailApproverSubject mailApproverContent mailRequesterSubject mailRequesterContent mailRequesterDeclinedSubject mailRequesterDeclinedContent eventName endDate

5. Add the following script to the scriptable task:

   //construct event name
   eventName="provision-"+vmName;
   //add days to today for approval
   var today = new Date();
   var endDate = new Date(today);
   endDate.setDate(today.getDate()+daysToApproval);
   //construct external URL for approval
   var myURL = new URL() ;
   myURL=System.customEventUrl(eventName, false);
   externalURL=myURL.url;
   //mail to approver
   mailApproverSubject="Approval needed: "+vmName;
   mailApproverContent="Dear Approver,n the user "+mailRequester+" 
   would like to provision a VM from template "+template.name+".
   n To approve please click here: "+externalURL;
   //VM provisioned
   mailRequesterSubject="VM ready :"+vmName;
   mailRequesterContent="Dear Requester,n the VM "+vmName+" 
   has been provisioned and is now available under IP :"+ipAddress;
   //declined
   mailRequesterDeclinedSubject="Declined :"+vmName;
   mailRequesterDeclinedContent="Dear Requester,n the VM "+vmName+" has been declined by "+approver;

6. Bind the out-parameter of Wait for customer event to approvalSuccess. Configure the Decision element with approvalSuccess as true.
7. Bind all the other variables to the workflow elements.

Improving with the presentation

We will now edit the workflow’s presentation in order to make it workable for the requester. To do so, follow the given steps:

1. Click on Presentation and follow the steps to alter the presentation, as seen in the following screenshot:
2. Add the following properties to the in-parameters:
   

   In-parameter	Property	Value
   template	Predefined list of elements	#templates
   folder	Predefined list of elements	#folders
   datastore	Predefined list of elements	#datastores
   pool	Predefined list of elements	#resourcePools
   network	Predefined list of elements	#networks

3. You can now use the General tab of each in-parameter to change the displayed text.
4. Save and close the workflow.

How it works…

This is a very simplified example of an approval workflow to create VMs. The aim of this recipe is to introduce you to the method and ideas of how to build such a workflow.

This workflow will only give a requester the choices that are configured in the configuration element, making the workflow quite safe for users that have only limited knowhow of the IT environment. When the requester submits the workflow, an e-mail is sent to the approver. The e-mail contains a link, which when clicked, triggers the external event and approves the VM. If the VM is approved it will get provisioned, and when the provisioning has finished an e-mail is sent to the requester stating that the VM is now available. If the VM is not approved within a certain timeframe, the requester will receive an e-mail that the VM was not approved.

To make this workflow fully functional, you can add permissions for a requester group to the workflow and Orchestrator so that the user can use the vCenter to request a VM.

Things you can do to improve the workflow are as follows:

• Schedule the provisioning to a future date.
• Use the resources for the e-mail and replace the content.
• Add an error workflow in case the provisioning fails.
• Use AD to read out the current user’s e-mail and full name to improve the workflow.
• Create a workflow that lets an approver configure the configuration elements that a requester can chose from.
• Reduce the selections by creating, for instance, a development and production configuration that contains the correct folders, datastores, networks, and so on.
• Create a decommissioning workflow that is automatically scheduled so that the VM is destroyed automatically after a given period of time.

See also

Refer to the example workflow, 7.03 Approval and the configuration element, 7 approval.

Summary

In this article, we discussed one of the important aspects of the interaction of Orchestrator with vCenter Server and vRealize Automation, that is VM provisioning.

Resources for Article:

---

Further resources on this subject:

• Importance of Windows RDS in Horizon View [article]
• Metrics in vRealize Operations [article]
• Designing and Building a Horizon View 6.0 Infrastructure [article]

---