vSphere 5.1 Update 1 released

VMware has released vSphere 5.1 Update today. This update brings tons of fixes and enhancements to vSphere 5.1 product family, including new release of vCloud Director. Updated products with links to their release notes are below.

For vCenter Server one of most notable changes is that it is now officially supported on Windows Server 2012 and with Microsoft SQL Server 2012. There are also multiple security issues fixed in Tomcat server shipping with vCenter Server, along with updated Oracle JRE.

Removing vDS VXLAN virtual wires using vCenter Orchestrator

In my previous article I wrote about provisioning vNetwork Distributed Switch backed VXLAN virtual wires using vCenter Orchestrator (vCO) and vCloud Network and Security (vCNS) REST API. In this article I will show you how to remove them using vCO. I will not go into details of creating REST workflow elements in this article, see my previous article for more information on that.

First thing you should note is that you should never ever remove a VXLAN virtual wire port group directly from vDS using vSphere Client. You must always remove VXLAN networks through vCNS (vShield Manager) to keep your VXLAN network database in sync.

To start with we need to go to vShield API Programming Guide and look at “Delete a VXLAN Virtual Wire” REST API example.

Request:
DELETE https://vcns-ip-or-fqdn/api/2.0/vdn/virtualwires/virtualWireID

Looks simple enough, we just need to know ID instead of name of each virtual wire we wish to remove. This requires some work so lets get to it, finished workflow should look close to this:

image

Listing all VXLAN virtual wires

Listing all virtual wires of a vCNS instance is just a simple GET request

Request:
GET https://vcns-ip-or-fqdn/api/2.0/vdn/virtualwires

Response is a XML document containing all VXLAN virtual wires managed by our vCNS, response will be passed as string to next workflow element.

Parsing XML response

imageWhile listing of all virtual wires is easy as single GET request, we need to do some scripting to parse REST response.

Input parameter containing REST response will be string type variable and it is hard to work with as is so we should convert data into XML type variable for easier access. As content is already in XML format simple typecasting using XML() will do. Once data is in XML type variable we can read values from it by simply accessing XML elements as variables, for example first virtual wire name is located in xmlDoc.dataPage.virtualWire[0].name, ID of this virtual wire is in xmlDoc.dataPage.virtualWire[0].ObjectId and so on.

We are looking for VXLAN virtual wire ID by virtual wire name, so we need to match input parameter containing name against xmlDoc.dataPage.virtualWire[i].name in a loop through all virtual wires.

Once we have match for virtual wire name we can fill output parameter with xmlDoc.dataPage.virtualWire[i].objectId. There is a important catch however, when assigning variable from XML you must typecast output parameter as String. If you fail to do this vCO may pass output parameter as invalid (empty) input parameter for next workflow element. I wasted several hours of my own and @joerglew’s (Sorry Joerg!) time for debugging why vCO was passing empty parameters because of this.

Parameters of “Get virtual wire ID” Scriptable Task element should consist of

Input

  • contentAsString: string
  • vxlanNetwork: string

Output

  • virtualWireID: string

Complete script content

Removing VXLAN virtual wire

We got our virtual wire ID in previous workflow element so you can pass it as input parameter for your “Delete VXLAN virtual wire” REST API workflow element.

Provisioning vDS VXLAN virtual wires using vCenter Orchestrator

Recently while I was working on vSphere infrastructure automation processes I came up with a need to provision vNetwork Distributed Switch VXLAN virtual wires using vCenter Orchestrator 5.1 (vCO). I learned that there is no VMware vCloud Networking and Security (vCNS) plug-in for vCO 5.1 so I had to come up with a way to tap into vCNS from vCO.

vCenter Orchestrator has REST plug-in which allows easy integration with any RESTful service so I ended up looking at REST API on vCNS. As a first thing I glanced through vShield API Programming Guide and it become clear that it is very easy to command vCNS through a REST API so my disappointment for not having a vCNS plug-in for vCO was quickly forgotten.

For a quick example on how to create a new VXLAN virtual wire using vCNS, just send POST request to https://vcns/api/2.0/vdn/scopes/scopeID/virtualwires with request body of

vCenter Orchestrator workflow

I deployed VXLAN using vShield Manager web console and I started to work on my virtual wire provisioning workflow.

Connecting to a vCNS REST API

