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 !



Comments

What's hot ?

Nutanix : Create a simple VM with Terraform

Raspberry : Boots in Emergency Mode