Fehlerbehebung

Diese Seite führt von einem Symptom zu seinen üblichen Ursachen und dazu, was zu tun ist: ein Cluster, der auf dem Weg zu bereit anhält, pbx-agent, der sich nicht registriert oder nicht mehr meldet, eine Operation, die fehlschlägt, ein Zugangsdatum, das abgelehnt wird. Hilft nichts davon, schreib mir mit dem Namen des Clusters und dem fehlgeschlagenen Schritt oder der Operation.

In Arbeit: noch nicht buchbar

PaaSbox Clusters ist am 2026-10-10 im Labor Ende-zu-Ende auf echten Hetzner-Servern gelaufen Gebaut und ist noch nicht buchbar. Diese Seite beschreibt die Zustände und Meldungen von Portal und pbx-agent, wie sie gebaut sind. Die Mails, die sie nennt, sind In Arbeit: Das Labor hat keine verschickt. Die Oberfläche des Portals ist englisch, darum stehen ihre Beschriftungen und Meldungen hier auf Englisch. Sag mir, wenn es buchbar ist.

Der Cluster hält bei einem Schritt an und zeigt Failed

Die Seite des Clusters sagt Stopped at step …, mit dem Namen des Schritts und ob der Cluster gerade angelegt (provisioning) oder gelöscht (deleting) wurde, darunter die Meldung von Hetzner oder vom Portal. Das Portal löscht von sich aus nichts, du kannst dir also die Ressourcen in deinem Projekt ansehen. Retry from … eines Team-Admins setzt bei diesem Schritt wieder an, sobald die Ursache behoben ist. Jeder Schritt hat eine Zeitgrenze; ein Schritt, der sie überschreitet, schlägt mit „step … timed out after …” fehl.

Schritt	Übliche Ursache	Was zu tun ist
validate	Das Hetzner-Token des Projekts funktioniert nicht mehr, die Verbindung zum Projekt ist gesperrt, der Standort ist unbekannt, der Kanal bietet kein Release an, oder das Release hat kein Image für die Architektur des Servers	Token ersetzen (Zugangsdaten rotieren), dann erneut versuchen; bei Architektur oder Standort den Cluster löschen und mit einem anderen Servertyp oder Standort anlegen
image	Das Kopieren des Node-Images ins Projekt ist fehlgeschlagen oder hat länger als eine Stunde gedauert	Erneut versuchen. Nur der erste Cluster eines Projekts wartet auf diesen Schritt
network, firewall, primary_ip	Hetzner hat das Anlegen der Ressource abgelehnt, etwa weil das Projekt eine seiner Grenzen erreicht hat	Bei Hetzner eine höhere Grenze erfragen oder im Projekt Platz schaffen, dann erneut versuchen
dns	Der DNS-Dienst hat den Namen der API abgelehnt, oder der Cluster hat keine öffentliche IPv4	Erneut versuchen; hält er wieder an, schreib mir
server	Hetzner hat das Anlegen des Servers abgelehnt, etwa weil der Typ am Standort gerade nicht verfügbar ist oder das Projekt seine Server-Grenze erreicht hat	Später erneut versuchen, bei Hetzner eine höhere Grenze erfragen, oder den Cluster löschen und an einem anderen Standort anlegen
enrollment	pbx-agent hat sich nicht binnen 10 Minuten registriert; siehe unten	Erneut versuchen
api_healthy	k3s hat binnen 10 Minuten keine gesunde API gemeldet	Erneut versuchen; hält er wieder an, schreib mir

Ein Server, dessen Registrierungs-Token ungenutzt abgelaufen ist, wird beim erneuten Versuch durch einen neuen mit frischen User-Data ersetzt. Ein übernommener Server wird stattdessen noch einmal neu aufgesetzt.

Ein Löschen, das anhält, zeigt dieselbe Meldung mit deleting, und Retry from … setzt es fort; jeder Durchgang löscht, was er über das Label des Clusters noch findet (Einen Cluster abkoppeln oder löschen).

pbx-agent registriert sich nicht

pbx-agent registriert sich mit einem Einmal-Token, das 30 Minuten nach dem Anlegen des Servers verfällt.

• Der Server erreicht das Portal nicht. pbx-agent braucht ausgehendes HTTPS. Die Firewall des Clusters hat nur Regeln für eingehenden Verkehr; eine ausgehende Regel, die du in der Hetzner-Konsole hinzugefügt hast, kann ihn blockieren.
• Das Token wurde abgelehnt (invalid_token, token_used, token_expired, server_mismatch). pbx-agent versucht es dreimal und wartet dann untätig. Ein Server, der sich nie registriert hat, wird beim erneuten Versuch ersetzt.
• Der Node hat ein anderes Image gebootet als das seines Releases (image_mismatch). Das Portal vergleicht den Hash des gebooteten Images mit dem Release und lehnt ab. pbx-agent wartet untätig. Mit dem Image, das das Portal in dein Projekt kopiert hat, sollte das nicht passieren; schreib mir mit dem Namen des Clusters.