Before I was able to connect vCO to vCNS I had to install untrusted SSL certificate of vCNS into vCO. This is done by running “Manage SSL certificates” workflow in vCO. I guess this step is not necessary if your vCNS is using trusted SSL certificate.

image

For some odd reason I had to use vCNS host IP address instead of FQDN in host URL to make vCO to download the certificate. Any time I tried with FQDN I just got an error message about URL being invalid.

Now that SSL certificate was installed I was ready to connect vCO to vCNS REST API, this is done by running a “Add a REST host” workflow in vCO. You have to enter following data for this workflow:

  • Name: vCloud Network and Security (or anything you want)
  • URL: https://vcns-ip-or-fqdn/api/2.0
  • Host’s authentication type: Basic
  • Session mode: Shared session or Per User Session

Adding a REST operation

Next step was to run a “Add a REST operation” workflow

image

Parent host should be REST host added in previous step. Template URL is URL for this REST operation. Note that I have {scopeId} in this URL, this means that {scopeID} is a parameter which we need to set for this operation.

Creating a workflow

Once REST operation is added we need to create a workflow of it so we can execute this operation. This is done by running a “Generate a new workflow from a REST operation” workflow, for this you need to browse for recently added REST operation for Operation input.

image

I now had a bare workflow for executing a REST operation on vCNS, this workflow does however require XML request body as string so I had to do some scripting to build  necessary XML request. I created a “Create VXLAN Virtual Wire” workflow and gave it following input parameters:

  • vxlanName: string
  • vxlanDesc: string

and created following attributes

  • scopeId: string: value vdnscope-1
  • tenantId: string: value production
  • content: string

then I dropped in Scriptable task element and “Invoke ‘Create VXLAN Virtual Wire..’” workflow I had previously created in my workflow schema

image

In Scriptable task element I mapped in vxlanName, vxlanDesc and tenantId input parameters and wrote following code

and I mapped content source attribute to content attribute as output value.

In “Invoke ‘Create VXLAN Virtual Wire..’” element I mapped in scopeID and content attributes and all output parameters to NULL. My workflow was done. I executed this workflow, entered input parameters and watched as VXLAN virtual wire was deployed in vDS.

VDN Scope and Tenant ID

You may have noticed that I had two preset attributes in my workflow, scopeId and tenantId. To find out what your scopeId is you can use any REST client to query this information from vCNS, I used Postman REST Client extension for Chrome web browser, just send GET request to a https://vcns/api/2.0/vdn/scopes.

image

To find out tenantId I created virtual wire using vShield Manager and sent GET request to https://vcns/api/2.0/vdn/virtualwires, tenantId is returned as part of virtual wires output.

Automate VMware Tools upgrade using vCenter Orchestrator

Keeping VMware Tools up to date can be somewhat challenging as up until vSphere 5.1 installing updated version of VMware Tools requires a guest OS reboot which in many cases is not possible during normal operation hours. There is a simple solution though, in Virtual Machine settings on options tab and in VMware Tools settings there is a checkbox “Check and upgrade Tools during power cycling

CheckAndUpgradeToolsDuringPowerCycling

What this setting does, is that in case VMware Tools are out of date, and there are updated version available on ESXi host, VM will perform automatic VMware Tools update during any guest OS shutdown or startup event. I have used this feature with Windows VMs for years and it has proven to be reliable and very useful. With Linux VMs I would still go with manual VMware Tools update process, although automatic update of VMware Tools is supported on Red Hat Linux VMs.

So this is very handy feature, but this setting is not set by default, and going through all VMs in your infrastructure can be quite tedious task if done manually. Instead of clicking through all your VMs you can use an pretty simple vCenter Orchestrator workflow to configure all your Windows VMs for this.

With vSphere 5.1 vCenter Orchestrator (vCO) is configured automatically so I won’t go through all steps required for manual vCO configuration. If your vCO installation is not set up, please go through “Installing and Configuring VMware vCenter Orchestrator” document, you can get vCO up and running in no time with vSphere 5.1. Or you can leave a comment below and I will try to assist.

vCenter Orchestrator workflow

I have created a simple vCO workflow to set VMware Tools update policy to automatic for all Windows VMs in a vSphere cluster. Workflow has following steps:

  1. Get list of all VMs of a vCenter Server cluster object
  2. Loop through all VMs
  3. Check the guest OS id returned by VM object, if Windows check VMware Tools upgrade policy
  4. If Tools update policy is automatic already, skip to a next VM
  5. If Tools update policy is manual, reconfigure VM with automatic VMware Tools upgrade policy

