Einen Cluster anlegen

Ein Cluster entsteht aus einem Formular im Portal. Diese Seite geht das Formular der Reihe nach durch und zählt dann auf, was das Portal in deinem Hetzner-Projekt anlegt, wann der Cluster als bereit gilt und was zu tun ist, wenn ein Schritt fehlschlägt.

In Arbeit: noch nicht buchbar

Gebaut im Labor: Am 2026-10-10 hat der Provisioner Cluster auf echten Hetzner-Servern angelegt, durch jeden Schritt unten. Dieser Lauf startete das Anlegen über einen Verwaltungsbefehl; das Formular selbst ist In Arbeit. Die Oberfläche des Portals ist englisch, darum stehen ihre Beschriftungen hier auf Englisch. Sag mir, wenn es buchbar ist.

Vor dem Formular

Einen Cluster anlegen kann nur ein Team-Admin. PaaSbox Clusters → New cluster zeigt das Formular, wenn nichts im Weg steht, und nennt sonst das Erste, was im Weg steht, in dieser Reihenfolge:

1. Ein Hetzner-Projekt, verbunden (Hetzner-Projekt verbinden).
2. Ein Release auf dem Kanal stable. Bis dahin gibt es für dich nichts zu tun.
3. Platz im Limit des Teams von 10 Clustern gleichzeitig (mehr auf Anfrage). Gelöschte und abgekoppelte Cluster zählen nicht. Lösche oder koppel einen ab, oder wähle Ask for a higher limit.
4. Keine offene Rechnung: Kläre sie zuerst unter Billing.
5. Die Bedingungen, einmal für das Team angenommen.
6. Das Abo In Arbeit: Der erste Cluster des Teams startet es im Checkout von Paddle; weitere Cluster kommen dazu (Kosten und Abrechnung).

Das Formular

Cluster

Feld	Was es bewirkt
Name	Der Name des Clusters im Portal. Du tippst ihn erneut ein, um eine Wiederherstellung, ein Abkoppeln oder ein Löschen zu bestätigen.
DNS label	Der erste Teil des Namens der API, <label>.<team>.k3s. gefolgt von der Zone von PaaSbox. Kleinbuchstaben, Ziffern und Bindestriche, höchstens 32, eindeutig in deinem Team; leer wird es aus dem Namen gebildet. Es lässt sich später nicht ändern. Der Server heißt <label>-cp-1.
Hetzner project	Das Projekt, in dem der Cluster entsteht.
Server	A new server oder A server I already have (Einen vorhandenen Server nutzen).
PaaSbox Platform	No platform oder ein Profil: Der Cluster startet dann mit eingeschaltetem Flux und eingeschalteter PaaSbox Platform. Erscheint, wenn das Release die Plattform enthält. In Arbeit
ACME e-mail	Mit einem Profil: die Adresse, unter der Let’s Encrypt das Konto anlegt und an die es Warnungen vor dem Ablauf schickt. Mit deiner Adresse vorausgefüllt.
Location	Die Standorte deines Projekts, gelesen über die Hetzner-API.
Server type	Die Typen, die das Portal dort nutzen kann, mit vCPU, Speicher, Platte und dem monatlichen Listenpreis von Hetzner.
Release channel	stable oder early, das ein neues Release zuerst bekommt (Releases und Kanäle).
Topology	Single node.

Servertypen. Angeboten werden nur die Linien CPX, CCX und CAX: Das Node-Image bootet nur mit UEFI, und die CX-Linie bootet nur mit BIOS; das habe ich gemessen. Ein Typ steht in der Liste, wenn Hetzner ihn am Standort verkauft und das aktuelle Release ein Image für seine Architektur hat: CPX und CCX sind amd64, CAX ist arm64 In Arbeit. Der Preis ist der Listenpreis von Hetzner ohne Umsatzsteuer, den Hetzner mit dir abrechnet.

Die Plattform. Das Formular bietet die Profile an, die keine Option außer dem Profil brauchen, dazu With observability (metrics, logs, traces, Grafana); ein Profil, das mehr braucht, wählst du später auf dem Reiter Add-ons, und der Hilfetext des Felds nennt es. Das Formular bietet minimal und saas-http01 an; saas braucht ein DNS-Token und eine Default domain, nach denen nur der Reiter Add-ons fragt (Add-ons auswählen). Mit einem Profil braucht das Formular die ACME e-mail. Die Servertypen folgen der Wahl: Für saas-http01 mit Observability sagt das Formular ”… needs a server with 8 GB or more: cpx32 or larger”, wählt diesen Typ vor und lehnt einen kleineren ab. Im Labor am 2026-10-11 startete ein so angelegter cpx22 mit saas-http01 mit eingeschaltetem Flux und eingeschalteter Plattform.

