Indice dell'articolo
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
Restituiscono dati in formato JSON piatto, facili da parsare. Il problema? Nutanix le sta gradualmente sostituendo.
API v3 – L’approccio moderno (e complesso)
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:
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:
- Aggregare metriche su qualsiasi entità (cluster, host, VM)
- Richiedere attributi specifici senza scaricare dati inutili
- Ottenere statistiche in tempo reale con una singola chiamata
Ecco un esempio di come lo usiamo per le metriche dei cluster:
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 😛
