Part I. vSphere Tags and vRO 7
This is the first part of series of articles related to working with vSphere tags from vRrealize Orchestrator 7
Here we will discuss the tags, we’ll talk about the required setup for vRO to handle vSphere tags and will touch upon other related topics.
In Part II we will discuss vAPI in more details and will write custom JavaScript code.
In Part III we will see actual examples of workflows related to vSphere tags.
If you ever have to deal with vSphere tags from vRO then the below information can be helpful and can save you some time.
Without a further ado lets begin..
vSphere tags are used for attaching a meta data to an object.
It helps organizing objects in the inventory and makes them more sortable and searchable.
There are couple of interesting things when it comes to dealing with tags in some sort of programmatic way.
Tags are not part of the public vSphere API and they are also stored in different database – the Inventory Service database.
Prior vSphere 6 possible ways to manage vSphere object tags in a programmatic way were for example via PowerCLi or via vSphere MOB browser.
With PowerCLI one uses the tagging cmdlets( i.e add-tag), with vSphere MOB addTag and removeTag can be invoked on a vSphere object.
The overall tag management via API/SDK is not really a straightforward process and prior vSphere 6 wasn’t the most easy thing to do.
Luckily for us, there are now vSphere 6 and 6.5
And these two new versions bring new features and enhancements on the API/SDK level.
I am talking about vCloud Suite SDK( codenamed vAPI) available for vSphere 6. In vSphere 6.5 it was renamed to VMWare Automation SDK.
Lets focus on vSphere 6 and the vCloud Suite SDK or vAPI for short.
Note: Technically vCloud API is around for longer time ,related to vCloud Director. But we are referring in this article to vCloude Suite SDK, now part of vSphere 6. For a vCloud API reference the following guide can be consulted.
A new thing in vSphere 6 is that the tags are no longer stored in the Inventory Service database, but in the vCenter database(VCDB), in KV_STORE
For detailed information check VMWare KB 2130130
We will work with tags via vRealize Orchestrator 7, leveraging vCenter 6 vAPI.
Note: Installing and configuring vRealize Orchestrator and vRealize Automation will be covered in separate articles.
vCenter 6 vAPi is a vAPI endpoint which is accessible by client application via URL.Before working with the vAPI we need to configure the vRO to communicate with it.This is done via vAPI plug-in which comes with the vRO.
When we login with the vRO client, we navigate to the last tab (Plug-ins tab) ( note: change to Design or Run from the drop down menu):
This is the vAPI plug-in and once we configure it, under Endpoints and Metamodels, we will have the vAPI endpoint URL.
The format of vAPI endpoint is https://vcenter-fqdn/api and configuration is done via two workflows( as we will see).
Now, lets run the workflows. For this purpose we will need to navigate to the Workflows tab:
Under Library, we need to navigate to VAPI and there we see the two configuration workflows – Add vAPI endpoint and Import vAPI metamodel.
These are all built-in workflows coming with vRO( provided by VMWare). We can modify them if we need to ( recommended to duplicate them first).
And we can create our custom workflows as well( obviously).
It is important to first run Import vAPI metamodel – upon completion it imports the vAPI model metadata and creates the relevant vRO scripting objects.
It takes one mandatory parameter, the vAPI endpoint URL (format https://vcenter-fqdn/api)
Select Yes for secure connection and press Submit. Usually it executes successfully if DNS resolution is fine and the vCenter is reachable.
If everything is fine a green mark will appear under the workflow and if error – a red dot. Sample results are shown below:
As I said if there is a problem there will be this red dot and in the Logs tab a dump of the execution stack will be stored for troubleshooting.
Now, assuming the Import vAPI metamodel workflow completed successfully, then we need to run the second workflow – Add vAPI endpoint
The process is exactly the same as for vAPI metamodel workflow – one mandatory parameter – the vAPI endpoint URL
If successful – the configuration is done. If not – well…time for troubleshooting.
After we have executed these two workflows, the vAPI enpoint URL will appear under Metamodel and Endpoints sections of the vAPI plug-in.
If either is missing, there might be some problem so the above steps need to be repeated.
Usually there is one meta model, but the endpoints can be many.
In most cases, it is 1:1 mapping, but there might be multiple vCenter servers so multiple vAPI endpoints which will be stored under Endpoints.
After we made the vAPI configuration, we can continue with the tags. There are few built-in workflows related to tags and categories:
They are located in vAPi/Examples/vSphere.
I had a lot of fun while trying to create a tag with the Create tag workflow mainly because was failing due to providing wrong type of mandatory param.
Here is what I mean:
It has two mandatory parameters and while the first one is easy to get( browsing will lead to the vAPI plugin and Enpoints and will list the vAPI URL)
the second one – Tag category ID – is not so intuitive(at least that’s my opinion).
Now let me elaborate a bit on this. The format expected in Tag category ID is a vAPI proprietary URN long string ID which uniquely identifies an entity.
It is something like a distinguishedName(DN) in LDAP world( it seems to have the same concept)
Example – urn:vmomi:InventoryServiceCategory:b819db73-03c1-4b2a-a13e-300854124799:GLOBAL
What are the elements of the string:
urn – this is referred to as vCloud Director Object ID.
vmomi – VMware Managed Object Management Interface
InventoryServiceCategory – showing Category( can be also InventoryServiceTag for Tags) , the entry comes from a table – cis_kv_keyvalue in KV_STORE
GUID – the long sequence of numbers and letters looks like the 128 bit GUID. I guess an identifier of the particular object
GLOBAL – default scope.
Great, that is nice – we have a mechanism to refer uniquely to an object. But…the format of the ID is somewhat cryptic and not intuitive to work with.
So when you login to vCenter (VCSA )and you create ,say, a TEST tag category and you want the workflow to create your tag there, well…then…how this can be done?
How you would see your TEST tag category ID? Well finding an ID of a particular tag category requires some work.
We will use another workflow – List all tagging categories. It accepts one mandatory parameter – the vAPI enpoint URL and it outputs the ID of every category in a single line,separated with coma in the Log tab:
But from this output is not clear which ID is for which category. Besides when any workflow requires this kind of IDs as mandatory param to work, how would one know the exact format? The param just says – Tag category ID( or Tag ID in other workflows).
I was trying different things( for some of the readers this may be obvious thing from the very first look, but for some of us it took a bit of a time to do it)
and then I’ve decided to copy the whole thing – from urn: till :GLOBAL an it worked. The Create tag workflow completed successfully.
So I believe that we, the people creating the workflows, we should strive to make our workflows or any product, intuitive and easy to work with.
And in regard to built-in workflows , there could have been an information or an example in the Description of the workflow to show what the mandatory parameter is and how to be used.
Or why not using a category name as a param, instead of an ID( the name could be selected by the user in a drop down menu or other means, the categories enumerated in advance and the name mapped to the ID,etc).
Something like this in the workflow description could be very helpful for situation when the parameters are non-intuitive:
Now, the person who runs it will understand what is required and will be way easier to work with the workflow.
Continuing on the readability and intuitive use of the workflows – List All Tagging Categories workflow gives the category IDs.
And by using this category ID we can create tags via Create Tag workflow, so far so good.
Ok, but which ID is for which category? Lets imagine ( hypothetically) the person who runs it is being told to create a new Tag, called Not_Used, in category NON_PROD. And there are several categories. It can be frustrating – how to approach it ? Talking to admins, creating randomly and removing tags until it hits the right category ? That is not the way..
Instead an additional output entry – the category name – can be added and displayed like this:
Note that the print screen shows only one category, but there are more just not shown.
The output is each category on separate line with Category ID and Name. Now looks better with name and ID together right? 🙂
Also similar functionality can be added for the tags too which we will explore in further articles.
This is the end of Part I where we discussed the vSphere tags and we have introduced the vAPI – a mechanism which allows vRO to work with tags.
In Part II, we’ll focus more on exploring vAPI and will write some JavaScript code.
I hope you liked the article and you find the information useful.
If you have ideas or suggestion for improvement of the article let us know.
The information provided here is AS IS, be extra careful when performing any of the actions in production environment.
Angel Iliev
Latest posts by Angel Iliev (see all)
- vSphere Automation with vRO 7 – Tags and vAPI – Part II - November 29, 2016
- vSphere 6 Automation with vRO 7 – Tags and vAPI – Part I - November 25, 2016
Pingback: vSphere Automation with vRO 7 - Tags and vAPI - Part II - The Virtualist