Wartungsfenster (Maintenance window)

Days, From, To und Time zone, etwa Europe/Berlin. Voreingestellt sind Samstag und Sonntag, 02:00 bis 05:00 Uhr, Europe/Berlin. Ein Ende vor dem Start läuft über Mitternacht. Upgrades, die du für das Fenster einplanst, Patch-Releases und Neustarts von k3s passieren nur darin (Einen Cluster upgraden). In Arbeit Dass sie auf das Fenster warten, ist auf einem echten Cluster noch nicht gelaufen.

Snapshots

Who holds the bucket’s keys, der S3 endpoint, Bucket, Folder und Region, Schedule (cron, UTC) (voreingestellt 0 */6 * * *), Snapshots to keep (voreingestellt 28) und, wenn das Portal sie hält, Access key und Secret key. Gib Endpunkt und Bucket an, oder keins von beiden. Ohne Bucket bleiben die Snapshots auf der Platte des Servers und gehen mit ihm verloren. Backups einrichten erklärt jedes Feld, wer die Schlüssel hält und wie du den Bucket später hinzufügst.

Netz und Zugangsdaten (Network and credentials)

Feld	Was es bewirkt
Who may reach the Kubernetes API (port 6443)	Adressbereiche, einer pro Zeile. Voreingestellt ist jeder, 0.0.0.0/0 und ::/0; trag die Bereiche ein, von denen aus du arbeitest. Du kannst sie später ändern (Festlegen, wer die API erreicht).
Hetzner token inside the cluster	Der Cloud Controller und der Volume-Treiber brauchen ein Token desselben Projekts. A separate token (recommended) lässt sich allein widerrufen, und ein Pod, der es liest, hat nicht das Token, mit dem das Portal Server anlegt; füge es in Separate token ein. A copy of the project’s token ist die Alternative.

Wähle Create cluster. Das Formular prüft Standort, Typ und ein eigenes Token zuerst bei Hetzner.

Was das Portal in deinem Projekt anlegt

Die Seite des Clusters zeigt jeden Schritt, den das Portal abarbeitet:

1. validate: das Token, der Standort, der Servertyp, das Release.
2. image: Das Node-Image wird in dein Projekt kopiert, einmal pro Projekt und Architektur; es bleibt für spätere Cluster dort.
3. network: 10.0.0.0/16 mit dem Subnetz 10.0.1.0/24.
4. firewall: Port 6443 von deinen Bereichen, die Ports 80 und 443 von allen, ICMP, sonst nichts. Port 22 (SSH) bleibt zu.
5. primary_ip und dns: eine eigene IPv4-Adresse des Clusters, und der Name der API, der auf sie zeigt.
6. server: aus dem Node-Image, im Netz, hinter der Firewall.
7. enrollment: Die User-Data enthalten nur, woher pbx-agent kommt, und seine Prüfsumme, die Adresse des Portals, die ID des Clusters, den Namen des Nodes und ein Einmal-Token zur Registrierung, das nach 30 Minuten abläuft. Das Portal prüft, dass der Server genau das Image aus dem Release des Clusters gebootet hat.
8. api_healthy, dann ready: pbx-agent startet k3s und meldet eine gesunde Kubernetes-API. Ab dann wird abgerechnet.

Jede Ressource trägt die Labels pbx-cluster=<die ID des Clusters> und pbx-managed=true. Im Labor war der Cluster auf einem cpx22 nach 2 Minuten 46 Sekunden bereit, 69 davon für das Kopieren des Images; von außen antworteten nur 6443, 80, 443 und ICMP.

Wenn ein Schritt fehlschlägt

Die Overview des Clusters zeigt Stopped at step mit dem Namen des Schritts und dem Fehler. Das Portal löscht nichts, du kannst dir also dein Projekt ansehen. Behebe die Ursache, etwa ein Token, das Hetzner ablehnt, oder ein Projekt an seinem Hetzner-Limit, und wähle Retry from mit dem Schritt. Ein Server, dessen Registrierungs-Token ungenutzt abgelaufen ist, wird mit frischen User-Data ersetzt. Fehlerbehebung nennt die üblichen Ursachen.

Backups einrichtenDie Snapshots auf deinen Bucket richten und wählen, wer seine Schlüssel hält.

Eine Kubeconfig holenDen neuen Cluster mit kubectl erreichen.