DNS names for your clusters

A cluster needs names: one for its Kubernetes API, one or more for the apps behind its ingress, and a TXT record whenever Let’s Encrypt checks a DNS-01 challenge for a certificate. If you have no domain of your own, or do not want to use it yet, PaaSbox gives your team one: <team>.paasbox.app, free, with the records a cluster needs below it.

Built The API runs at https://dns.paasbox.com/v1. The service opens with the components’ first release: until then no team tokens are handed out.

What you get

• A name for your team. <team> is your team’s name made into a DNS label: lower case, letters, digits and hyphens, at most 32 characters. Everything below it is yours to write, for example api.prod.acme.paasbox.app or *.apps.acme.paasbox.app.
• The records a cluster needs: A, AAAA, CNAME and TXT. TXT is what Let’s Encrypt’s DNS-01 challenge needs, so wildcard certificates work too.
• An API that Hetzner’s clients speak. It answers the zone and record-set requests of the Hetzner Cloud API with Hetzner’s own request and answer bodies. The hcloud CLI and Hetzner’s Go client work with it unchanged, and so do the cert-manager webhook and the Gardener DNS extension among the open components; you set two things, the endpoint and the token.
• A team token. It starts with pbdns_, is shown once, carries the scope dns and nothing else, and belongs to the team, not to a person: a cluster keeps its DNS when the person who created the token leaves. A team can hold up to five active tokens and revoke any of them.
• An audit log. Every write is recorded with the team, the token, the name, the record type and the answer, including the writes Hetzner refused.

Using it

Point a Hetzner DNS client at the endpoint, with your team token:

export HCLOUD_ENDPOINT=https://dns.paasbox.com/v1
export HCLOUD_TOKEN=pbdns_…            # your team token

# api.prod.acme.paasbox.app → 203.0.113.7
hcloud zone rrset set-records --record 203.0.113.7 paasbox.app api.prod.acme A

The zone is always paasbox.app, and record names are relative to it: api.prod.acme is api.prod.acme.paasbox.app. The DNS API lists every endpoint, the limits and the errors.

The sign-in. Built The paasbox CLI fetches a token itself: it shows a short code, you approve it in your browser after one sign-in to the PaaSbox portal, and the token goes to the CLI without being shown anywhere in between. It is the OAuth device flow that gh auth login uses, so it works over SSH and on a machine without a browser. It opens with the service.

What it refuses

The token can write only below your team’s name. Everything else is refused:

• NS records, anywhere: a name below yours cannot be delegated to another server.
• The zone apex and other teams’ names. Reading another team’s name answers 404, not 403, so the zone cannot be listed through the API.
• Reserved names that PaaSbox answers on itself, such as www, mail and api: no team gets one of them as its name.

Limits

Records per team	200, counted across all your record sets
Records per record set	50
Active tokens per team	5
Requests	In progress 120 per minute per token, 600 per minute per team, and 300 per minute per address before a token is checked; over a limit, Hetzner’s own answer 429 rate_limit_exceeded

Names for PaaSbox Clusters

Built in a lab. Every PaaSbox Clusters cluster gets a name for its Kubernetes API, <cluster>.<team>.k3s.paasbox.app, pointing at the server’s IPv4 address. The portal writes it itself; no team token is involved, and the k3s label is reserved for it. Deleting the cluster removes the name. After a detach the name stays for 30 days, so you can move the cluster to a name of your own. In the lab run of 2026-10-10 the portal wrote and removed these names in a test zone; under paasbox.app they come with PaaSbox Clusters.

The k3s name is for the Kubernetes API only. An app gets a name of its own, pointing at the same server: in a domain you own, or below <team>.paasbox.app once this service opens. Deploy your first app shows the steps.

Demo names

In progress For a demo or a course, before anybody has set up DNS: a random name under demo.paasbox.app, such as k3x9q7m2p4ta.demo.paasbox.app, and a token that can write only below it. A demo lives 4 hours unless you ask for longer, at most 7 days from its creation, with up to 20 records. When it is deleted or expires, its records are deleted and its token stops working. A trainer can hand a room a course code instead of tokens. Built and tested on a branch; not released.

What it does not promise

The names come with no promise of availability. For anything that must keep working, use a zone of your own at Hetzner: the same clients write to it with your own Hetzner token and Hetzner’s own endpoint, so moving is a change of the endpoint, the token and the zone name.

The DNS APIEvery endpoint, the limits and the errors.

Deploy your first appLearn step 2: an app with its database, under a name of its own, over HTTPS.