Create your first cluster

This is the first step of the Learn path. You create the cluster you keep for the steps after it, and this time every choice is deliberate: a Hetzner project of its own, a separate token inside the cluster, the Kubernetes API open only to you, and a bucket for snapshots. Then you find each part of the cluster again, in your Hetzner project and in Kubernetes.

In progress: not bookable yet

Built in a lab: on 2026-10-10 the portal created clusters like this one on real Hetzner servers, with snapshots to S3 and kubeconfigs from the browser. That run started the create with a management command; the form is In progress. You cannot follow these steps yet. Tell me when it opens.

What you will have

A single-node k3s cluster named upcheck-prod, for the production of one app. The Learn path deploys upcheck, a small Django app, and names each cluster after the app and the stage; step 4 adds upcheck-staging next to this one.

It costs €29 incl. VAT a month, or $29 plus applicable sales tax outside the EU. If it is your team’s first cluster, it starts the team’s subscription and costs the full month even if you delete it early. If you kept the Quick start’s cluster first, delete that one once upcheck-prod is ready: it is then not the team’s only cluster, and the rest of its month is credited. In progress Billing through Paddle has not run yet.

What you need

• A new Hetzner Cloud project, used only for your clusters. A Hetzner API token opens its whole project, read and write; Hetzner offers no narrower kind. A project of its own keeps that reach to your clusters.
• Two API tokens of that project, both Read & Write, from Security → API tokens in the Hetzner console. The first is for the portal, which creates the server. The second is for the cluster itself: its cloud controller and its volume driver need one. A pod that reads the second token never holds the first, and you can revoke it on its own.
• An S3 bucket with an access key and a secret key, for the snapshots. A bucket at Hetzner Object Storage in the cluster’s location costs least. In progress Hetzner Object Storage itself has not run with PaaSbox yet; the lab used a self-hosted S3 server in its place.
• The public IP address you work from, to open the Kubernetes API to it and to nothing else.
• kubectl on your computer, and a browser with JavaScript.

Create the cluster

1. Connect the project. Open PaaSbox Clusters → Hetzner projects, choose Add a Hetzner project, enter a Project name, paste the first token under HCLOUD_TOKEN (read/write) and choose Validate & connect. If the project already holds resources other than servers, such as networks or snapshots, the portal lists them and asks you to confirm that the project is dedicated to PaaSbox. A new project holds none.

2. Name it. Choose New cluster. Enter the Name upcheck-prod and leave DNS label empty: it is made from the name. The DNS label becomes the first part of the Kubernetes API’s name and cannot change later.

3. Choose the server. Keep A new server. Choose a Location near your users and the Server type cpx22: 4 GB of memory carry the cluster and a small app. Keep the channel stable and the topology Single node. Leave PaaSbox Platform at No platform; step 2 switches it on.

4. Set the maintenance window. The default is Saturday and Sunday, 02:00 to 05:00, Europe/Berlin. The window is for upgrades and restarts of k3s, and every upgrade reboots the node, so pick hours when nobody uses the app. In progress Holding scheduled upgrades and restarts to the window has not run on a real cluster yet.

5. Point the snapshots at your bucket. Keep Who holds the bucket’s keys at the portal (who holds the keys decides whether the portal can read your snapshots). Enter the S3 endpoint as a host name without https://, the Bucket, the Folder upcheck-prod and the Region, then the Access key and Secret key. Keep the schedule: a snapshot every six hours, the last 28 kept, which is seven days.

6. Open the API only to you. Under Who may reach the Kubernetes API (port 6443), replace 0.0.0.0/0 and ::/0 with your address, for example 203.0.113.7/32. Ports 80 and 443 stay open to everyone for your app; port 22 stays closed.

7. Give the cluster its own token. Under Hetzner token inside the cluster, keep A separate token (recommended) and paste the second token.

8. Create it. Choose Create cluster and watch the steps on the cluster’s page. The cluster is ready when pbx-agent reports a healthy Kubernetes API; in the lab that took 2 minutes 46 seconds, 69 of them for copying the node image into the new project.

Find it in your Hetzner project

Open the project in the Hetzner console. Everything the portal created for the cluster carries the labels pbx-cluster=<the cluster's ID> and pbx-managed=true, so you can tell it apart from anything else:

• the server upcheck-prod-cp-1, made from a snapshot labelled pbx-image: the node image, copied into the project once;
• a private network, 10.0.0.0/16 with the subnet 10.0.1.0/24;
• a firewall that lets in port 6443 from your address, ports 80 and 443 from everyone, and ICMP, and nothing else;
• a primary IPv4 address.

The cluster’s page shows the Kubernetes API’s name at the top. It is upcheck-prod.<your team>.k3s. followed by PaaSbox’s zone, and it points at that address.

Look inside

1. On the cluster’s Access tab, choose admin and 1 hour, then Get kubeconfig and Download kubeconfig. A view kubeconfig would be read-only and could not list the nodes.

2. List the node and what runs on it:

   export KUBECONFIG=~/Downloads/upcheck-prod-admin.kubeconfig
   kubectl get nodes -o wide
   kubectl get pods -A

   One node, upcheck-prod-cp-1, Ready, with the k3s version of the cluster’s release. The pods are CoreDNS, Traefik on ports 80 and 443, metrics-server, the Hetzner cloud controller and the driver for volumes on the server’s disk. In the lab, a fresh cluster used 1.2 GiB of the cpx22’s memory.

3. Look at the storage and the two Secrets pbx-agent wrote:

   kubectl get storageclass
   kubectl -n kube-system get secret hcloud pbx-etcd-s3

   local-lvm-thin is the default class: volumes on the server’s own disk. The Secret hcloud holds the second token, for the cloud controller and the volume driver; pbx-etcd-s3 holds your bucket’s address and keys, which k3s reads for every snapshot.

Take a first snapshot

1. On the cluster’s Overview, choose Snapshot now. Operations shows its steps; in the lab a snapshot reached the bucket in 25 seconds.

2. Open Backups. The snapshot is listed under Snapshots, and Where says it is in S3. Look in your bucket: the file is in the folder upcheck-prod.

What you have now

A cluster for the production of one app, in a project of its own, with the API open only to you, its own token for the cloud controller, and snapshots in your bucket every six hours. Keep it: the next step deploys the app on it.

2 · Deploy your first appRun upcheck with its database on this cluster, reachable over HTTPS.

Create a clusterEvery field of the form, and what to do when a step fails.