From token to cluster

You paste a Hetzner Cloud API token; roughly 10–15 minutes later you run kubectl get nodes against your own cluster. This page walks through exactly what happens in between, what shows up in your Hetzner project (and what never does), and the three optional topologies you can choose for your worker nodes.

Before you start

You need three things:

• A Hetzner Cloud project. We recommend a project dedicated to paasbox: the token you hand us is scoped to exactly one project, so a dedicated project keeps a clean boundary between what the platform manages and everything else you run at Hetzner.
• An API token for that project with read & write permission (Hetzner Console → your project → Security → API tokens). Read/write is required because on-demand node pools legitimately create and delete servers — see the FAQ for the honest detail, including why adopted servers are never deleted regardless of what the token would allow.
• A payment method on file — the card gates cluster creation; there’s no charge until you start a cluster. See How paasbox works.

Token custody. The token enters the platform once, is stored encrypted, and is never displayed again — not in the console, not in the API. It is used exclusively to provision and manage cluster resources in your project: create and configure servers, networks, load balancers, and volumes there. It grants no access to anything outside that project, and you can rotate it in the portal — or revoke it at Hetzner — at any time.

The provisioning timeline

1. Your token is validated

   paasbox checks that the token can list your project, then stores it encrypted. If you plan to bring existing servers, the portal lists your project’s servers now so you can pick which ones to adopt.

2. The node operating-system image lands in your project

   Hetzner images are project-scoped — there is no cross-project image sharing — so we publish our node OS image into your project as one snapshot of about 0.25 GB. Snapshot storage costs you a fraction of a cent per month. This happens once per project; later image versions arrive the same way (see ongoing operations).

3. Your control plane starts — on our infrastructure

   The cluster’s control plane (API server, etcd, scheduler, controllers) starts as managed pods on the platform we operate. It never runs inside your project and never appears on your Hetzner bill — it’s covered by the flat fee. See What you bring & what we run.

4. Worker servers appear in your project

   A private network is created for the cluster, then the node pools come up:

   • Managed (on-demand) pools — new servers are created from the snapshot, at current Hetzner prices.
   • Pooled (adopted) pools — your existing servers are reinstalled in place and join the cluster as they are. No new order, no deletion — that’s how their grandfathered price survives.

5. Nodes join the cluster

   Each worker boots from the image, configures itself, and opens an outbound connection to your control plane. Your project needs no inbound access from us — there is nothing to open up or expose.

6. Ready — get your kubeconfig

   When the cluster reports Ready, download a short-lived admin kubeconfig from the console or the API (Access your cluster), or wire up your own identity provider. From here on it’s kubectl, Helm, or Flux — your cluster, your tools.

Adopting existing servers adds one step to the clock: adoption reinstalls the OS, which wipes the disk, so each adopted server goes through a rebuild before it joins. Migrate workloads off first — the portal makes you confirm this explicitly.

What you’ll see in your Hetzner project

After provisioning, your project contains exactly the resources your cluster is made of:

Resource	How many	What it is
OS snapshot	1–2	The node operating-system image (~0.25 GB each). We keep the current and previous version.
Private network	1	Node-to-node and node-to-control-plane traffic for the cluster.
Worker servers	N	Your node pools — created from the snapshot, or your adopted servers. Billed by Hetzner to you.
Load balancers	0+	Created on demand when you create a Service of type LoadBalancer.
Volumes	0+	Created on demand when your workloads request persistent storage (PVCs). Resize online, in place.

These resources are managed — don’t edit them by hand

Deleting or modifying the snapshot, the private network, or the worker servers in the Hetzner Console will break your cluster — the platform continuously reconciles against them. To remove something, act in the paasbox console instead: scale a pool down, or delete the cluster (which removes what we created — but never your adopted servers).

The three optional topologies

A default cluster runs cloud servers with public IPs. Three optional topologies change what your worker fleet looks like — you can combine them per node pool.

Private worker nodes behind a NAT gateway

Choose this when you want a smaller attack surface — workers with no public IPv4 at all — and want to stop paying Hetzner’s per-address IPv4 fee for every node.

What changes: your workers get no public IP; they live only on the cluster’s private network. A small NAT gateway — deployed and managed by the platform — carries their outbound traffic (image pulls, OS updates, your workloads’ egress). Load balancers still expose your services to the internet exactly as before.

Provisioning works unchanged: a new node receives its first-boot configuration over the cloud’s internal metadata channel, which needs no public IP — so private nodes are created, join, and update just like public ones.

Early access. Private networking is rolling out cluster by cluster — tell us when you create your cluster and we’ll enable it for you.

Bring your existing (price-locked) servers as a node pool

Choose this when you hold servers ordered before Hetzner’s price increase and want to keep that rate while running them as Kubernetes nodes. This is the reason paasbox exists.

What changes: nothing is ordered and nothing is deleted. Your servers are adopted: reinstalled in place, joined to the cluster, and from then on operated under a strict rule — only deleting a server or changing its plan ever reprices it, and paasbox does neither, ever. Every lifecycle operation (upgrades, node repair, image changes, hibernate and wake) is performed by reinstalling the same server in place, and Hetzner’s own delete protection is enabled as a second guard. On node pools whose OS supports it, updates apply in place on the running server — no reinstall, no replacement, and the price survives either way.

Leaving is just as safe: remove a pool or delete the cluster and your adopted servers are handed back to you intact — still yours, still at your price.

Dedicated (bare-metal) servers behind a vSwitch

Choose this when you want serious, steady capacity per euro: Hetzner’s dedicated lines offer far more cores and memory per monthly euro than cloud servers, and price-locked dedicated boxes keep their rate here too.

What changes: your physical servers join the cluster over a private VLAN (Hetzner vSwitch) bridged into the cluster’s cloud network, so dedicated and cloud nodes talk privately as one cluster — mixed pools are a supported shape, with cloud nodes for burst and metal for the baseline. Since bare metal can’t boot from a cloud snapshot, imaging happens through Hetzner’s rescue system instead. The same never-delete discipline applies: dedicated servers are never cancelled by the platform.

Coming soon. Dedicated node pools are not yet generally available. If you have Robot servers you’d like to bring, register your interest — like new regions, we prioritise by demand.

After day one: ongoing operations

• Image updates arrive automatically. When we release a new node OS version, the new snapshot is published into your project the same way as the first one. This is non-disruptive — a snapshot is just data at rest until nodes update from it.
• Node updates roll in your maintenance window. Kubernetes and OS updates apply during the maintenance window you set on the cluster — never at a time we pick. On supported pools the update is applied in place on the running server; adopted servers are otherwise reinstalled in place; only on-demand nodes are ever replaced.
• Snapshots are tidied for you. We keep the current and the previous image version in your project and remove older ones, so snapshot storage stays at rounding-error cost.

Common questions

What happens if I revoke the token?

Your cluster keeps running — nodes and control plane don’t depend on the token from minute to minute, and your kubeconfig keeps working. What stops is management of your project: no scaling, no new or repaired nodes, no load-balancer or volume changes, no image updates. The console shows the connection as invalid; paste a fresh token and management resumes.

Which costs land in my project, and which are yours?

Yours (billed by Hetzner): worker servers, load balancers, volumes, public IPv4 addresses, and the ~0.25 GB of snapshot storage. Ours (covered by the flat fee): the control plane and everything else we operate — see Pricing & fair-use.

Does anything of mine run on your infrastructure?

Only your cluster’s control plane. Your workloads run exclusively on the workers in your own project — we never host, and never see, your application traffic or data.