CluPilotCloud/docs/superpowers/specs/2026-08-01-hostname-vergabe-design.md

Hostnamen vergibt CluPilot, nicht der Betreiber

Stand: Entwurf, 1. August 2026 Auslöser: gemessen auf pve-fns-1, dem ersten echten Host

---

Das Problem, an dem es aufgefallen ist

Der Betreiber legte einen Host als pve-fns-1 an. Die Konsole zeigte diesen Namen, PrepareBaseSystem setzte ihn als Hostnamen, und Proxmox übernahm ihn als Node-Namen.

RegisterHostDns trug aber etwas anderes ein:

10.66.0.100 fsn-01.node.clupilot.com

HostTakeoverCommand::fqdnFor() bildet den Namen systematisch aus Rechenzentrum und laufender Nummer — unabhängig davon, was eingegeben wurde.

Damit führt CluPilot zwei Namen für dieselbe Maschine, und nur einer davon löst auf. Der Betreiber rief den Namen auf, den er selbst vergeben hatte, und stand vor einer Seite, die nicht lädt. Nirgendwo in der Oberfläche stand, dass es einen zweiten gibt.

Das ist keine Anzeigeschwäche. Es sind zwei Wahrheiten über dieselbe Sache, und die zweite fällt erst auf, wenn jemand sie braucht.

Die Entscheidung

Der systematische Name gewinnt. Das Namensfeld entfällt.

Der Betreiber wählt ein Rechenzentrum und trägt IP und Root-Passwort ein. Den Namen vergibt CluPilot:

<rz>-<nn>          fsn-03
<rz>-<nn>.node.<zone>   fsn-03.node.clupilot.com

Ein Name, an einer Stelle gebildet, von Maschine, Proxmox-Node, DNS und Konsole gleichermaßen benutzt.

Begründung des Besitzers, wörtlich: „das wäre sogar besser wie pve-fns-1 was ich eingetragen habe." Ein selbst getippter Name ist eine Fehlerquelle ohne Gegenwert — er muss eindeutig sein, DNS-tauglich, und er sagt nichts, was das Rechenzentrum nicht schon sagt.

Wie die Nummer vergeben wird

Fortlaufend je Rechenzentrum, niemals wiederverwendet.

Eine gelöschte fsn-02 steht danach noch in Protokollen, in Sicherungen, in der Überwachungshistorie und im DNS-Zwischenspeicher. Bekäme die nächste Maschine denselben Namen, teilten sich zwei verschiedene Server einen Namen über die Zeit — und niemand könnte im Nachhinein sagen, welche gemeint war.

MAX(nummer) + 1 reicht dafür nicht, weil PurgeHost die Zeile löscht und das Maximum damit zurückfällt. Der Zähler muss die Löschung überleben:

• Spalte next_host_number an datacenters, Vorgabe 1
• Vergabe erhöht sie, Löschen eines Hosts fasst sie nicht an
• Vergabe innerhalb der bestehenden Transaktion in StartHostOnboarding, mit Sperre auf die Rechenzentrums-Zeile (lockForUpdate)
• Zusätzlich ein eindeutiger Index auf hosts.name — ein Riegel, kein Ersatz

Zweistellig aufgefüllt (fsn-03), ab hundert wächst es natürlich weiter (fsn-100). Kein Sonderfall nötig.

Was sich ändert

Ort	Heute	Danach
Admin\HostCreate	Feld „Name", Pflicht	entfällt; die Seite zeigt, welcher Name vergeben wird
StartHostOnboarding	nimmt name entgegen	vergibt ihn selbst aus dem Rechenzentrum
HostTakeoverCommand::fqdnFor()	bildet <rz>-<nn> eigenständig	$host->name.'.node.'.$zone — eine Zeile
RegisterHostDns	eigene Ableitung	benutzt dieselbe Quelle
PrepareBaseSystem	hostnamectl set-hostname $host->name	unverändert — der Name ist jetzt der richtige
datacenters	—	Spalte next_host_number
hosts	name frei	eindeutiger Index auf name

PrepareBaseSystem bleibt bewusst unangetastet: Es setzte immer schon $host->name. Sobald der Name systematisch ist, stimmen Maschine, Node und DNS von selbst überein. Das ist der Beweis, dass die Reparatur an der richtigen Stelle sitzt — sie entfernt eine zweite Quelle, statt eine dritte einzuführen.

Die Anlegen-Seite sagt den Namen vorher

Ein Name, der ohne Ankündigung entsteht, ist eine Überraschung. Die Seite zeigt ihn, sobald ein Rechenzentrum gewählt ist:

Dieser Host wird fsn-03 heißen und unter fsn-03.node.clupilot.com erreichbar sein.

Vergeben wird er trotzdem erst beim Speichern — die Vorschau liest den Zähler, sie verbraucht ihn nicht. Zwei gleichzeitig geöffnete Formulare zeigen also beide fsn-03, und der zweite bekommt beim Speichern fsn-04. Das ist richtig so und darf nicht durch eine Reservierung „behoben" werden: ein abgebrochenes Formular hinterließe sonst eine Lücke im Zähler, die niemand wieder auffüllt.

Der bestehende Host

pve-fns-1 läuft, sein Proxmox-Node heißt so, und ein Node lässt sich nachträglich nur mühsam umbenennen.

Die Zeile wird auf fsn-01 umbenannt, die Maschine nicht. Konsole und DNS stimmen damit überein; dass der Proxmox-Node anders heißt, ist sichtbar und schadet nicht — die Host-Detailseite führt „Node" ohnehin als eigenes Feld.

datacenters.next_host_number für fsn startet entsprechend bei 2.

Abnahme

1. Host in fsn anlegen ohne Namensfeld → heißt fsn-02, DNS löst auf
2. Zweiten anlegen → fsn-03, keine Kollision
3. fsn-02 entfernen, dritten anlegen → fsn-04, nicht fsn-02
4. Auf der Maschine: hostname meldet denselben Namen wie das DNS
5. Zwei Formulare gleichzeitig: beide zeigen fsn-05, gespeichert wird fsn-05 und fsn-06

Punkt 3 ist der, der die Sorgfalt trägt. Er scheitert bei jeder Umsetzung, die MAX(nummer) + 1 rechnet.

Reihenfolge

Nach vmbr0, vor der vollständigen Abnahmeinstallation. Der Besitzer will die Namensvergabe im selben Durchlauf prüfen, in dem eine frische Maschine ohne einen Handgriff auf active geht.