Anmelden und gehostete Namen

Gardener braucht Namen. Der API-Server des Gardens, das Dashboard, das Ingress-Wildcard des Seeds und der API-Server jedes Shoots brauchen einen DNS-Namen, und Let’s Encrypt braucht einen TXT-Record, bevor es ein Zertifikat dafür ausstellt. DNS ist also die eine Voraussetzung einer Landschaft neben dem Hetzner-Token, und die eine Entscheidung, die du triffst, bevor du etwas ausführst.

Drei Wege zu Namen

`dns.mode`	was es dich kostet	was du bekommst
`zone`	eine Domain (etwa 10 € im Jahr) und eine Hetzner-DNS-Zone; deren Token in `$DNS_TOKEN`	deine eigenen Namen, mit niemandem geteilt. Die richtige Wahl für alles, was einen Versuch überdauert
`my-paasbox`	ein paasbox-Konto und eine Anmeldung im Browser	`<team>.paasbox.app`, kostenlos, mit den TXT-Records, die Let’s Encrypt braucht
`sslip`	nichts	Namen, die über sslip.io aus der IP des Nodes entstehen, ohne Zone und ohne Records. Garden, Dashboard und Seed-Ingress funktionieren, Shoots bekommen aber kein externes DNS, weil es nirgends hingeschrieben werden kann

sslip ist entworfen, aber noch nicht implementiert (Stand: 2026-09-07): Der Aufbau verweigert den Modus und nennt die beiden anderen. Die Datei, die paasbox garden init schreibt, beginnt mit dns.mode: sslip. Ändere das vor dem ersten paasbox garden up.

Später zu wechseln sind zwei Zeilen in der values.yaml und ein weiteres paasbox garden up. zone und sslip reden überhaupt nicht mit uns: kein Konto, keine Anmeldung, nichts zuzustimmen. Die Anmeldung unten taucht nur auf, wenn du einen kostenlosen gehosteten Namen willst. Dort ist das Konto das, was Missbrauch begrenzt.

Die Anmeldung, wie du sie erlebst

dns.mode: my-paasbox braucht einen Token für die Namen deines Teams. Einen aus einer Webseite zu kopieren ist genau die Art Schritt, die das Werkzeug abschaffen soll, also holt die CLI ihn selbst. Ruf paasbox auth login auf, oder starte den Aufbau und lass ihn es merken:

$ paasbox garden up my-garden
  dns.mode my-paasbox and no $DNS_TOKEN — signing in to console.paasbox.com

    open   https://console.paasbox.com/device        (opening your browser…)
    code   FTQK-2X7M                                 (expires in 10 minutes)

  waiting… ✓ signed in — team Acme GmbH → acme.paasbox.app
### check — preflight …

Das ist der OAuth-2.0-Device-Authorization-Grant (RFC 8628), derselbe Ablauf, den gh auth login und docker login nutzen. Es gibt keinen lokalen Callback-Server und keinen Port, den du frei halten musst. Es funktioniert also über SSH und auf einer Maschine ganz ohne Browser: --no-browser gibt die URL aus, und du bestätigst sie auf dem Telefon.

Auf der Seite unter console.paasbox.com/device meldest du dich wie gewohnt an der Console an und siehst dann, wer fragt (die CLI nennt ihre eigene Version), was sie danach tun darf, in Worten, und zu welchem Team der Token gehören wird. Dann:

Mehrere Teams: Du wählst eines aus. Ein Team, das nicht geht, wird mit dem Grund angezeigt, statt zu fehlen: Sein Slug ist kein DNS-Label, es ist ein reservierter Name, oder du bist kein Admin dieses Teams. Hier zu bestätigen ist genauso privilegiert, wie einen Token auf der Team-Seite auszustellen, also verlangt es dieselbe Rolle.
Noch kein Team: Leg direkt eines an. Der Slug wird beim Tippen von demselben Code geprüft, der später über den Button entscheidet.
Noch kein Konto: Registriere dich wie üblich, und du landest wieder auf der Bestätigungsseite.

Der Code hat acht Zeichen aus einem Alphabet ohne 0/O und ohne 1/I/l, wird als XXXX-XXXX angezeigt und in beliebiger Groß- und Kleinschreibung akzeptiert, mit oder ohne Bindestrich. Er gilt zehn Minuten und lässt sich genau einmal bestätigen. Der Token selbst entsteht erst, wenn die CLI ihn abholt, nicht wenn du auf Bestätigen drückst. Dazwischen ist er nirgends gespeichert.

Die Adresse des Portals ist in der CLI fest eingebaut und wird nie aus einer Antwort übernommen: Eine Antwort, die woandershin zeigt, bricht die Anmeldung ab und speichert nichts. $PAASBOX_PORTAL oder --portal überschreiben sie, wenn du eine eigene Instanz betreibst.

Der Team-Token, und wo er liegt

