Create a cluster

A cluster is created from one form in the portal. This page goes through the form in order, then lists what the portal creates in your Hetzner project, when the cluster counts as ready, and what to do when a step fails.

In progress: not bookable yet

Built in a lab: on 2026-10-10 the provisioner created clusters on real Hetzner servers, through every step below. That run started the create with a management command; the form itself is In progress. Tell me when it opens.

Before the form

Only a team admin can create a cluster. PaaSbox Clusters → New cluster shows the form when nothing stands in the way, and otherwise names the first thing that does, in this order:

1. A Hetzner project, connected (Connect a Hetzner project).
2. A release on the stable channel. Until then there is nothing for you to do.
3. Room in the team’s limit of 10 clusters at once (more on request). Deleted and detached clusters do not count. Delete or detach one, or choose Ask for a higher limit.
4. No unpaid invoice: sort it out under Billing first.
5. The terms, accepted once for the team.
6. The subscription In progress: the team’s first cluster starts it in Paddle’s checkout; later clusters are added to it (Costs and billing).

The form

Cluster

Field	What it does
Name	The cluster’s name in the portal. You type it again to confirm a restore, a detach or a delete.
DNS label	The first part of the API’s name, <label>.<team>.k3s. followed by PaaSbox’s zone. Lower-case letters, digits and hyphens, at most 32, unique in your team; empty, it is made from the name. It cannot change later. The server is named <label>-cp-1.
Hetzner project	The project the cluster is created in.
Server	A new server, or A server I already have (Use a server you already have).
PaaSbox Platform	No platform, or a profile: the cluster then starts with Flux and the PaaSbox Platform switched on. Shown when the release carries the platform. In progress
ACME e-mail	With a profile: the address Let’s Encrypt registers the account under and sends expiry warnings to. Filled in with your address.
Location	The locations of your project, read from the Hetzner API.
Server type	The types the portal can use there, with vCPU, memory, disk and Hetzner’s monthly list price.
Release channel	stable, or early, which gets a new release first (Releases and channels).
Topology	Single node.

Server types. Only the CPX, CCX and CAX lines are offered: the node image boots with UEFI only, and the CX line boots with BIOS only; I measured that. A type is listed when Hetzner sells it in the location and the current release has an image for its architecture: CPX and CCX are amd64, CAX is arm64 In progress. The price is Hetzner’s list price excluding VAT, which Hetzner bills to you.

The platform. The form offers the profiles that need no option beyond the profile and With observability (metrics, logs, traces, Grafana); a profile that needs more is chosen later on the Add-ons tab, and the field’s help text names it. The form offers minimal and saas-http01; saas needs a DNS token and a default domain, which only the Add-ons tab asks for (Choose add-ons). With a profile, the form needs the ACME e-mail. The server types follow the choice: for saas-http01 with observability the form says ”… needs a server with 8 GB or more: cpx32 or larger”, picks that type and refuses a smaller one. In the lab on 2026-10-11 a cpx22 created this way with saas-http01 started with Flux and the platform switched on.

Maintenance window

Days, From, To and Time zone, such as Europe/Berlin. The default is Saturday and Sunday, 02:00 to 05:00, Europe/Berlin. An end before the start runs past midnight. Upgrades you schedule for the window, patch releases and restarts of k3s happen only inside it (Upgrade a cluster). In progress Holding them to the window has not run on a real cluster yet.

Snapshots

Who holds the bucket’s keys, the S3 endpoint, Bucket, Folder and Region, Schedule (cron, UTC) (default 0 */6 * * *), Snapshots to keep (default 28) and, when the portal holds them, the Access key and Secret key. Give the endpoint and the bucket, or neither. Without a bucket the snapshots stay on the server’s disk and are lost with it. Set up backups explains each field, who holds the keys, and how to add the bucket later.

Network and credentials

Field	What it does
Who may reach the Kubernetes API (port 6443)	Address ranges, one per line. The default is everyone, 0.0.0.0/0 and ::/0; put in the ranges you work from. You can change them later (Change who can reach the API).
Hetzner token inside the cluster	The cloud controller and the volume driver need a token of the same project. A separate token (recommended) can be revoked on its own, and a pod that reads it does not hold the token the portal creates servers with; paste it into Separate token. A copy of the project’s token is the alternative.

Choose Create cluster. The form checks the location, the type and a separate token with Hetzner first.

What the portal creates in your project

The cluster’s page shows each step as the portal works through it:

1. validate: the token, the location, the server type, the release.
2. image: the node image is copied into your project, once per project and architecture; it stays there for later clusters.
3. network: 10.0.0.0/16 with the subnet 10.0.1.0/24.
4. firewall: port 6443 from your ranges, ports 80 and 443 from everyone, ICMP, nothing else. Port 22 (SSH) stays closed.
5. primary_ip and dns: an IPv4 address of the cluster’s own, and the API’s name pointing at it.
6. server: from the node image, in the network, behind the firewall.
7. enrollment: the user data holds only where to get pbx-agent and its checksum, the portal’s address, the cluster’s ID, the node’s name and a single-use enrollment token that expires after 30 minutes. The portal checks that the server booted exactly the image of the cluster’s release.
8. api_healthy, then ready: pbx-agent starts k3s and reports a healthy Kubernetes API. Billing starts then.

Every resource carries the labels pbx-cluster=<the cluster's ID> and pbx-managed=true. In the lab, ready took 2 minutes 46 seconds on a cpx22, 69 of them for the image copy; from outside, only 6443, 80, 443 and ICMP answered.

If a step fails

The cluster’s Overview shows Stopped at step with the step’s name and the error. The portal deletes nothing, so you can look at your project. Fix the cause, for example a token Hetzner refuses or a project at its Hetzner limit, and choose Retry from the step. A server whose enrollment token expired unused is replaced with fresh user data. Troubleshooting lists the usual causes.

Set up backupsPoint the snapshots at your bucket, and choose who holds its keys.

Get a kubeconfigReach the new cluster with kubectl.