Come raccogliamo dati da Nutanix: un viaggio tra API v2 e v3

*Quando ho iniziato a lavorare all’integrazione con Nutanix per un mio nuovo progetto in sviluppo, non immaginavo quante sorprese mi avrebbero riservato le loro API. Ecco cosa ho imparato.*

## Nutanix: non solo storage

Per chi non lo conoscesse, Nutanix è una delle piattaforme di infrastruttura iperconvergente (HCI) più diffuse al mondo. In pratica, combina computing, storage e virtualizzazione in un’unica soluzione. Quando i nostri clienti ci hanno chiesto di monitorare anche i loro cluster Nutanix, sapevo che sarebbe stata un’avventura interessante.

## Prism Central: il punto d’ingresso

La prima cosa da capire è che Nutanix ha due interfacce di gestione:

– **Prism Element**: gestisce il singolo cluster

– **Prism Central**: gestisce più cluster da un unico punto

Per una soluzione di monitoraggio enterprise, Prism Central è la scelta obbligata. Da un solo endpoint è possibile raccogliere dati di tutti i cluster registrati, senza dover configurare connessioni multiple.

## Il dilemma delle API: v2 vs v3

Ed ecco dove inizia il divertimento. Nutanix offre due versioni delle sue API REST:

### API v2 – Il vecchio ma affidabile

Le API v2 sono state il cavallo di battaglia di Nutanix per anni. Sono semplici, immediate e… in via di deprecazione. Usano endpoint come:

GET /api/nutanix/v2.0/clusters

GET /api/nutanix/v2.0/vms

GET /api/nutanix/v2.0/hosts

Le API v3 rappresentano il futuro. Usano un approccio chiamato “intent-based”, dove non chiedi semplicemente “dammi le VM”, ma invii una richiesta POST con criteri di filtro:

json

POST /api/nutanix/v3/vms/list

{

"kind": "vm",

"length": 500,

"filter": "power_state==on"

}

Il bello è che puoi paginare, filtrare e richiedere solo i campi che ti servono. Il brutto? La struttura delle risposte è molto più complessa, con tre livelli di annidamento: `metadata`, `spec` e `status`.

## La mia scelta: API v3 con un trucco

Dopo vari esperimenti, abbiamo deciso di usare le API v3 per la raccolta dati principale. Ma c’è un segreto che non trovate facilmente nella documentazione: la **Groups API**.

### Groups API: il superpotere nascosto

L’endpoint `/api/nutanix/v3/groups` è probabilmente la feature più potente e meno documentata di Prism Central. Permette di:

1. **Aggregare metriche** su qualsiasi entità (cluster, host, VM)

2. **Richiedere attributi specifici** senza scaricare dati inutili

3. **Ottenere statistiche in tempo reale** con una singola chiamata

Ecco un esempio di come lo usiamo per le metriche dei cluster:

json

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" }

]

}

Con una sola chiamata otteniamo storage, CPU, memoria e IOPS di tutti i cluster. Magico.

## Le unità di misura: PPM e altre stranezze

Un aspetto che mi ha fatto perdere qualche ora: Nutanix esprime molte metriche in **PPM** (Parts Per Million), non in percentuale.

Quindi quando vedi `hypervisor_cpu_usage_ppm: 450000`, non significa che la CPU è al 450000%. Devi dividere per 10.000 per ottenere il 45%.

Stesso discorso per la latenza I/O, espressa in microsecondi (`controller_avg_io_latency_usecs`): dividi per 1000 per avere i millisecondi.

Ogni 60 secondi raccolgo:

– Lista cluster con versione AOS e numero nodi

– Host con CPU, memoria, hypervisor

– VM con stato, vCPU, RAM, disco

– Storage container con capacità e utilizzo

– Network (subnet) con VLAN e configurazione IP

– Metriche di performance (IOPS, latenza, CPU%, memoria%)

## Le sfide affrontate

### 1. Paginazione

Con centinaia di VM, la paginazione è essenziale. Le API v3 supportano `offset` e `length`, ma attenzione: il default di `length` è 20, non infinito!

### 2. Timeout

Le richieste alla Groups API possono essere lente su cluster molto carichi. Abbiamo dovuto implementare timeout generosi e retry con backoff esponenziale.

### 3. Certificati SSL

Molti Prism Central in produzione usano certificati self-signed. Il mio client supporta la disabilitazione della verifica SSL (solo in ambienti controllati, ovviamente).

### 4. Multi-cluster

Un singolo Prism Central può gestire decine di cluster. La mia architettura deve correlare correttamente ogni entità al suo cluster di appartenenza.

## Conclusioni

Integrare Nutanix non è stato banale, ma il risultato vale lo sforzo. Oggi posso monitorare cluster Nutanix con una mia soluzione personalizzata.

Se state lavorando a un’integrazione simile, il mio consiglio è: partite dalle API v3 e familiarizzate con la Groups API. È la chiave per ottenere dati ricchi senza sovraccaricare il sistema.

E ricordatevi: PPM diviso 10.000 uguale percentuale. Me lo sono tatuato sulla tastiera 😛