Ein Standort, der nie online ging

Erfasst am 28.07.2026 von einer CE dieses Deployments. sitecli/capture-manifest.json hält fest, um welchen Knoten es sich handelt, und scripts/capture-sitecli.sh --check überprüft die Befehlsoberfläche erneut gegen eine laufende CE.

Die API kann dies nicht debuggen

Die Debug-API erreicht den Knoten über die Control Plane von F5 Distributed Cloud, über den Tunnel, den die Registrierung aufbaut. Wenn die Registrierung fehlgeschlagen ist, existiert kein Tunnel, sodass jeder Befehl auf dieser Website für genau diesen Fehlerfall nicht verfügbar ist. Arbeiten Sie von der Site Console aus, wenn der Knoten noch einen Netzwerkpfad besitzt, und von der seriellen Konsole aus, wenn nicht.

1. Vergewissern Sie sich, dass Sie den richtigen Tenant abfragen. Das kostet einen Befehl und steht an erster Stelle, weil ein Fehler hier jeden späteren Schritt verfälscht: Eine gesunde Flotte in dem Tenant, den Sie nicht betrachten, ist nicht von einer Flotte zu unterscheiden, die sich nie registriert hat.

   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

   Stimmen die Werte nicht überein, oder liefert ein Credential, das Sie für gültig halten, ein nacktes 401? Das ist das Symptom eines Tokens, das für einen anderen Tenant ausgestellt wurde, und es hat dieses Deployment bereits einen vollständigen Neuaufbau gekostet (Issue 696).

2. Prüfen Sie, was der Tenant meint. In der Standortliste zu fehlen ist ein anderes Problem als vorhanden, aber nicht ONLINE zu sein.

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

   Wenn der Standort existiert und ONLINE meldet, war die Registrierung erfolgreich und Sie befinden sich im falschen Workflow.

3. Finden Sie die Registrierung des Standorts und deren Status. Ein Knoten kann sich registrieren und dann auf Genehmigung warten, was von außen identisch zu einem Fehlschlag aussieht.

   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

   Überhaupt keine Einträge bedeutet, dass sich der Knoten noch nicht registriert hat — gehen Sie zur seriellen Konsole. Ein Eintrag in einem anderen Zustand als ONLINE bedeutet, dass er sich registriert hat und danach etwas fehlgeschlagen ist, was eine andere Untersuchung erfordert.

   Um den gesamten Namespace nach allem zu durchsuchen, was auf Genehmigung wartet, nimmt listregistrationsbystate den Zustand als POST-Body entgegen:

   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'

   Bei einer gesunden Flotte liefert das nichts zurück, weil die Genehmigung automatisiert erfolgt.

4. Vergewissern Sie sich, dass die VM tatsächlich läuft, bevor Sie einen Softwarefehler annehmen.

   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. Verbinden Sie sich mit der seriellen Konsole. Interaktiv erfordert das ein echtes Terminal; die Verbindung selbst kann stattdessen über den Websocket skriptgesteuert erfolgen — siehe serielle Konsole.

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

   Wird die Verbindung verweigert, prüfen Sie, ob die Boot-Diagnose auf der VM aktiviert ist, bevor Sie schlussfolgern, dass der Knoten nicht erreichbar ist; diese Voraussetzung und ihre Fehlerbilder werden auf der Seite serielle Konsole behandelt.

6. Lesen Sie, was die Konsole zeigt, in dieser Reihenfolge. Zuerst cloud-init — ein Knoten, dessen cloud-init nie abgeschlossen wurde, hat keine Konfiguration, mit der er sich registrieren könnte. Dann die Registrierungsversuche selbst, dann DNS: Wenn der Knoten register.ves.volterra.io nicht auflösen kann, kann nichts Nachgelagertes funktionieren.

7. Sobald der Knoten ONLINE ist, prüfen Sie mit health und erwarten Sie state: PROVISIONED.

Eine Registrierung ist nach einer UUID benannt, niemals nach ihrem Standort

Registrierungen heißen r-<uuid>, und es gibt keinen Endpunkt, der einen Standortnamen dort akzeptiert, wo ein Registrierungsname erwartet wird. GET .../registrations/<site> liefert 404, was sich liest wie „dieser Standort hat keine Registrierung“ und in Wirklichkeit „das ist kein Registrierungsname“ bedeutet. Die Zuordnung von Standort zu Registrierung ergibt sich nur aus registrations_by_site/<site> wie in Schritt 3, oder indem man registrations auflistet und über gc_spec.passport.cluster_name abgleicht.

Dieselbe Falle ließ es so aussehen, als hätte eine gesunde Flotte null Registrierungen.

Die üblichen Ursachen

• Sie sind auf den falschen Tenant ausgerichtet, sodass eine intakte Flotte abwesend erscheint. Schritt 1.
• cloud-init wurde nicht abgeschlossen, sodass /etc/vpm/config.yaml fehlt oder falsch ist.
• Das Registrierungstoken ist abgelaufen, bereits verbraucht oder stammt von einem anderen Tenant.
• Keine ausgehende Route zu register.ves.volterra.io.
• Zeitabweichung, die groß genug ist, um Zertifikate ungültig zu machen — später schnell auszuschließen mit chronyc-sources, aber nicht erreichbar, solange der Knoten nicht online ist. Das Login-Banner von SSH meldet NTP: Synced und den Status des Resolvers, bevor Sie irgendetwas ausführen, sofern SSH verfügbar ist.