How to plug PowerShell scripts into vCenter Orchestrator

Administrators using vCenter Orchestrator who rely on their PowerShell scripts can develop workflows to make vSphere management more streamlined.

The first part of this series explained how administrators register and integrate vCenter Orchestrator in the vSphere...

Web Client to execute workflows within the client.

The default workflows from vCenter Orchestrator (vCO) are very useful and perform a variety of different functions. However, there are a number of tasks we might want to execute via PowerShell script. In this post, I'll show how to install the PowerShell plug-in within vCO and then build a workflow to execute one of those PowerCLI scripts located on a Windows server.

Install the PowerShell plug-in
VMware built vCO so its capabilities can be extended with plug-ins. A vCO plug-in normally includes a set of workflows and a software developer's kit (SDK) we use with our own workflows to orchestrate and automate different parts of the environment. You can view and download plug-ins from VMware and third parties on the VMware Solutions Exchange site.

As shown below, the PowerShell plug-in requires us to upload the "dar" file, provide some administrative credentials to vCO and click Install. Most plug-ins require us to restart the vCO server service; this is done in the Startup Options section by clicking Restart service.

Installing the PowerShell plug-in
Installing the PowerShell plug-in in vCenter Orchestrator.

Configure the PowerShell plug-in

Once the PowerShell plug-in has been installed, begin the configuration. The PowerShell plug-in uses a PowerShell host. A PowerShell host is an instance of Windows that executes the scripts. We connect and authenticate to the PowerShell host through Kerberos authentication. A few steps will need to be completed to prep both our PowerShell host and vCO to use Kerberos before we can add the PowerShell host to the inventory.

Set up Kerberos authentication on the Windows server

On the Windows server we will use as the PowerShell host, we need to run a few commands to set up Windows Remote Management (WinRM) to allow the remote connections from vCO. Go to a command prompt and execute the following commands:

winrm quickconfig

winrm set winrm/config/service/auth @{Kerberos="true"}

winrm set winrm/config/service @{AllowUnencrypted="true"}

winrm set winrm/config/winrs @{MaxMemoryPerShellMB="2048"}

Set up Kerberos authentication on vCO

We also need to tell vCO we will use Kerberos authentication by creating a krb5.conf file. Unfortunately for those not comfortable with Linux bash environments, it can only be done on the command line of our vCO server. 

The location of this file differs across vCO versions; in 5.1 it was located at /opt/vmo/jre/lib/security/krb5.conf and in 5.5 it is located at /usr/java/jre-vmware/lib/security/krb5.conf.  

We need to create this file, with the contents below -- replace LAB.LOCAL domain with your domain name -- in the proper location. Once the file has been created, it's recommended to set your Linux permissions to 644 as well.

default_realm = LAB.LOCAL
udp_preferences_limit = 1   [realms]
kdc = dc.LAB.LOCAL
default_domain = LAB.LOCAL
}   [domain_realms]

Add PowerShell host to vCO inventory

After completing the Kerberos configuration, we add the PowerShell host to the vCO inventory. After launching the vCO client and expanding the PowerShell folder, there is a workflow for this purpose aptly named Add a PowerShell host

Right-click and run this workflow to display a few required input parameters. Input the fully qualified domain name of the PowerShell host along with some proper credentials to ensure we have selected Kerberos as an authentication type. Once finished, the PowerShell host should be visible and accessible from within the inventory. Now we can begin to create a workflow to execute our PowerCLI scripts.

Add the PowerShell host
Add the PowerShell host to the vCenter Orchestrator inventory.

A script to rename VMs

For the sake of this post, let's assume we were looking to automate the following PowerCLI script named RenameVMsToUpper.ps1 located in c:\scripts on the PowerShell host.

param ($vmhost)
$vcenter = "vcentername"
$username = "username"
$password = "password"
$ErrorActionPreference = "silentlycontinue"
Add-PSSnapin VMware.VimAutomation.Core
Connect-viServer $vcenter -user $username -Password $password | out-Null
Get-VMhost $vmhost | Get-VM | foreach-object { Set-VM -VM $_ -Name $_.Name.ToUpper() -confirm:$false }

The script takes in one parameter -- a string variable representing the name of an ESXi host. It then retrieves all virtual machines (VMs) on the host and changes the existing name to one with all uppercase characters. It's not the most complex of scripts but an example of how to automate PowerCLI scripts with vCO.

Create the workflow

To execute this script from vCO, we create a new workflow. To create a new workflow, right-click the workflow tab in the vCO client, select New Workflow and give it a name. 

In the workflow editor, set up a couple of input parameters, which is done in the Inputs tab. The first parameter is the host object we would like to execute this workflow on. Let's call this vmhost and make it a type of VC.HostSystem. Additionally, since the script arguments can only receive a string parameter, we will also need to set up an input parameter (vmhostname) of type String.

Add input parameters
Add input parameters in the vCenter Orchestrator workflow editor.

Add properties to parameters

From here, we can move onto the Presentation tab. Input presentation allows us to add various properties to our parameters to better define how they are displayed or calculated. For this workflow, we will need to add a couple of presentation properties. 

First, we will want to add a Default Value property to our vmshostname variable and ensure we have selected the "double arrow" icon next to value. This will allow us to calculate the value using standard Object Graph Navigation Language (OGNL) syntax. For the value definition, we can reference the name property of our vmhost variable by inputting #vmhost.name. This sets up the string version of our host name in thevmhostname variable we need to pass to our script. 

Add presentation properties
Add presentation properties to the vmhostname variable.

As for vmhost, we can go ahead and add the Show Parameter Input property and set it to false. Since the workflow will be implemented by right-clicking on a host in the vSphere Web Client, we do not need to show the selection of a host; it will be passed through to the workflow automatically.

Set presentation properties to the vmhost
Set presentation properties to the vmhost variable.

Next, go to the Schema tab and drag the Invoke and external script into our workflow. The prompt will display the option to add the activity's parameters as inputs and outputs on the main workflow. This allows us to take the inputs and outputs from the Invoke and external script workflow and embed them into the newly created workflow. Click Setup on the message near the top of the screen to open the Promote workflow parameters dialog box.

Activity prompt
The prompt in vCO asks if you want to add the activity's parameters as inputs and outputs on the main workflow.

Fine-tune the variables

The setup of the variables is simple. The host variable mapping type is set to Value using the name of our PowerShell host. The externalScript variable is set a Value pointing to the path of the script that contains the syntax described earlier. For now, set the arguments parameter to Skip; we will map it to our vmhostname variable in the next step.

Adjust the input/output parameters
Adjust the input/output parameters on the workflow.

To pass the vmhostname variable into the script arguments, go into the Visual Binding tab of the Invoke an external script workflow. As shown below, to map the vmhostname variable to the arguments variable, drag vmhostname on top of the arguments parameter.

Pass the vmhostname variable
Pass the vmhostname variable into the script arguments.

Complete the vSphere Web Client integration

You can save and close the workflow. The only thing left is to tell the vSphere Web Client that the workflow can be executed contextually by right-clicking on a host. To do this, go to the Context Actions section of the Manage tab from the vCO Home section in the vSphere Web Client. Click the + to create a new context action. In the Add new workflow dialog, browse to find the workflow and click Add, then at the bottom of the dialog, select the host object and click OK.

Set up the vSphere Web Client to add the workflow
Set up the vSphere Web Client to add the workflow to a context menu.

This completes the configuration process. Now, when you right-click on a host, the RenameVMs workflow should be displayed when selecting the All vCenter Orchestrator Actions menu.

The workflow appears under the All vCenter Orchestrator Actions menu
After the configuration is complete, the workflow appears under the All vCenter Orchestrator Actions menu.

While the script is basic, this tutorial should show how powerful vCO can be by bringing some new life into the libraries of PowerCLI scripts an administrator uses frequently.

Dig Deeper on Scripting administrative tasks