Rotate credentials

A cluster of PaaSbox Clusters works with several credentials: the Hetzner token the portal creates servers with, the Hetzner token the cluster itself uses, the keys of your snapshot bucket, pbx-agent’s own keys, and the DNS tokens of some add-ons. This page replaces each one, so that a leaked or departing credential stops working without stopping your apps.

In progress: not bookable yet

Built in a lab: on 2026-10-10, on a real server, pbx-agent rotated its own keys in 17 seconds and kept syncing, and a swap of the bucket’s keys took 8 seconds; a wrong key pair was refused and the keys in force stayed. Replacing the project’s token and the token inside the cluster is In progress: built, not yet run on a real cluster. Tell me when it opens.

Credential	Who uses it	Where you replace it	Status
The project’s Hetzner token	the portal, to create and delete resources	PaaSbox Clusters → Hetzner projects	In progress
The Hetzner token inside the cluster	the cloud controller and the volume driver	the cluster’s Settings → Credentials	In progress
The bucket’s keys	k3s, for every snapshot	the cluster’s Backups → Bucket keys	Built
pbx-agent’s keys	pbx-agent, to sign its calls and open what the portal seals	nowhere: they rotate on their own	Built
DNS tokens of add-ons	cert-manager, external-dns, the PaaSbox Platform	the cluster’s Add-ons	In progress
The k3s server token	k3s	no rotation in the portal	—

Each replacement is for team admins.

The project’s Hetzner token

The portal uses this token to create, change and delete the resources of your clusters. Nothing inside a cluster uses it, unless that cluster was created with A copy of the project’s token (next section).

1. In the Hetzner console, in the same project, create a new API token with Read & Write permission.

2. If a cluster of this project runs with a copy of the project’s token inside, replace that one first: its Settings → Credentials says a copy of the project’s token. The copy does not change when you replace the project’s token, and it would stop working when you revoke the old one.

3. In the portal, open PaaSbox Clusters → Hetzner projects. Under the project, paste the new token into New token for this project and choose Replace.

4. In the Hetzner console, revoke the old token.

The portal checks that the new token works and that it sees the servers of every cluster of this project. Hetzner tokens carry no project ID, so this is how the portal makes sure the token is for the same project; a token of another project is refused with the cluster’s name. If no cluster of the project has a server yet, the portal has nothing to compare, so check yourself that the token is from the right project. Check the token tests the token in use at any time, and the project shows when it was last checked.

The Hetzner token inside the cluster

The cluster’s cloud controller and its volume driver call the Hetzner API with this token. It is in the Secret kube-system/hcloud.

1. In the Hetzner console, in the cluster’s project, create a new API token with Read & Write permission.

2. On the cluster’s Settings, under Credentials, paste it into New Hetzner token and choose Replace the token inside the cluster.

3. Wait for pbx-agent’s next sync, about 30 seconds. It writes the new token into the Secret kube-system/hcloud and restarts the cloud controller and the volume driver, the way kubectl rollout restart does. Your own workloads are not restarted.

4. In the Hetzner console, revoke the old token.

The portal refuses a token that does not work or does not see the cluster’s servers. Credentials then says a separate token, with the date you saved it.

The bucket’s keys

k3s reads the bucket’s address and keys from the Secret kube-system/pbx-etcd-s3 for every snapshot, so a new pair needs no restart. If the portal holds the keys:

1. At your S3 provider, create a new key pair for the bucket. Keep the old one for now.

2. On the cluster’s Backups, under Bucket keys, enter the Access key and the Secret key and choose Save new keys.

3. The page says it is waiting for pbx-agent to list the bucket with the new access key. pbx-agent tries the new pair on the bucket first. If that works, the new pair replaces the one in use and pbx-agent writes it into the Secret; In use then shows the new access key’s first characters. If it fails, the keys in force stay, and the failed check is listed with its message.

4. At your S3 provider, revoke the old pair.

In the lab the check took 8 seconds, and the next snapshot went to the bucket with the new pair.

In progress If you hold the bucket’s keys yourself, the portal takes none: you write the new pair into the Secret kube-system/pbx-etcd-s3 yourself (the keys etcd-s3-access-key and etcd-s3-secret-key), and pbx-agent never changes it. Keys held by the customer have not run in the lab yet. Set up backups has the choice between the two.

pbx-agent’s keys

pbx-agent signs every call to the portal with a key of its own, and opens what the portal seals for it with another. The portal has it replace both on its own every 90 days: pbx-agent makes new keys, registers them with the portal and confirms them, and the first call signed with the new key retires the old one. Nothing for you to do; the operation shows up under Operations.

DNS tokens of add-ons

In progress cert-manager with DNS-01, external-dns and the PaaSbox Platform with wildcard certificates use a DNS API token, which you enter as an option on the cluster’s Add-ons. The field never shows the stored token. Enter the new token and save; a blank field keeps the stored one. pbx-agent writes it into the add-on’s Secret, kube-system/pbx-addon-<name>. Then revoke the old token where you created it. These add-on paths have not run in the lab yet. Choose add-ons.

The k3s server token

The portal has no way to rotate the k3s server token. Do not rotate it by hand while the portal manages the cluster: the portal finds the token a snapshot needs by the token’s hash in the snapshot, and it would find none for snapshots taken after a rotation by hand, so it could not restore them. After you detach, the token is yours to rotate; Run without PaaSbox says how.

Security modelWhat the portal holds, and what a leaked database or a compromised portal could do with it.

Set up backupsThe bucket, who holds its keys, the schedule and the retention.