Advisory · Progetti · Conferenze LinkedIn GitHub Credly IT EN

Automazione e AI · Nutanix

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

Indice dell'articolo
  1. Nutanix: non solo storage
  2. Prism Central: il punto d’ingresso
  3. Il dilemma delle API: v2 vs v3
  4. La mia scelta: API v3 con un trucco
  5. Le unità di misura: PPM e altre stranezze
  6. Le sfide affrontate
  7. Conclusioni

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:

  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:

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 😛