Un sito che non è mai entrato in linea

Acquisito il 28-07-2026 da un CE di questo deployment. sitecli/capture-manifest.json registra quale nodo, e scripts/capture-sitecli.sh --check verifica nuovamente la superficie dei comandi su un CE attivo.

La API non può eseguire il debug di questo problema

La API di debug raggiunge il nodo attraverso il control plane di F5 Distributed Cloud, tramite il tunnel stabilito dalla registrazione. Se la registrazione è fallita non esiste alcun tunnel, quindi ogni comando di questo sito non è disponibile per questo specifico tipo di errore. Operare da Site Console se il nodo dispone ancora di un percorso di rete, e dalla console seriale in caso contrario.

1. Verificare di interrogare il tenant corretto. Questo costa un solo comando ed è il primo perché sbagliarlo fa sì che ogni passaggio successivo menta: una flotta integra nel tenant che non si sta guardando è indistinguibile da una flotta che non si è mai registrata.

   cd terraform
   terraform output -raw xc_tenant       # the tenant this deployment belongs to
   terraform output -raw xc_env_tenant   # the tenant your shell is exporting

   f5-sales-demo
   f5-sales-demo

   Valori non corrispondenti, oppure una credenziale che si ritiene valida che restituisce un semplice 401? È il sintomo di un token generato per un altro tenant, e a questo deployment è già costato una ricostruzione completa (issue 696).

2. Verificare cosa pensa il tenant. L’assenza dall’elenco dei siti è un problema diverso dalla presenza con stato differente da ONLINE.

   curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
     "$XCSH_API_URL/api/config/namespaces/system/sites" | jq -r '.items[].name'

   Se il sito esiste e riporta ONLINE, la registrazione è riuscita e si sta seguendo il workflow sbagliato.

3. Individuare la registrazione del sito e il suo stato. Un nodo può registrarsi e poi attendere l’approvazione, cosa che dall’esterno appare identica a un errore.

   curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
     "$XCSH_API_URL/api/register/namespaces/system/registrations_by_site/<site>" \
     | jq -r '.items[] | "\(.name)  \(.object.status.current_state)  \(.object.spec.gc_spec.infra.hostname)"'

   r-a97e20c8-b7e1-483d-bd76-34a64ff8bc78  ONLINE  f5-xc-ce-vm-01

   L’assenza totale di elementi significa che il nodo non si è ancora registrato — passare alla console seriale. Un elemento in uno stato diverso da ONLINE significa che si è registrato e che qualcosa è fallito successivamente, il che costituisce un’indagine diversa.

   Per esaminare l’intero namespace alla ricerca di elementi in attesa di approvazione, listregistrationsbystate accetta lo stato come corpo di una POST:

   curl -sS -X POST -H "Authorization: APIToken $XCSH_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"namespace":"system","state":"PENDING"}' \
     "$XCSH_API_URL/api/register/namespaces/system/listregistrationsbystate" | jq -r '.items[].name'

   Su una flotta integra non restituisce nulla, perché l’approvazione è automatizzata.

4. Verificare che la VM sia effettivamente in esecuzione, prima di presumere un guasto software.

   az vm list -d -g <resource-group> --query "[].{name:name,power:powerState}" -o table

   Name              Power
   ----------------  ----------
   f5-xc-ce-vm-01    VM running
   f5-xc-ce-vm-02    VM running
   f5-xc-ce-vm-03    VM running
   mcn-ce-ha-client  VM running

5. Collegarsi alla console seriale. In modalità interattiva serve un terminale reale; il collegamento stesso può essere invece automatizzato via websocket — vedere console seriale.

   az serial-console connect -g <resource-group> -n <vm-name>

   Se il collegamento viene rifiutato, verificare che la diagnostica di avvio sia abilitata sulla VM prima di concludere che il nodo è irraggiungibile; questo prerequisito e le sue modalità di errore sono trattati nella pagina console seriale.

6. Leggere ciò che mostra la console, in quest’ordine. Prima cloud-init — un nodo il cui cloud-init non è mai stato completato non ha alcuna configurazione con cui registrarsi. Poi i tentativi di registrazione stessi, quindi il DNS: se il nodo non riesce a risolvere register.ves.volterra.io, nulla a valle può funzionare.

7. Una volta che il nodo è ONLINE, verificare con health e attendersi state: PROVISIONED.

Una registrazione prende il nome da un UUID, mai dal suo sito

Le registrazioni sono denominate r-<uuid>, e non esiste alcun endpoint che accetti un nome di sito dove è previsto un nome di registrazione. GET .../registrations/<site> restituisce 404, che si legge come “questo sito non ha alcuna registrazione” mentre in realtà significa “quello non è un nome di registrazione”. La corrispondenza tra sito e registrazione si ottiene soltanto da registrations_by_site/<site>, come nel passaggio 3, oppure elencando le registrations e confrontando gc_spec.passport.cluster_name.

La stessa trappola ha fatto sembrare che una flotta integra non avesse alcuna registrazione.

Le cause più comuni

• Si sta puntando al tenant sbagliato, quindi una flotta perfettamente funzionante sembra assente. Passaggio 1.
• cloud-init non è stato completato, quindi /etc/vpm/config.yaml è assente o errato.
• Il token di registrazione è scaduto, già utilizzato, o appartiene a un altro tenant.
• Nessuna route di egress verso register.ves.volterra.io.
• Uno scostamento dell’orologio abbastanza grande da invalidare i certificati — rapido da escludere successivamente con chronyc-sources, ma non raggiungibile finché il nodo non è online. Il banner di accesso SSH riporta NTP: Synced e lo stato del resolver prima di eseguire qualsiasi comando, quando SSH è disponibile.