Schema of workflow looks like this, click the image below to see it in greater detail

vco-enableVMtoolsUpgrade-schema

JavaScript used in the workflow

vCenter Orchestrator uses JavaScript as its scripting language. Usually you just need to write simple logic code which does not require much of learning if you already know any other scripting language like Perl, Python or PowerShell. I am no programmer by any means and I was able to pick necessary skills for JavaScript in few days.

More complex code like vSphere API calls can be generated automatically with help of VMware Fling Onyx. For example I used Onyx to create API call code for “Set VM Tools Update” script block in this workflow. Onyx is available at http://labs.vmware.com/flings/onyx.

Here are key parts of JavaScript code used in this workflow so you get an idea how Orchestrator scripting looks like.

NeedToSet
Custom decision object “Need to set?” script to check guest OS type and Tools upgrade policy

curVM is a VM object picked up from array of all VMs in a cluster. In that VM object you have all properties of a VM, including guest OS type.

By matching guest OS type to a keyword “windows” we are able to figure out if VM we are processing is a Windows VM or not. If guest OS type is Windows then we check its VMware Tools upgrade policy to avoid unnecessary reconfiguration operations. If VMware Tools update policy is not “upgradeAtPowerCycle” we will exit this Custom description type workflow object with return code “true” which will lead to “Set VM Tool Update” workflow object.

SetVMtoolsUpdate
“Set VM Tools Update” script object code

In this workflow object we have a code which will set VMware Tools update policy of a current VM to “upgradeAtPowerCycle”. Before we apply this configuration script will sleep for a one second to avoid sending configuration tasks to a vCenter Server with too high rate.

These are two most complex JavaScript code blocks used in this simple workflow.

How to import workflow

To install this workflow download it from a link at the end of this article. Once you have downloaded workflow file open vCO client, login to vCO server and in client select workflows tab as shown on image below

Workflows_Tab

First you need to decide where to import workflow. You can either create a new folder for imported workflows by right clicking at the top most menu item and selecting “Add folder…”, or you could import workflow to a existing folder, like “Library”.

Now right click desired folder and select “Import workflow…” and browse workflow you downloaded. Once done should have “Enable VM Tools upgrade on VM power cycle” workflow added into your workflow inventory.

NewWorkflowImported

How to execute workflows

With release of vSphere 5.1 accessibility of vCO workflows has improved a lot. Before vSphere 5.1 you had either to use vCO client or some custom interface to run workflows, in vSphere 5.1 ability to execute vCO workflows is integrated in new vSphere Web Client!

You can execute workflow from vCO client by right clicking a workflow and selecting “Start workflow…” or you can just select it and press CTRL+R. vCO client will then open a dialog window to ask necessary input parameters for a workflow. In case of workflow show here you need to select vCenter Server cluster object in which you wish to execute this workflow. To get list of cluster objects click “Not set” link and press enter in “Filter:” input box, vCO client will then search for all cluster objects and list them for you to choose.

Alternatively you can associate this workflow to a cluster object in vSphere Web Client for easy access.

Login to vSphere Web Client with administrator privileges, and click “vCenter Orchestrator” link on the left side menu.

WebClient_vCenter_Orchestrator

In next view you should see “vCO Servers: 1” on left side menu if your vCO is properly registered with VMware SSO and Web Client services. Integration is configured automatically when doing vCenter Server Simple install.

If you have vCO registered select “Manage” tab, and click green plus sign to add a new workflow association.WebClient_vCenter_Orchestrator_Manage

Next browse workflow from the tree menu on the left side, click “Add” and select “Cluster” from available type list.

WebClient_vCenter_Orchestrator_AddWorkflow

Now you have associated this workflow with vSphere cluster object, to run workflow go and right click any cluster in Web Client and select workflow from “All vCenter Orchestrator Actions” menu. Any changes made by workflow are listed in Cluster –> Monitor –> Tasks view.

WebClient_All_Orchestrator_Actions

Workflow download

Feel free to download this workflow from link below, you may use, distribute and modify it as you wish. I will not provide any guarantee that this workflow will work as intended in your environment.

http://v-reality.info/files/EnableVMToolsUpgradeOnVMPowerCycle.workflow