From 67d5de3eb8978320038378011a01b83428ac0009 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= Date: Wed, 4 Feb 2026 21:45:16 +0100 Subject: [PATCH] docs: update CLAUDE.md for DNS automation - Add /modules/ and /lib/ to directory structure - Document homelab.dns options and zone auto-generation - Update "Adding a New Host" workflow (no manual zone editing) - Expand DNS Architecture section with auto-generation details Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 45 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c04fa25..465cb9e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -101,17 +101,21 @@ This ensures documentation matches the exact nixpkgs version (currently NixOS 25 ### Directory Structure -- `/flake.nix` - Central flake defining all 16 NixOS configurations +- `/flake.nix` - Central flake defining all NixOS configurations - `/hosts//` - Per-host configurations - `default.nix` - Entry point, imports configuration.nix and services - `configuration.nix` - Host-specific settings (networking, hardware, users) - `/system/` - Shared system-level configurations applied to ALL hosts - Core modules: nix.nix, sshd.nix, sops.nix, acme.nix, autoupgrade.nix - Monitoring: node-exporter and promtail on every host +- `/modules/` - Custom NixOS modules + - `homelab/` - Homelab-specific options (DNS automation, etc.) +- `/lib/` - Nix library functions + - `dns-zone.nix` - DNS zone generation functions - `/services/` - Reusable service modules, selectively imported by hosts - `home-assistant/` - Home automation stack - `monitoring/` - Observability stack (Prometheus, Grafana, Loki, Tempo) - - `ns/` - DNS services (authoritative, resolver) + - `ns/` - DNS services (authoritative, resolver, zone generation) - `http-proxy/`, `ca/`, `postgres/`, `nats/`, `jellyfin/`, etc. - `/secrets/` - SOPS-encrypted secrets with age encryption - `/common/` - Shared configurations (e.g., VM guest agent) @@ -137,6 +141,7 @@ All hosts automatically get: - Daily auto-upgrades with auto-reboot - Prometheus node-exporter + Promtail (logs to monitoring01) - Custom root CA trust +- DNS zone auto-registration via `homelab.dns` options ### Active Hosts @@ -279,14 +284,17 @@ This means: 1. Create `/hosts//` directory 2. Copy structure from `template1` or similar host 3. Add host entry to `flake.nix` nixosConfigurations -4. Add hostname to dns zone files. Merge to master. Run auto-upgrade on dns servers. -5. User clones template host -6. User runs `prepare-host.sh` on new host, this deletes files which should be regenerated, like ssh host keys, machine-id etc. It also creates a new age key, and prints the public key -7. This key is then added to `.sops.yaml` -8. Create `/secrets//` if needed -9. Configure networking (static IP, DNS servers) +4. Configure networking in `configuration.nix` (static IP via `systemd.network.networks`, DNS servers) +5. (Optional) Add `homelab.dns.cnames` if the host needs CNAME aliases +6. User clones template host +7. User runs `prepare-host.sh` on new host, this deletes files which should be regenerated, like ssh host keys, machine-id etc. It also creates a new age key, and prints the public key +8. This key is then added to `.sops.yaml` +9. Create `/secrets//` if needed 10. Commit changes, and merge to master. 11. Deploy by running `nixos-rebuild boot --flake URL#` on the host. +12. Run auto-upgrade on DNS servers (ns1, ns2) to pick up the new host's DNS entry + +**Note:** DNS A records are auto-generated from the host's `systemd.network.networks` static IP configuration. No manual zone file editing is required. ### Important Patterns @@ -313,5 +321,24 @@ All hosts ship metrics and logs to `monitoring01`: - `ns1` (10.69.13.5) - Primary authoritative DNS + resolver - `ns2` (10.69.13.6) - Secondary authoritative DNS (AXFR from ns1) -- Zone files managed in `/services/ns/` - All hosts point to ns1/ns2 for DNS resolution + +**Zone Auto-Generation:** + +DNS zone entries are automatically generated from host configurations: + +- **Flake-managed hosts**: A records extracted from `systemd.network.networks` static IPs +- **CNAMEs**: Defined via `homelab.dns.cnames` option in host configs +- **External hosts**: Non-flake hosts defined in `/services/ns/external-hosts.nix` +- **Serial number**: Uses `self.sourceInfo.lastModified` (git commit timestamp) + +Host DNS options (`homelab.dns.*`): +- `enable` (default: `true`) - Include host in DNS zone generation +- `cnames` (default: `[]`) - List of CNAME aliases pointing to this host + +Hosts are automatically excluded from DNS if: +- `homelab.dns.enable = false` (e.g., template hosts) +- No static IP configured (e.g., DHCP-only hosts) +- Network interface is a VPN/tunnel (wg*, tun*, tap*) + +To add DNS entries for non-NixOS hosts, edit `/services/ns/external-hosts.nix`.