Glossar: groupdir-infra

Paketmanager & Betriebssystem

Nix / NixOS

Deklarative Builds und Systemkonfiguration. Im Repo: Flake, Module unter nixos/, lokales Prüfen mit nix build.

Flake: Einstieg flake.nix plus Lock flake.lock: pinnt Inputs und exportiert u. a. nixosConfigurations, devShells, colmenaHive, checks (Eval-Tests aus tests/, laufen mit nix flake check mit). Braucht nix-command und flakes.
Nix store: /nix/store/…-hash-name: unveränderliche Build-Ergebnisse. Grundlage für Versionen nebeneinander und atomare Systemwechsel.
Generation: Eine gebaute Systemkonfiguration zum Aktivieren. Wechsel atomar; alte Generationen erlauben Rollback.
nix develop: Öffnet die Dev-Shell aus dem Flake (devShells.default). In groupdir-infra u. a. mit tofu, just, colmena.
nix build: Baut ein Flake-Output, oft mit Symlink ./result. Zum lokalen Prüfen ohne Deploy.
NixOS-Modul: Datei unter nixos/modules/ mit options und config. Prefixe hier: labEdge.*.
mkOption: Hilfsfunktion zum Deklarieren einer Option (Typ, Default, Beschreibung).

Infrastructure as Code

Terraform / OpenTofu

In Lessons: Terraform-Begriffe (State, Plan, Apply, Provider). CLI im Repo: tofu (OpenTofu), weitgehend Drop-in. OpenTofu entstand als Community-Fork nach HashiCorps Wechsel zur BSL (2023) und liegt unter der Linux Foundation. Lesson 0003. Stacks: tofu/dns, tofu/proxmox.

Provider: Plugin für eine API (Hetzner Cloud DNS, Proxmox, …). Siehe tofu/*/providers.tf.
State: Buchführung der von Terraform verwalteten Remote-Objekte. In groupdir-infra remote in GitLab (groupdir-dns / groupdir-proxmox), nicht als Datei im Git-Repo. Siehe Repo-Betrieb.
Plan: Vorschau der Änderungen, ohne sie auszuführen. Beispiel: tofu -chdir=tofu/dns plan -out=tfplan.
Apply: Führt einen Plan aus und aktualisiert Reality plus State. Beispiel: tofu -chdir=tofu/dns apply tfplan.

Ausrollen & Install

Deploy

Alltag: Colmena. Einmalig: Disko (Platten) und nixos-anywhere (Erstinstallation).

Colmena: Deploy für NixOS-Hosts. Inventar (targetHost, targetUser, tags) in deployment.nix; hive.nix baut daraus die Colmena-Nodes. Befehle: colmena build, colmena apply, colmena apply --on HOST.
Disko: Deklarative Partitionierung: nixos/hosts/*/disko.nix. Vor allem bei Install und Neuanlage.
nixos-anywhere: Einmalige Remote-Installation von NixOS; danach Colmena. Siehe docs/install.md.

groupdir-infra

DNS

Lab-*.lab-A aus net/lab/hosts/; Zone net/dns/groupdir.de.nix merged mit öffentlichen und VPN-Records. Semantik: DNS-Records, lab-ipam.md.

DNS source of truth: Lab: net/lab/hosts/*.nix (Normalisierung in net/lab/hosts.nix) → net/lab/dns-records.nix. Zone: net/dns/groupdir.de.nix (staticRecords ++ labRecords, gebaut über net/dns/records.nix-Konstruktoren). Daraus Hetzner (tofu/dns) und internes DNS (lab-gateway, via net/dns/internal-view.nix).
Lab IPAM: net/lab/hosts/ + just lab-ipam: freie IPs und Host-Zuordnung im Lab-LAN (192.168.200.0/24.
scope: public | internal | both. Öffentlich: Hetzner. Intern: lab-gateway.
target: Intern bei A-Records: direct (→ value) oder reverse-proxy (→ Gateway + Caddy zu upstream).
upstream: Bei reverse-proxy: Backend-URL für Caddy, z. B. http://192.168.200.30:3000.

groupdir-infra

WireGuard

Tunnel zum Hub und Lab-Zugang. Inventar: WireGuard-IPAM, wireguard.md.

WireGuard Git-SoT: net/wireguard/: network.nix + peers/*.nix. Vorbereitung für Cutover; live noch wireguard-ui.
WireGuard IPAM: just wireguard-ipam: belegte Tunnel-IPs (172.30.0.0/24 und nächste freie Adressen.
Hub: VPS (vpn.groupdir.de): öffentlicher Endpoint, aggregiert Peers.
Site-Peer: z. B. lab-gateway: reicht Lab-LAN per extraAllowedIPs weiter.
AllowedIPs: WireGuard: welche Ziele über den Peer gehen / welche Quellen von ihm akzeptiert werden.

Komfort

Hilfsmittel

Shortcuts um die nativen Befehle herum; Details stehen in den jeweiligen Tool-Abschnitten.

just: Task-Runner; Rezepte in justfile. Kürzt z. B. tofu- und Colmena-Aufrufe ab, ersetzt sie nicht.