Custom Attributes and Tags (vAPI)

In this recipe, we will see how to create and use custom attributes and tags. We are talking about vCenter tags and not about Orchestrator tags, which have no common ground. This recipe will also use the vAPI plugin.

Getting ready

You need to have a VM to which you can tag or assign a custom attribute.

For tagging, you need to have a vAPI vCenter Endpoint. See the Getting started with vAPI recipe in this chapter.

How to do it...

We will split this recipe into two parts. The first part concerns Custom Attributes, while the second concerns Tags.

Custom Attributes

Please note that Custom Attributes are only visible in the vSphere Client (also called Fat client or c-Client).

We will now work through the lifecycle of a Custom Attribute:

  1. Create a new workflow.
  2. Drag the setOrCreateCustomField action onto the schema. This action will create a definition and set a value to an object.
  3. Drag the getCustomField action onto the schema. This action will read a Custom Attribute from an object.
  4. Now assign all the variables as input parameters.
  5. Change the type of managedEntity from Any to VC:VirtualMachine.
  6. Drag a scriptable task onto the schema. The following script will create the delete custom attribute:
          var vimHost = managedEntity.vimHost; 
      var key; 
        var customFieldDefs = vimHost.customFieldsManager.field; 
        for (var i = 0; i < customFieldDefs.length; i++) { 
          if (customFieldDefs[i].name == customFieldName) { 
          key = customFieldDefs[i].key; 
            break; 
          } 
        } 
        vimHost.customFieldsManager.setField(managedEntity, key, "");
  7. Drag a scriptable task onto the schema. The following script will delete the custom attribute definition:
          var vimHost = managedEntity.vimHost; 
      var customFieldDefs = vimHost.customFieldsManager.field; 
        for (var i = 0; i < customFieldDefs.length; i++) { 
          if (customFieldDefs[i].name == customFieldName) { 
            key = customFieldDefs[i].key; 
            break; 
          } 
        } 
      vimHost.customFieldsManager.removeCustomFieldDef(key);
  8. Now assign all the variables as input parameters.
  9. Change the type of managedEntity from Any to VC:VirtualMachine.
  10. Save and run the workflow.

See also the example workflow 12.02.1 Custom Attribute Lifecycle.

vSphere Tags

We will now work with Tags using the vAPI:

  1. Create a new workflow with the following variables:

    Name

    Type

    Section

    Use

    endpoint

    VAPI:VAPIENDPOINT

    IN

    The endpoint we want to use

    tagCatName

    String

    IN

    Name of the tag category

    tagName

    String

    IN

    Name of the tag

    tagValue

    String

    IN

    Value of the tag

    VM

    VC:VirtualMachine

    IN

    VM to tag

    tagCatID

    String

    Attribute

    ID of the tag category

    tagID

    String

    Attribute

    ID of the tag

  2. Drag a scriptable task onto the schema. The following script will create a new tag category. Define tagCatID as OUT:
          var client = endpoint.client(); 
      var tagging = new com_vmware_cis_tagging_category(client); 
      var spec = new com_vmware_cis_tagging_category_create__spec(); 
      spec.name = tagCatName; 
      spec.description = tagDesciption; 
      spec.cardinality = "MULTIPLE"; 
      spec.associable_types = ["VirtualMachine"]; 
      var tagCatID = tagging.create(spec);
  3. Drag a scriptable task onto the schema. The following script will create a new tag using the created tag category. Define tagID as OUT:
          var client = endpoint.client(); 
      var tagging = new com_vmware_cis_tagging_tag(client); 
      var spec = new com_vmware_cis_tagging_tag_create__spec(); 
      spec.category_id = tagCatID; 
      spec.description = tagDesciption; 
      spec.name = tagName; 
      var tagID = tagging.create(spec);
  4. Drag a scriptable task onto the schema. The following script will associate a tag with a VM:
          var client = endpoint.client(); 
      var tagging = new com_vmware_cis_tagging_tag__association(client); 
      var objectId = new com_vmware_vapi_std_dynamic__ID() ; 
      objectId.id = VM.id; 
      objectId.type = VM.vimType; 
      tagging.attach(tagID, objectId);
  5. Drag a scriptable task onto the schema. The following script will read all tag and tag category information:
          var client = endpoint.client(); 
      var tagging = new com_vmware_cis_tagging_tag(client); 
      var tag = tagging.get(tagId); 
      System.log("Name :"+tag.name+"
Category
      :"+tag.category_id+"
Deciption :"+tag.description); 
 
      tagCatID=tag.category_id; 
      var tagging = new com_vmware_cis_tagging_category(client); 
      var tagCat = tagging.get(tagCatID); 
      System.log("Name :"+tagCat.name+"
Category
      :"+tagCat.cardinality+"
Deciption :"+tagCat.description+"
Types 
      :"+tagCat.associable_types);
  6. Drag a scriptable task onto the schema. The following script will delete a tag from a VM:
          var client = endpoint.client(); 
      var tagging = new com_vmware_cis_tagging_tag(client); 
      tagging.delete(tagID);
  7. Drag a scriptable task onto the schema. The following script will delete a tag category:
          var client = endpoint.client(); 
      var tagging = new com_vmware_cis_tagging_category(client); 
      tagging.delete(tagCatID);
  8. Assign all the parameters and then run the workflow. For testing purposes, you may want to comment the delete instructions from Steps 6 and 7 out.

The Notes field

The only field that is the same in vSphere Client and vSphere Web Client is the Notes field. Here is how to read it:

content=vm.config.annotation;

Here is how to set it:

var spec = new VcVirtualMachineConfigSpec();   
spec.annotation = "test";   
vm.reconfigVM_Task(spec);

How it works...

This recipe is actually more about the changes in vSphere in the last couple of years. Until vSphere 5.5 and the first real workable vSphere Web Client, the vSphere Client using Custom Attributes have been the way to handle things. With vSphere 6, vAPI and a higher value in vSphere Web Client tagging is the way to go.

With the instructions in this recipe, you could create a workflow that transports your Custom Attributes into Tags:

How it works...

Custom Attributes

Custom attributes are actually two things. First, we have the custom attribute definition and then we have the custom attribute value. The definition is set once and is then available for all (or almost all) objects inside vCenter. A value is specifically assigned to one object. For instance, you set a Definition called Manager. This field is now available to all objects in vCenter. Then you define a value of Mickey Mouse to one (or more) VM(s).

There are basically only three methods of customFieldsManager that we are using:

Method

Description

addCustomFieldDef()

Adds a definition to vCenter.

removeCustomFieldDef()

Removes a definition from vCenter.

setField()

Sets a value to an object.

vAPI tagging

Tagging is one of those things that has been missing from Orchestrator since their introduction. The only way around that was to use PowerShell. With the vAPI, things are easier.

Tags in vSphere are a combination of a tag category and the Tag itself. Both items are available for all vCenter objects. The tag category can be limited to specific types of Objects, for example, virtual machines. In addition to this, a tag category can be set to either one Tag per object or multiple Tags per object. The Tag itself has only a name and description, however, it's the item that gets assigned to an object.

To get some more information about the vAPI documentation, here is what I used:

https://pubs.vmware.com/vsphere-60/index.jsp#com.vmware.dcli.cmdref.doc/com/vmware/cis/tagging/Category.html

If you get the hang of it, it's actually quite easy, and I'm looking forward to more possibilities.

See also

See also the following example workflows:

  • 12.03.1 Custom Attribute Lifecycle
  • 12.3.2 Tag Lifecycle
  • 12.3.3 assignTag2VM
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset