How we collect data from Nutanix: a journey through API v2 and v3

When I started working on the Nutanix integration for a new project I’m developing, I had no idea how many surprises their APIs had in store for me. Here’s what I learned.

Nutanix: not just storage

For those who aren’t familiar with it, Nutanix is one of the most widely used hyperconverged infrastructure (HCI) platforms in the world. In practice, it combines compute, storage and virtualization in a single solution. When our customers asked us to monitor their Nutanix clusters as well, I knew it was going to be an interesting adventure.

Prism Central: the entry point

The first thing to understand is that Nutanix has two management interfaces:

Prism Element: manages a single cluster
Prism Central: manages multiple clusters from a single place

For an enterprise monitoring solution, Prism Central is the only real choice. From a single endpoint you can collect data from all the registered clusters, without having to configure multiple connections.

The API dilemma: v2 vs v3

And this is where the fun begins. Nutanix offers two versions of its REST APIs:

API v2 – Old but reliable

The v2 APIs were Nutanix’s workhorse for years. They’re simple, straightforward and… on their way to deprecation. They use endpoints like:

GET /api/nutanix/v2.0/clusters
GET /api/nutanix/v2.0/vms
GET /api/nutanix/v2.0/hosts

They return data in flat JSON format, which is easy to parse. The catch? Nutanix is gradually replacing them.

API v3 – The modern (and complex) approach

The v3 APIs represent the future. They use an approach called “intent-based”, where you don’t simply ask “give me the VMs”, but send a POST request with filter criteria:

POST /api/nutanix/v3/vms/list
{
  "kind": "vm",
  "length": 500,
  "filter": "power_state==on"
}

The good part is that you can paginate, filter and request only the fields you need. The bad part? The structure of the responses is much more complex, with three levels of nesting: metadata, spec and status.

My choice: API v3 with a trick

After various experiments, we decided to use the v3 APIs for the main data collection. But there’s a secret you won’t easily find in the documentation: the Groups API.

Groups API: the hidden superpower

The /api/nutanix/v3/groups endpoint is probably the most powerful and least documented feature of Prism Central. It lets you:

Aggregate metrics for any entity (cluster, host, VM)
Request specific attributes without downloading useless data
Get real-time statistics with a single call

Here’s an example of how we use it for cluster metrics:

POST /api/nutanix/v3/groups
{
  "entity_type": "cluster",
  "group_member_count": 500,
  "group_member_attributes": [
    { "attribute": "cluster_name" },
    { "attribute": "storage.capacity_bytes" },
    { "attribute": "storage.usage_bytes" },
    { "attribute": "hypervisor_cpu_usage_ppm" },
    { "attribute": "hypervisor_memory_usage_ppm" },
    { "attribute": "controller_num_iops" }
  ]
}

With a single call we get storage, CPU, memory and IOPS for all the clusters. Magic.

Units of measurement: PPM and other oddities

One thing that cost me a few hours: Nutanix expresses many metrics in PPM (Parts Per Million), not as a percentage.

So when you see hypervisor_cpu_usage_ppm: 450000, it doesn’t mean the CPU is at 450000%. You need to divide by 10,000 to get 45%.

The same goes for I/O latency, which is expressed in microseconds (controller_avg_io_latency_usecs): divide by 1000 to get milliseconds.

Every 60 seconds I collect:

Cluster list with AOS version and number of nodes
Hosts with CPU, memory, hypervisor
VMs with state, vCPU, RAM, disk
Storage containers with capacity and usage
Networks (subnets) with VLAN and IP configuration
Performance metrics (IOPS, latency, CPU%, memory%)

The challenges we faced

1. Pagination

With hundreds of VMs, pagination is essential. The v3 APIs support offset and length, but watch out: the default for length is 20, not unlimited!

2. Timeouts

Requests to the Groups API can be slow on heavily loaded clusters. We had to implement generous timeouts and retries with exponential backoff.

3. SSL certificates

Many production Prism Central instances use self-signed certificates. My client supports disabling SSL verification (only in controlled environments, of course).

4. Multi-cluster

A single Prism Central can manage dozens of clusters. My architecture has to correctly map each entity to the cluster it belongs to.

Conclusions

Integrating Nutanix wasn’t trivial, but the result is worth the effort. Today I can monitor Nutanix clusters with my own custom solution.

If you’re working on a similar integration, my advice is: start with the v3 APIs and get familiar with the Groups API. It’s the key to getting rich data without overloading the system.

And remember: PPM divided by 10,000 equals percentage. I’ve had it tattooed on my keyboard 😛