Working with the vCenter API (to change a VM's HA settings)

This recipe will showcase how to derive a function for a more complicated feature. We will be configuring the HA setting for a single VM. Here, we will primarily be focusing on how to work with the vCenter API.

Getting ready

For this recipe, we will need a vCenter cluster that is configured for VMware High Availability (HA), as well as a VM which has an HA restart priority that we can change.

To do this, you should have an understanding of the introduction to Chapter 6, Advanced Programming, as well as the recipes Working with the API and JavaScript complex variables in the same chapter.

How to do it...

We will use the API and find out how to set VM's HA restart priority. This recipe requires you to take a close look at each of the objects that we will visit and read its properties and external documentation.

It is best to follow this step by step using the API browser:

  1. Create a new workflow and create the following variables:

    Name

    Type

    Section

    Use

    priority

    String

    IN

    This variable denotes the HA priority. It can have the values clusterRestartPriority, disabled, high, medium, and low. It can also use the presentation property Predefined answers.

    VM

    VC:VirtualMachine

    IN

    This is the VM we will be working with.

    cluster

    VC:ClusterComputeResource

    IN

    This is the cluster the VM is in.

    vcTask

    VC:Task

    Attribute

    This variable will carry the reconfiguration task from the script to the wait task.

    progress

    Boolean

    Attribute

    The default value is false. It shows the progress of a task.

    pollRate

    Number

    Attribute

    The default value is 5 (seconds). It shows how often it should be checked for task completion.

  2. Add a scriptable task to the schema and edit it.
  3. Use the API browser to search for the word restart.
  4. Check the results. You should find VcClusterDasVmConfigInfo.restartPriority and VcClusterDasVmSettings.restartPriority. Click on the first one and open it in the API browser.
  5. Then, click on External documentation. Your web browser will open and bring you to the vCenter API documentation. Take a look; the things we need are marked as Deprecated, meaning they are of no use to us. They still work, but it's not a good idea to use functions that are about to be removed:

    How to do it...

  6. Repeat Step 5 with the second choice. You will find that there are no deprecated functions, meaning we can use them. Let's start adding some lines to our script. First, we need the constructor. We will copy and paste VcClusterDasVmSettings, which results in the following:
          var myVcClusterDasVmSettings = new VcClusterDasVmSettings();
  7. Then, we need to add the restartPriority attribute to it. Clicking on the restartPriority attribute tells us that it is of the type VcClusterDasVmSettingsRestartPriority, so take a look at that. We will use the value directly, as shown in the following line:
          myVcClusterDasVmSettings.restartPriority=
      VcClusterDasVmSettingsRestartPriority.fromString(priority);
  8. Next, we need to think about changing the configuration. The external documentation also tells us that VcClusterDasVmSettings is a property of VcClusterDasVmConfigInfo. Taking a look at this object, we find that the attribute .key is a VM object, and that the .dasSettings attribute will take our myVcClusterDasVmSettings.
  9. Now we will add the constructor of VcClusterDasVmConfigInfo to our script, as well as the rest of the lines:
          var myVcClusterDasVmConfigInfo = new VcClusterDasVmConfigInfo(); 
      myVcClusterDasVmConfigInfo.key=VM; 
      myVcClusterDasVmConfigInfo.dasSettings=myVcClusterDasVmSettings;
  10. Again, we need to go higher in the API tree. Looking at the parent of VcClusterDasVmConfigInfo we find VcClusterDasVmConfigSpec. This has a .info attribute, which will take a value of VcClusterDasVmConfigInfo. However, a closer look at the external documentation shows us that we need to define the .operation attribute. We know this because all the other attributes come with a * saying that they do not need to be present, meaning the operation has to be there. So, we will add that as well:
          var myVcClusterDasVmConfigSpec = new VcClusterDasVmConfigSpec(); 
      myVcClusterDasVmConfigSpec.operation = VcArrayUpdateOperation.add; 
      myVcClusterDasVmConfigSpec.info = myVcClusterDasVmConfigInfo;
  11. We will still need to go higher. The parent of myVcClusterDasVmConfigSpec is vcClusterConfigSpecEX. It has a .dasVmConfigSpec attribute, which will take a value of VcClusterDasVmConfigSpec, but further inspection reveals that it needs an array of VcClusterDasVmConfigSpec. So let's do that:
          var myVcClusterDasVmConfigSpecArray = new Array() ; 
      myVcClusterDasVmConfigSpecArray.push( myVcClusterDasVmConfigSpec ); 
      var myVcClusterConfigSpecEx = new VcClusterConfigSpecEx() ; 
      myVcClusterConfigSpecEx.dasVmConfigSpec = 
      myVcClusterDasVmConfigSpecArray;
  12. The next part isn't documented, but results from trial and error. We need to define the .dasConfig attribute. Try the finished script and comment the next two lines out, and you will get an error message telling you that you need VcClusterDasConfigInfo:
          var myVcClusterDasConfigInfo = new VcClusterDasConfigInfo() ; 
      myVcClusterConfigSpecEx.dasConfig = myVcClusterDasConfigInfo;
  13. We are almost there; one more step and we are done. Check out the VcClusterConfigSpecEx object, which tells us that it can be used with a cluster, so let's look the other way around. Search for Cluster and take a closer look at ClusterComputeResource. It has a method called reconfigureCluster_Task(), which will take our VcClusterConfigSpecEx. So, let's use the following:
          vcTask=cluster.reconfigureComputeResource_Task
      ( myVcClusterConfigSpecEx, true );
  14. The return value of this attribute is a vCenter task. We will define the Boolean of the method as true, as only the changes to the cluster are needed. If we set it to false, it will apply all the changes defined in VcClusterDasConfigInfo.
  15. Our little script is finished and looks like the following:
          var myVcClusterDasVmSettings = new VcClusterDasVmSettings(); 
      myVcClusterDasVmSettings.restartPriority=
      VcClusterDasVmSettingsRestartPriority.fromString(priority); 
 
      var myVcClusterDasVmConfigInfo = new VcClusterDasVmConfigInfo(); 
      myVcClusterDasVmConfigInfo.key=VM; 
      myVcClusterDasVmConfigInfo.dasSettings=myVcClusterDasVmSettings; 
 
      var myVcClusterDasVmConfigSpec = new VcClusterDasVmConfigSpec() ; 
      myVcClusterDasVmConfigSpec.operation = VcArrayUpdateOperation.add; 
      myVcClusterDasVmConfigSpec.info = myVcClusterDasVmConfigInfo; 
 
      var myVcClusterDasVmConfigSpecArray = new Array() ; 
      myVcClusterDasVmConfigSpecArray.push( myVcClusterDasVmConfigSpec ); 
      var myVcClusterConfigSpecEx = new VcClusterConfigSpecEx() ; 
      myVcClusterConfigSpecEx.dasVmConfigSpec =
      myVcClusterDasVmConfigSpecArray; 
      var myVcClusterDasConfigInfo = new VcClusterDasConfigInfo() ; 
      myVcClusterConfigSpecEx.dasConfig = myVcClusterDasConfigInfo; 
 
      vcTask=cluster.reconfigureComputeResource_Task
      ( myVcClusterConfigSpecEx, true );
  16. As the final step, we will add the action vim3WaitTaskEnd to the workflow:

    How to do it...

How it works...

This recipe has probably caused you a bit of a headache, but it is also extremely important to understand how to create workflows that use properties that are not implemented in the existing library. Working through the API, finding the items, and putting them together is a vital part of advanced programming skills in Orchestrator.

The method shown here is a difficult one, but, if you already know to which object a setting belongs, you can also move from the top down. In this case, you will have to drill down from ClusterComputeResource. If you like, give it a try. Have a go at the DRS setting for a VM. It basically follows the same route.

There is another way to generate this kind of script. Check out the Onyx project at labs.vmware.com/flings/onyx.

Onyx integrates itself between vSphere Client and vCenter Server and translates the actions in a script. However, it is always better to understand what actually happens and how to search and find it.

There's more...

To make the workflow work better, we will apply a few presentation properties to it. We looked at these in the Workflow presentations and Linking actions in presentations recipes in Chapter 5, Visual Programming:

  1. Add the Predefined answers property to the presentation of the in-parameter priority. The correct answers are found in the VcClusterDasVmSettingsRestartPriority object. This will only show the correct values that should be entered.
  2. Add the Predefined list of elements property to the presentation of the in-parameter VM.
  3. Click on the purple puzzle piece (it helps us to create an action call), and in the pop-up, search for Cluster; select the only return action called getAllVMsOfCluster and assign it to the input of the cluster:

    There's more...

See also

Refer to the example workflows, 12.02.1 Change VM HA settings and 12.02.2 Change VM DRS settings.

..................Content has been hidden....................

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