My First vCenter Orchestrator Workflow – Part 4 – A look at the Powershell Plug-in

Orchestrate-FacilitateAlright!  So far throughout this series of posts we have installed, configured and setup vCenter Orchestrator; as well as created and tested the integration between both vCO and the vSphere Web Client.  So what’s next in my venture?  Well if you can remember back to Part 1 of the series I set out on a quest to develop a workflow that would take an un-configured host and go through a series of tasks to create datastores, rename networks, setup hostname, etc…  Basically configure it the way I wanted.  Now there are built-in workflows in vCO to do this, however I had already done this work inside of a PowerShell script – so my main goal was to get vCO to execute that script.  And this leads us to part 4!

So first off as I said above there are a ton of great built in workflows inside of vCO that can do pretty much anything.  Some things however, such as the ability to run a Powershell script, are missing!  Thankfully there is a thriving developers community built around vCO and it’s SDKs allowing third party vendors to release their own sets of workflows in the form of a plug-in.  So as you probably guessed by now we will need to install a plugin to handle our Powershell script execution.

This plugin is called the vCenter Orchestrator Plug-in for Microsoft Windows Powershell and can be found over on VMware’s site.  You will need to download this file.  Once you have your hands on the vmoapp file we need to go into the vCenter Orchestrator Configuration page (https://IP_OF_vCO:8283/) to install it.  Select Plug-ins from the left hand menu, then browse down to the Install new plug-in section.  Upload your file and click ‘Upload and install’, accept the EULA and away you go… If you browse back to the main Plug-ins page you will notice that it states the plugin will be installed at the next server startup; so if you wish you can do this task manually by going to Startup Options -> Restart Service.


At this point we can fire up our vCO client.  Having a look in the Library of workflows we can now see a PowerShell folder.  Expanding this out further let’s us see some of the workflows that come packaged with the plug-in.  So we now have a few configuration steps we need to go through before executing scripts with this plug-in.

First off we need setup a PowerShell host.  A PowerShell host is simply a Windows machine with Powershell installed located somewhere in your environment that will handle the storing and executing of the scripts.  There is a great article on all of the steps here but I will go through explaining them all as well.   Keep in mind this might not be the most secure of ways to go about everything – but this is simply a lab so I’m not too worried – for those concerned w/ security implications check out the full lengthy thrilling winrm read on the msdn 🙂   

So, once you have chosen which machine you would like to be your Powershell host go ahead and drop to a command prompt on that machine and run the following list of commands.

  • To create a winrm listener and open any required firewall ports
  • winrm quickconfig
  • To enable kerberos authentication
  • winrm set winrm/config/service/auth @{Kerberos=”true”}
  • Allow transfer of unencrypted data – told you wasn’t the most secure 🙂
  • winrm set winrm/config/service @{AllowUnencrypted=”true”}
  • Up the max memory per shell – I needed to do this to get things working
  • winrm set winrm/config/winrs @{MaxMemoryPerShellMB=”2048″}

And there we are!  Things should be setup fine now on our host end to allow the connections from our vCO server.  Now we need to configure kerberos on the vCO end of things.  To do this you will need to console into your vCO server and get on the command line there – hope your comfortable with vi 🙂

Basically we need to create a file under /opt/vmo/jre/lib/security called krb5.conf – to do so simply

cd /opt/vmo/jre/lib/security
vi krb5.conf

This file will need to look as follows – obviously change to fit your environment – if you happen to be using an default configuration of the autolab then you are good just to copy the following…

default_realm = LAB.LOCAL
udp_preferences_limit = 1
kdc = dc.lab.local
default_domain = LAB.LOCAL

Once you are done simply hit :wq to save and exit.  In order to grant vCO permission to access our newly created krb5 file you will also need to change ownership of the file using the following command

chown vco.vco krb5.conf

And, in order for changes to take affect, restart the vCO service – you can do this from the configuration page->Startup Options or simply

service vcod restart

Whew!  Ok!  Getting somewhere….Now we need to add the host into our configuration of the Powershell plug-in.   I find the easiest way to do this is to simply run the ‘Add a Powershell Host’ workflow however you can develop the script/code on the fly to add the host during your own workflow if you want.   The way I have documented however is as follows…

Browse to the PowerShell plug-in configuration by expanding Library->PowerShell->Configuration in the workflows view of your vCO Client.  Right click ‘Add a PowerShell host’ and select Start Workflow.


Here we need to add a few key pieces of information.  Enter a name for your PowerShell host – this can be whatever you wish, then enter the HOSTNAME of the host you setup (kerberos will not work with IP)   and click Next.


The only item that needs to be changed on the Host Type screen is Authentication; be sure Kerberos is selected and click ‘Next’.


In the User Credentials screen you have a couple of options in regards to Session mode.  Again since this is a lab environment I selected Shared Session, however if you were looking at a more production type deployment you might want to explore the Per User settings which will execute commands under the credentials of the current user connected to vCO.  Enter in some credentials with access to vCO and click ‘Submit’.  The workflow should kick off and you can watch it flow through the different elements.  When done, hopefully you have a nice green check mark beside it!

Now that we have successfully installed the Powershell plug-in and added a Powershell host lets go ahead and create a script on our Powershell host to run in order to make sure everything works.  Although my end goal is to completely configure a host –  for simplicity sake I’ll use a small snippet of the complete script.  So I have placed the following script on my PowerShell host to simply add a new VM Network to vSwith0.  As you can see the script is pretty simple, takes two parameters, a host and a location code.  The location code is used to represent uniquness in my environment and is actually used multiple times in the complete script for the hostname, datastores, etc….

param ($hosttoconfigure, $locationcode)
add-pssnapin VMware.VimAutomation.Core
$username = "Host Username"
$password = "Host Password"
$success = Connect-VIServer $hosttoconfigure -username $username -Password $password
Get-VirtualSwitch -Name vSwitch0 | New-VirtualPortGroup -Name "$locationcode-VM_Network" -confirm:$false

So let’s get started on our workflow to call this script.  Again, create a new workflow and call it what you will.   Once you are in the workflow editor move to the Inputs tab.  Here we will get the information from the user that we require in the script.  So go head and add a couple of inputs to the workflow, one being hosttoconfigure (Type VC.HostSystem) and locationcode (Type String).


By selecting our host parameter and clicking the eye icon we can set the ‘Show in Inventory’ presentation property on the host input.  This will basically allow the user to browse through their vCenter to select the host when running the workflows, so might as well go ahead and do that as well.


The Powershell workflow that we will be using is called ‘Invoke and external script’ and requires 3 parameters; One, a Powershell Host which we have setup previously, the second is the script to execute, and the third is the arguments to pass to the script.


Once on the Schema tab go head and drag the ‘Invoke an external script’ workflow into yours.   When you see the parameter setup black bar pop up click ‘Setup’ and we can have a look at the parameters.


Through this screen we can basically promote or link the parameters from the Script workflow to our main workflow.  You can see that I’ve done a few things.  One, I’ve set the host parameter to a value (same as creating an attribute) and browsed through my inventory to select my Powershell host that we created previously.  Secondly I manually inputted the path to my Powershell script in the externalScript parameter.  Thirdly I selected to skip the arguments parameter at this time.  I’ve done this because I need to pass the hostname as well as the locationcode parameter from my main workflow to this parameter which we will do with a separate element called a Scriptable task.  Go ahead and click ‘Promote’.


So now we have our main input parameters setup (locationcode and hosttoconfigure) as well as our script setup and ready to go.  We just need to tackle that arguments parameter.  As I said we will do this with a separate Scriptable Task workflow so go ahead and drag that into your schema, just before your Invoke External Script.   A scriptable task is just that, kind of a blank canvas to do any sort of scripting (javascript) that you desire.


So let’s go ahead and click the pencil icon to edit our scriptable task.  There are few IN parameters that we are going to need inside of our script; The first is hosttoconfigure and the second is locationcode.


Now move on to the OUT parameters.  We will need to create a new out parameter to store our arguments, so click the link for a new parameter and create a new workflow attribute called scriptArgs of type string.

Now we need to move to the Scripting tab.  This is where we can concatenate a property of the hosttoconfigure parameter and the locationcode to populate our newly created scriptArgs variable.  Honestly it’s a one-liner.  I’m sure there is a way to create this workflow without even requiring this whole Scriptable task but this is the way I got to to work (again, my FIRST vCO workflow).  Copy/Paste the following into your scripting tab.

scriptArgs = hosttoconfigure.Name + " " + locationcode;

Ok, you can close out of your Scriptable task workflow now.  We are almost there.  All that we have left to do is map the External Script workflow paramater arguments to our Scriptable task elements parameter scriptArgs.  Thankfully this is an easy thing to do.


Once again go into your External Script element and click on the Visual Binding tab.  Here, as shown above, we simply need to drag the scriptArgs in attribute over to the arguments in parameter.


Guess what!  Your done!  If everything has been setup properly and I’ve done a good job at explaining what to do then you should be able to Save and Close your workflow and actually run it on a host (a test host of course).  The result – you should get a VM Network setup on vSwitch0 – oh and a pretty green checkmark beside your workflow 🙂

At this point I’m going to cut off this post since it’s getting pretty long.  That being said I’m not going to end the series!  I’m always looking at ways to better automate things and you know, having users type in that location code just isn’t good enough for me, a lot of room for error there; they could type it in wrong, do the same location twice, on and on and on…  And hey, I have a database already setup with my location codes in it and whether or not they have already been deployed.  So, stay tuned for Part 5 of my series where we will go through configuring the SQL plug-in and setting up our location input parameter to be populated by an SQL table – as well as update that same table on completion of our script.

My first vCenter Orchestrator Workflow