Vor der Registrierung gibt es keine Kubernetes-API, mit der du einen Pod starten könntest; der Weg auf den Server ist dann das Rescue-System von Hetzner (Root auf dem Server bekommen). Auf einem laufenden Node zeigt journalctl -u pbx-agent, was pbx-agent versucht hat, und pbx-agent status seinen Zustand.

pbx-agent meldet sich nicht

Die Liste der Cluster zeigt agent not reporting, wenn pbx-agent das Portal fünf Minuten lang nicht angerufen hat. Nach 24 Stunden bekommen die Admins des Teams eine Mail. Der Cluster selbst ist nicht betroffen: k3s läuft weiter und macht weiter die geplanten Snapshots.

• Der Server ist aus oder nicht erreichbar. Prüf ihn in der Hetzner-Konsole.
• pbx-agent wurde entfernt, mit pbx-agent uninstall, oder sein Dienst ist angehalten: systemctl status pbx-agent.
• pbx-agent wurde widerrufen, durch ein Abkoppeln: Er ruft nicht mehr an und lässt den Cluster, wie er ist. Das ist so gewollt.
• Die Uhr geht falsch. Das Portal lehnt Anfragen ab, deren Zeitstempel mehr als 60 Sekunden von seiner eigenen Zeit abweicht. pbx-agent übernimmt dann die Zeit des Portals aus der Antwort und versucht es noch einmal. Passiert das immer wieder, prüf die Uhr des Servers mit timedatectl.

Die Kubernetes-API antwortet nicht

• Von deinem Rechner aus: Deine Adresse liegt vielleicht nicht in den Bereichen, die Port 6443 erreichen dürfen. Settings zeigt sie, und ein Team-Admin kann deine dort von überall aus hinzufügen; das Portal liegt nicht hinter der Firewall des Clusters (Festlegen, wer die API erreicht).
• Auf dem Cluster: Während ein Upgrade den Node neu startet oder eine Wiederherstellung läuft, ist die API planmäßig weg. Sonst zeigt die Seite des Clusters, ob pbx-agent eine gesunde API meldet.
• Solange die API weg ist, nimmt pbx-agent nur eine Wiederherstellung und Diagnosen an. Andere Operationen warten im Portal, bis die API zurück ist.

Eine Kubeconfig kommt nicht an

• Der Cluster läuft nicht. Die Seite Access sagt, dass Kubeconfigs einen laufenden Cluster brauchen.
• Die API ist weg. Die Anfrage wartet im Portal; nach 5 Minuten verfällt sie. Frag neu, sobald die API zurück ist.
• „The credential was already handed out or has expired.” Das Portal übergibt die verschlüsselte Kubeconfig einmal und hält sie höchstens 5 Minuten. Frag nach einer neuen.

Eine Kubeconfig holen hat den ganzen Ablauf.

Ein neues Token oder neue Schlüssel werden abgelehnt

• Ein neues Projekt-Token: „This token does not see the servers of …”. Das Token stammt aus einem anderen Hetzner-Projekt. Leg es in dem Projekt an, in dem der Cluster liegt.
• Ein neues Token im Cluster: „This token does not see the cluster’s servers; is it for the same project?” Dieselbe Ursache.
• Neue Bucket-Schlüssel bleiben bei „Waiting for the agent to list the bucket”. pbx-agent probiert sie beim nächsten Abgleich am Bucket aus. Ist die Prüfung fehlgeschlagen, zeigt die Liste unter Bucket keys s3.verify als fehlgeschlagen, mit der Meldung des S3-Anbieters, etwa InvalidAccessKeyId, und die geltenden Schlüssel bleiben. Prüf das Paar und speichere es erneut.

Zugangsdaten rotieren hat die Schritte.

Ein Upgrade ist fehlgeschlagen

Die Seite Upgrades zeigt den fehlgeschlagenen Schritt, und die Admins des Teams bekommen eine Mail.

• Kam der Node nicht binnen 20 Minuten nach dem Neustart gesund zurück, oder kam er im neuen Image mit der falschen k3s-Version hoch, hat pbx-agent ihn in das vorige Image neu gestartet. Der Cluster fährt das Release, das er vorher fuhr. In Arbeit Diese Rückkehr ist auf einem echten Node noch nicht ausgelöst worden.
• Kam der Node im vorigen Image hoch, hat das neue nicht gebootet, und das Upgrade ist sofort fehlgeschlagen.
• Ist nur der letzte Schritt (commit) fehlgeschlagen, fährt der Node das neue Image, sein nächster Neustart würde aber das alte starten. Die Meldung des Upgrades sagt das.
• Der Snapshot von vor dem Upgrade, pbx-pre-upgrade-<release>, liegt in deinem Bucket. Stell ihn nur wieder her, wenn der Zustand des Clusters beschädigt ist; ein fehlgeschlagenes Upgrade allein braucht ihn nicht.
• Ein Upgrade, das sein Fenster verpasst, weil pbx-agent nicht erreichbar war, rückt ins nächste Fenster und verfällt nach 14 Tagen.

