Detach or delete a cluster

You can leave at any time, in one of two ways. Detach keeps the cluster running in your project and stops the portal from managing it; delete removes the cluster and everything the portal created for it. Both stop billing, and in both cases your snapshots stay in your bucket.

In progress: not bookable yet

Built in a lab: on 2026-10-10 a delete removed a cluster from a real Hetzner project in 14 seconds, its Hetzner volume included, and the delete of a cluster on an adopted server handed that server back in 23 seconds. Detach, pbx-agent uninstall and billing through Paddle are In progress: built and tested against simulated counterparts, not yet run on a real cluster. Tell me when it opens.

Which to choose

	Detach	Delete
The cluster	keeps running, unmanaged	removed
The server	stays	deleted (an adopted one is handed back)
Data on the server’s disk	stays	gone (an adopted server keeps its disk)
Hetzner volumes of the volume add-on	stay	deleted
Snapshots in your bucket	stay, and k3s keeps adding new ones	stay
The API’s DNS name	stays 30 days	removed
Billing	stops	stops

Billing stops for the cluster when you confirm. In progress Paddle credits the rest of the month on your next bill, except for the team’s last cluster: then the subscription ends with the month already paid, and a cluster you create before that month ends uses it again (Costs and billing).

What you need

• To be a team admin. Both cards are on the cluster’s Settings, for team admins only.
• The cluster’s name, to type as confirmation.
• Before a detach: what Run without PaaSbox lists under “Before you detach”, while the portal still works.

Detach

1. On the cluster’s Settings, under Detach, type the cluster’s name.

2. Choose Detach. The page says “Detached. The cluster keeps running; the portal no longer manages it.”, and the cluster’s Overview shows the date its DNS name goes.

What happens:

• The portal revokes pbx-agent. It stops calling the portal and changes nothing more; it stays on the server, idle, until you remove it.
• Billing stops.
• The cluster keeps running in your project, untouched: the server, k3s, your workloads, the firewall and the network stay as they are.
• k3s keeps taking the scheduled snapshots and uploading them to your bucket, as long as the keys in the cluster’s Secret kube-system/pbx-etcd-s3 stay valid.
• The cluster’s API name stays for 30 days, so you can move to a name of your own. After that the portal removes it.

Nobody maintains the cluster from the portal any more: no upgrades, no kubeconfigs from the portal, no restores. Run without PaaSbox is the runbook for what you do from then on.

Remove pbx-agent from the server

On the server, as root (Get root on the server):

pbx-agent uninstall          # prints what it would do, changes nothing
pbx-agent uninstall --yes    # does it

It disables and removes pbx-agent’s systemd unit and its rollback timer, and removes /var/lib/pbx-agent and /etc/pbx-agent. k3s, its configuration and every Kubernetes object stay as they are.

You can also run it without detaching first. The portal then no longer hears from the server: after five minutes the cluster is flagged agent not reporting, after 24 hours the team’s admins get a mail In progress, and billing continues until you detach or delete the cluster in the portal.

Delete

1. On the cluster’s Settings, under Delete, decide about Take a final snapshot first (ticked by default). Without a bucket, the final snapshot would land on the server’s disk, which is deleted too; untick it then.

2. Type the cluster’s name and choose Delete cluster. The page says “Deleting. Billing stopped now; the servers go in the next minutes.”

What happens, in this order:

1. Billing stops when you confirm.
2. If you asked for a final snapshot, pbx-agent takes one and uploads it to your bucket. A final snapshot that does not come within 15 minutes is skipped: you asked to delete.
3. The portal revokes pbx-agent.
4. It deletes the server, then the Hetzner volumes of the volume add-on (detaching any that is still attached), the primary IP address, the firewall, the private network and any placement group, every one found by the cluster’s label pbx-cluster, and then the API’s DNS name.

If a step fails, the cluster’s page shows the step, and Retry from that step resumes the delete; each pass deletes what it still finds.

What a delete does not touch:

• Your bucket’s contents. Every snapshot stays.
• The node image in your project. Other clusters in the project use it; delete it in the Hetzner console when none is left.
• A server you already had. An adopted server is never deleted. It leaves the cluster’s network, loses the cluster’s labels and with them the cluster’s firewall, and gets its old name back. It keeps running as it is, with the cluster’s system and data on its disk and no firewall of the portal’s in front of it; Hetzner keeps billing it to you. Use a server you already have.
• Anything you created yourself in the project, such as a firewall of your own for SSH.

Data on a deleted server, and on the Hetzner volumes the cluster created, is gone.

In progress An agent with an API key that has the scope k3s:destructive can detach or delete a cluster too, only with the cluster’s name as confirmation. Give an agent access.

If an invoice stays unpaid

In progress An unpaid invoice never deletes anything. The team’s admins get a mail on day 1, 7 and 13. After 14 days the portal detaches the team’s clusters: they keep running in your project, the portal stops managing them, billing stops, and their DNS names go 30 days later. While an invoice is unpaid, the team cannot create a new cluster. Paddle collects the payment and issues the invoices; that integration has not run with real payments yet. Costs and billing.

Run without PaaSboxKeep a detached cluster running: what to replace, your own DNS name, snapshots and restores by hand.

Quick startThe loop the approach is built on: create a cluster, use it, delete it.