Nutanix : Managing Categories through API (Part 1)

Background

Managing Categories (tags), within a Nutanix environment can be cumbersome, especially if you have big amount of VMs or if you want to automate the process and why not, react on triggers. Hopefully, Nutanix is giving you the power.I just finished couple of functions and added them to my Nutanix Php Framework !

Let's code!

First, this is important to mention that categories are only known in a Prism Central environment. Do not try to apply these API calls to Prism Element, it won't work. All functions in the framework starts with nxBlablabla(); Those related to Prism Central starts with nxpcBlablabla();

1. List all categories

<?php

include_once "nxFramework.php";

include_once "nxCredentialsPC.php";

// =========================================

// Main entry point

// =========================================

$cat=nxpcGetCategories($clusterConnect);

for($i=0;$i<count($cat);$i++)

{

print("Category : ".$cat[$i]->name."\n");

}

?>

It will give the following result : 

$ php -f nxCategories.php

Category : AppTier

Category : AppType

Category : Environment

Category : TemplateType

Category : Quarantine

Category : VirtualNetworkType

Category : CalmApplication

Category : CalmDeployment

Category : CalmService

Category : CalmPackage

Category : OSType

Category : AppFamily

Category : Status

Category : OS

Category : AnalyticsExclusions

Category : ADGroup

Category : BusinessUnit

Category : Fred

Now, if we want to see the possible values of the "Fred" category : 

<?php

include_once "nxFramework.php";

include_once "nxCredentialsPC.php";

// =========================================

// Main entry point

// =========================================

$category="Fred";

$values=nxpcGetCategoryValues($clusterConnect,$category);

print("Possible value(s) for ".$category."\n\n");

for($i=0;$i<count($values);$i++)

{

print("Value  : ".$values[$i]->value."\n");

}

?>

Will produce this output : 

$ php -f nxCategories.php

Possible value(s) for Fred

Value  : One

Value  : Two

Value  : Three

Value  : Four

2. Get categories from VM

<?php

include_once "nxFramework.php";

include_once "nxCredentialsPC.php";

// =========================================

// Main entry point

// =========================================

$vmName="MyVM";

        $clusterName="MyCluster";

$vmUuid=nxpcGetVMUuid($clusterConnect,$vmName,$clusterName);

$cat=nxpcGetVMCategories($clusterConnect,$vmUuid)->categories_mapping;

if($cat)

{

print("\nCategory applied to ".$vmName." is/are : \n\n");

// Loop thru found catagories and values

foreach($cat as $key => $value)

{

for($i=0;$i<count($value);$i++)

print($key." :: ".$value[$i]."\n");

}

}

else print("No category applied to ".$vmName."\n\n");

?>

Here is the result : 

$ php -f nxCategories.php

Category applied to MyVM is/are :

AppFamily :: Backup

OSType :: Linux

OS :: LinuxCentOS

Fred :: Two

Fred :: Three

3. Apply categories to a VM

This one is more tricky since we need to manage VM versioning. Indeed, each time a VM is modified, a version number is incremented. We need to maintain that increment to avoid collision when modifying VMs properties. This is why I have created a separate function which gets that version number. We need to apply a change AND pass the current version number to the VM we are applying categories. All is managed into the nxpcApplyCategory(); function.

Let's say that we want to apply the following categories/values to my test VM : 

OS -> Win10

Fred -> One

Fred -> Four

I need to create a specific array which contains those details and pass it to the function and I need to specify the cluster on which we are modifying the VM. Indeed, we can have the same VM name in different cluster, so we need to be sure we are modifying the right VM.

<?php

include_once "nxFramework.php";

include_once "nxCredentialsPC.php";

// =========================================

// Main entry point

// =========================================

// Set Category

// Note if a vategory requires two values, they can be entered between coma

$categories=array(

"Fred" => "One,Four",

"OS" => "Win10"

);

$vmName="MyVM";

$clusterName="MyCluster";

$vmUuid=nxpcGetVMUuid($clusterConnect,$vmName,$clusterName);

// Get the VM Specification version

$specV=nxpcGetSpecV($clusterConnect,$vmUuid);

$return=nxpcApplyCategory($clusterConnect,$categories,$vmName,$clusterName,$specV);

if(!$return) print("Categories have been applied.\n");

else print("Something goes wrong, please check the logs.\n");

?>

It will produce the following output :

$ php -f nxCategories.php

Categories have been applied.

And the Prism Central UI shows the following : 

4. Remove all categories from a VM

<?php

include_once "nxFramework.php";

include_once "nxCredentialsPC.php";

// =========================================

// Main entry point

// =========================================

        $vmName="MyVM";

$clusterName="MyCluster";

$vmUuid=nxpcGetVMUuid($clusterConnect,$vmName,$clusterName);

// Get the VM Specification version

$specV=nxpcGetSpecV($clusterConnect,$vmUuid);

$return=nxpcFlushCategories($clusterConnect,$vmName,$clusterName,$specV);

if(!$return) print("Categories have been applied.\n");

else print("Something goes wrong, please check the logs.\n");

?>

It will produce the following output - nothing fancy :

$ php -f nxCategories.php

Categories have been applied.

But more interesting, the UI shows no more categories for that VM :

With this, you can start to play. My use case here was to set a couple a categories to a very large amount of VMs (above 1000). Some specific, some generic and some common to the entire cluster. With the above functions, you can easily create a loop with all the requirements across all VMs you are managing.

Here are the new functions integrated into my Php Framework : 

nxpcApplyCategory($clusterConnect,$categories,$vmName,$clusterName,$specV)

nxpcFlushCategories($clusterConnect,$vmName,$clusterName,$specV)

nxpcGetCategories($clusterConnect)

nxpcGetCategoryValues($clusterConnect,$categoryName)

nxpcGetClusterUuid($clusterConnect,$clusterName)

nxpcGetSpecV($clusterConnect,$vmUuid)

nxpcGetVMCategories($clusterConnect,$vmUuid)

nxpcGetVMUuid($clusterConnect,$vmName)

This is the power of APIs.

Thanks to my fellow Nutanix NTC, Bilel Kammoun from https://vinception.fr/ for the guidance ! 

More info on Nutanix.dev here

As always : hope this helps !