Was du bekommst, ist ein Team-Zugangsdatum, kein persönliches. Eine laufende Landschaft darf ihr DNS nicht verlieren, weil die Person geht, die den Token angelegt hat. Deshalb gehört er dem Team, trägt den Scope dns und sonst nichts und wird genau einmal angezeigt. Ein Team kann bis zu fünf aktive Tokens halten; widerrufen wird in der Console, auf der DNS-Seite des Teams.

Auf deiner Maschine liegt er in ~/.config/paasbox/credentials.json, Modus 0600 in einem 0700-Verzeichnis, abgelegt nach dem Host des Portals. Eine selbst betriebene Instanz und console.paasbox.com können also beide angemeldet sein, ohne sich zu überschreiben. Diese Datei ist die einzige Kopie. Sie wird nie in ein Landschafts-Verzeichnis geschrieben; läuft eine Stufe, bekommt genau dieser Kindprozess den Token als $DNS_TOKEN.

Was du schon hast, hat immer Vorrang: Ein exportiertes $DNS_TOKEN oder eines in der .env der Landschaft wird unverändert genutzt, und die gespeicherte Anmeldung bleibt unangetastet. paasbox garden up --no-login meldet sich gar nicht erst an und sagt dir, was fehlt.

paasbox auth login          # --team acme legt es fest, --no-browser gibt die URL aus
paasbox auth status         # wer du bist, gegen das Portal geprüft
paasbox auth token          # nur der Token, für ein Skript
paasbox auth logout         # hier vergessen; gültig bleibt er, bis du ihn widerrufst

Was `<team>.paasbox.app` dir gibt

Team acme besitzt acme.paasbox.app und alles darunter. Eine in diesem Modus aufgebaute Landschaft bekommt ihre Namen dort, ohne dass dir eine Domain gehört:


die Garden-API	`api.acme.paasbox.app`
das Gardener Dashboard	`dashboard.ingress.acme.paasbox.app`
der Ingress des Gardens	`*.ingress.acme.paasbox.app`
der Ingress des Seeds	`*.ingress.seed.acme.paasbox.app`
die API-Server deiner Shoots	unter `shoots.acme.paasbox.app`

Das sind echte Namen in einer echten Zone. Let’s Encrypt stellt also über die DNS-01-Challenge echte Zertifikate dafür aus, und Gardeners Hetzner-DNS-Extension schreibt sie selbst, wenn Shoots kommen und gehen. Die Records liegen im DNS von Hetzner und werden von Hetzner ausgeliefert; paasbox hält die Tokens, die Kontingente und eine Audit-Zeile pro Schreibvorgang.

Was er verweigert

Der Token ist auf ein Label begrenzt, und die API setzt das bei jedem Aufruf durch:

Ein Team, ein Name. Schreiben ist auf <team>.paasbox.app und alles darunter erlaubt. Der Zonen-Apex ist ausgeschlossen, ebenso jeder Name jedes anderen Teams und jeder Name von uns.
Lesen ist gefiltert. Du siehst deine eigenen Records und sonst nichts. Jeder andere Name antwortet mit 404, nicht mit 403, damit sich die Zone auf diesem Weg nicht aufzählen lässt.
Vier Record-Typen: A, AAAA, CNAME, TXT. NS wird überall verweigert, denn einen Namen wegzudelegieren hieße, ihn aus der Reichweite zu geben.
Reservierte Labels lassen sich nicht beanspruchen: www, api, dns, admin, mail, ns, _acme-challenge und das Label des API-Hosts selbst.
Dein Label ist dein Team-Slug, kleingeschrieben, Unterstriche zu Bindestrichen, höchstens 32 Zeichen. Ein Slug, der das nicht übersteht, wird abgelehnt, statt in den Namen eines Nachbarn geändert zu werden; die Seite sagt dir, dass du den Slug umbenennen sollst. Das Label wird auf dem Token eingefroren. Das Team später umzubenennen verschiebt also die Records einer laufenden Landschaft nicht; dafür braucht es einen neuen Token.
Kontingente (Stand: 2026-09-07): 200 Records und fünf aktive Tokens pro Team.

Jeder Schreibvorgang wird festgehalten, auch die verweigerten: Team, Token, Name, Typ, Aktion, Zeit und was die Gegenstelle geantwortet hat.

Das ist ein kostenloses Entgegenkommen für Landschaften, die du selbst betreibst, kein allgemeiner DNS-Dienst. Wenn die Landschaft wichtig ist, ist eine eigene Domain für etwa 10 € im Jahr mit dns.mode: zone die bessere Wahl.

Für Skripte und andere Clients

Dieselben Namen sind über eine kleine, Hetzner-Cloud-kompatible API erreichbar; hcloud zone rrset und jeder Hetzner-DNS-Client funktionieren unverändert dagegen. Endpunkt, Scope-Regeln und was verweigert wird stehen auf der API-Seite.

Weiter

Dein eigener Gardener hat die Values-Datei, die Größen, den Aufbau und die Befehle für den zweiten Tag.