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

- Link: https://www.silviobalduzzi.com/2026/01/come-raccogliamo-dati-da-nutanix-un-viaggio-tra-api-v2-e-v3/
- Published: 2026-01-06T17:26:55+01:00
- Author: balduz84

_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:

    ```wp-block-code
    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:

    ```has-small-font-size
    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:

    ```has-small-font-size
    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
😛