Einen Cluster upgraden.

Ein Snapshot fehlt

• Fällt ein geplanter Snapshot zweimal hintereinander aus, bekommen die Admins des Teams eine Mail.
• Kein Bucket eingerichtet: Die Snapshots bleiben nur auf der Platte des Servers. Backups zeigt das Ziel.
• Die Schlüssel funktionieren nicht mehr: Hält das Portal die Schlüssel, speichere neue unter Backups → Bucket keys (oben). Hältst du sie selbst, prüf dein Secret kube-system/pbx-etcd-s3.
• Die Lifecycle-Regeln des Buckets haben vielleicht Snapshots gelöscht.

Eine Wiederherstellung wurde nicht fertig

Der fehlgeschlagene Schritt der Wiederherstellung und sein Log stehen auf der Seite Operations des Clusters. Eine Wiederherstellung wird nach einem Fehler in ihrem Schritt zum Zurücksetzen nie von selbst wiederholt: pbx-agent liest den Zustand des Nodes und meldet ihn, und du entscheidest. Hältst du die Schlüssel selbst, muss pbx-agent sie aus dem Cluster lesen, bevor er k3s anhält; eine solche Wiederherstellung braucht also eine laufende API. Snapshots machen und wiederherstellen.

Ein Add-on zeigt failed

Die Seite Add-ons zeigt für jedes Add-on den Zustand, den der Cluster meldet, mit dem Grund: eine fehlende Pflicht-Option, ein Token, das Hetzner ablehnt, ein Objekt, das Kubernetes ablehnt, ein Add-on, das es braucht und das aus ist. Korrigier die Option und speichere. Ein fehlgeschlagenes Add-on behält die Objekte, die es schon hat. Add-ons auswählen.

Die PaaSbox Platform meldet failed: not switched off: …, wenn du sie ausschaltest, solange noch eine SaaSApplication oder eine Datenbank existiert: Lösch sie zuerst (Add-ons auswählen). Bleibt sie stattdessen pending, ist vielleicht ein Teil von ihr einmal fehlgeschlagen: Flux versucht so einen Teil erst nach einer Stunde wieder. Lernschritt 2 zeigt, wie du Flux bittest, es jetzt zu versuchen.

Eine Änderung von Hand ist verschwunden

Objekte, die ein Add-on verwaltet, tragen das Label pbx.io/managed=true, und pbx-agent wendet sie alle zehn Minuten neu an. Willst du eines selbst steuern, schalte das Add-on ab und installiere dein eigenes (Add-ons auswählen). Eine Regel, die du in der Hetzner-Konsole in die Firewall des Clusters eingetragen hast, ist weg, sobald die API-Bereiche auf Settings gespeichert werden (Festlegen, wer die API erreicht).

Ein Server lässt sich nicht übernehmen

Das Formular zum Anlegen zeigt neben jedem Server, der sich nicht übernehmen lässt, den Grund. Einen vorhandenen Server nutzen erklärt jede Voraussetzung. Darunter: ein CX-Server (er bootet nur mit BIOS), eingeschalteter Rebuild-Schutz, oder eine Firewall, die über einen Label-Selektor auf den Server wirkt.

Ein Cluster lässt sich nicht anlegen

Die Seite zum Anlegen nennt das Erste, was im Weg steht: kein Hetzner-Projekt verbunden, noch kein Release veröffentlicht, die Cluster-Grenze des Teams erreicht („Delete or detach one, or ask for a higher limit”), eine unbezahlte Rechnung oder ein beendetes Abo, die Bedingungen noch nicht akzeptiert, oder das Abo noch nicht gestartet In Arbeit. Cluster legen nur Team-Admins an. Einen Cluster anlegen.

Diagnose

pbx-agent kann Diagnosedaten sammeln, Versionen, den Zustand seiner Units und die letzten Zeilen der Logs von k3s und pbx-agent, aber erst, nachdem du es für genau diese eine Anfrage erlaubt hast. Secrets, Tokens oder Umgebungsdateien sind nie darin. Geplant Die Seite im Portal, auf der du diese Erlaubnis gibst, ist noch nicht gebaut; bis dahin zeigen journalctl -u k3s und journalctl -u pbx-agent auf dem Server dieselben Logs.

Root auf dem Server bekommenDie Wege auf den Server, für die Logs, die das Portal nicht zeigen kann.

FAQKurze Antworten zum Ansatz, zum Preis, zu Produktion, Agenten und dem Gehen.