Zum Inhalt

Verwaltung mit desync

Diese Seite erklärt, wie unsere DNS-Einträge als CUE-Dateien im Repo liegen und wie sie mit desync zu deSEC kommen. Wie unsere Zonen aufgebaut sind und wofür die Einträge da sind, steht in DNS.

Die Dateien in desec/

Alles zu DNS liegt im Ordner desec/, als CUE-Package desec:

Datei Inhalt
desec_garage_lab_de.cue alle Einträge der Zone garage-lab.de und die Token-Policy für das Caddy auf werner
desec_garage_lab_net.cue alle Einträge der Zone garage-lab.net und die Token-Policy für das Caddy auf containerhost
desync_schema.cue das Schema: welche Felder ein Eintrag und eine Token-Policy haben müssen
desync.cue macht aus den Zonendateien die Eingabe für desync
desync_tool.cue die Befehle cue cmd plan und cue cmd apply

Im Alltag ändert man nur die beiden Zonendateien.

Ein Eintrag

Jeder Eintrag in einer Zonendatei ist ein Record-Set: alle Werte eines Typs für einen Namen.

Text Only
1
{subname: "md", type: "A", records: [ipam.netcup_vps.a]},

subname ist der Name ohne Domain, hier md für md.garage-lab.de; ein leerer Name steht für die Domain selbst. type ist der Typ, etwa A für eine IPv4-Adresse, AAAA für IPv6, CNAME für einen Verweis auf einen anderen Namen oder TXT für Text. records sind die Werte; bei TXT-Records gehören die Anführungszeichen mit zum Wert und werden deshalb als \" geschrieben.

Die IP-Adressen stehen nur einmal am Anfang der Datei im Block ipam und werden in den Einträgen über ihren Namen verwendet, hier ipam.netcup_vps.a. Zieht ein Server um, ändert man die Adresse an einer Stelle.

Am Ende jeder Zonendatei stehen unter desec: tokenPolicies die Rechte eines Tokens; was das ist, steht in DNS.

plan und apply

Ausgerollt wird wie bei den Hosts mit cue cmd plan und cue cmd apply, hier im Ordner desec/. CUE baut aus den Zonendateien eine JSON-Datei und gibt sie an desync weiter, das auf deinem Rechner läuft und über die API von deSEC arbeitet:

  • plan holt den aktuellen Stand bei deSEC und zeigt, welche Einträge angelegt, geändert oder gelöscht würden.
  • apply zeigt dasselbe, fragt nach und überträgt die Änderungen dann zu deSEC.
flowchart LR
    zonen["desec_*.cue"]
    cue["CUE<br>cue cmd plan / apply"]
    desync["desync<br>(dein Rechner)"]
    desec["deSEC"]

    zonen --> cue -->|JSON| desync -->|"API, mit DESEC_TOKEN"| desec

Bei deSEC meldet sich desync mit einem Token an, das in der Umgebungsvariable DESEC_TOKEN stehen muss. Wir legen es mit den anderen API-Tokens in die Datei .envrc im Repo-Ordner, die Git ignoriert, sodass sie nie im Repo landet; direnv setzt die Variable, sobald man in den Repo-Ordner wechselt. Wie man das einrichtet, steht in Arbeitsrechner einrichten.

DNS verwalten wir genauso wie die Hosts: in CUE, mit plan und apply. Wer eine Stack-Datei ändern kann, kann auch einen DNS-Eintrag ändern. CUE prüft die Einträge außerdem, bevor etwas ausgerollt wird: Ein Eintrag ohne Typ oder eine IP-Adresse, die in ipam nicht existiert, kommt gar nicht erst bei deSEC an.

Für deSEC nutzen wir desync, ein Werkzeug nur für diesen Zweck. Die Token-Policies lassen sich in der Web-Oberfläche von deSEC gar nicht verwalten, und ein Werkzeug dafür gab es nicht; deshalb haben wir desync selbst gebaut. desync kann nur deSEC und nur Einträge und Token-Policies, dafür ist es schnell verstanden. Es arbeitet wie syslet mit plan und apply und braucht außer dem Token nichts. Wie syslet kommt desync aus unserem eigenen Kreis und nicht von deSEC; solche Werkzeuge setzen wir ein, weil wir ihnen vertrauen können (siehe Grundsätze).

Was desync verwaltet

desync gleicht jede Zone, die in den Dateien steht, vollständig ab: Ein Eintrag, der bei deSEC existiert, aber nicht in der Zonendatei, wird gelöscht. Genauso vollständig gleicht es die Rechte jedes Tokens ab, das unter tokenPolicies steht.

Nicht verwaltet werden die Domains selbst und die Tokens; beides legt man einmalig in der Web-Oberfläche von deSEC an. Ein Token zeigt deSEC nur beim Anlegen im Klartext, es lässt sich also nicht sinnvoll aus einer Datei heraus anlegen.

Eine Domain bei deSEC anzulegen, reicht außerdem nicht: Eine neue Domain muss zuerst beim Registrar hosting.de registriert werden (siehe DNS).

desync löscht alles, was nicht in der Zonendatei steht. So zeigt die Zonendatei genau das, was bei deSEC eingetragen ist. Ein Eintrag, den jemand in der Web-Oberfläche anlegt, taucht beim nächsten plan als Löschung auf; so fällt er auf, statt unbemerkt zu bleiben.

Weiterlesen