homelab-ddi

Centralized DNS / DHCP / IPAM stack for the strscrm homelab. Replaces Technitium DNS and isc-dhcp-server.

Stack

Layer	Component	HA
IPAM / management	NetBox 4.6 + plugins (netbox_dns, netbox_dns_bridge, netbox_kea, netbox_healthcheck_plugin)	Single VM (PBS-backed)
Authoritative + recursive DNS	BIND 9.20 (catalog zones, RPZ blocklists, NetBox webhook receiver)	Active/active pair
DHCP	Kea 3.0.3 LTS with HA hook (hot-standby), memfile per node	Active/standby pair
Observability	Prometheus + Alertmanager + Grafana 11.4 + Loki + blackbox + Alloy + Stork agents	Single VM (Uptime Kuma probes the probe)
CI/CD	Forgejo Actions on megatron runner	n/a
Storage	Proxmox ceph rbd pool	shared across pve1/pve2/pve3

See /home/gosseljl/src/infra/CLAUDE.md (one level up from this repo) for the full design contract.

Layout

inventory.toml    # SOURCE OF TRUTH for hosts, IPs, MACs, subnets, reservations
docs/             # design docs, ADRs, runbooks, archived materials
terraform/        # Proxmox VM provisioning (bpg/proxmox provider)
ansible/          # roles + playbooks for in-VM config
netbox/           # plugins + seed data (seed-data/objects.yaml is part-generated from inventory.toml)
scripts/          # one-shot helpers (template builder, etc.)
tools/            # operator tooling (render-inventory.py, refresh-dashboards.sh)
tests/            # drift checkers + e2e tests
.forgejo/         # CI workflows

Quickstart

1. Install prereqs: terraform (or tofu), ansible, sops, age, uvx, pre-commit.
2. cp .env.example .env and fill in tokens.
3. direnv allow (or source .env manually).
4. pre-commit install — auto-renders inventory.toml on every commit and runs yamllint.
5. Phase 1: see docs/runbooks/phase-1-evidence.md for the deployed acceptance log.

Phases

Phase	Scope	Status
1	NetBox + first BIND node	Complete
2	Second BIND node + RPZ blocklists + catalog zones + NetBox webhook	Complete
3	Kea HA pair + netbox_kea plugin (test subnet only)	Complete
3.5	Forgejo Actions CI/CD + drift detection	Complete
3.75	Observability stack on monitor-01	Complete
3.76	Stork agent replaces kea-exporter + bind_exporter; Alloy replaces Promtail	Complete
3.77	Grafana dashboards: curated OSS imports replace hand-built set	Complete
3.78	NetBox object-count textfile collector + Infinity datasource	Complete
4	UniFi adoption + per-VLAN cutover on Kea	In progress (VLAN 101, 103 done; 102, 104 pending)
5	Decommission Technitium + isc-dhcp-server	Not started

Operator notes

• Internal DNS suffix: infra.strscrm.io (split-horizon on an owned domain).
• Lab management VLAN: tag 102, subnet 10.0.2.0/24, gateway 10.0.2.254, on vmbr0.
• Test subnet: VLAN 199, 10.0.99.0/24, on vmbr1 (carries the VLAN over the Cisco PVE-STOR trunk).
• Storage: Proxmox ceph rbd pool (shared across pve1, pve2, pve3).
• Backups: Proxmox Backup Server (pbs storage).
• Secrets: sops + age (see docs/secrets.md).
• External monitoring of monitor-01: Uptime Kuma probes http://monitor-01:9090/-/healthy so a dead Prometheus is detected from outside the stack.

Common tasks

• Add a host or reservation, or change an IP: edit inventory.toml at the repo root, then python3 tools/render-inventory.py to update netbox/seed-data/objects.yaml and ansible/roles/kea/defaults/main.yml. Commit both the TOML and the rendered YAML; CI rejects the push otherwise.
• Refresh Grafana dashboards from upstream: tools/refresh-dashboards.sh, review the diff, commit, push, let CI deploy.
• Cut a new VLAN over to Kea: set kea_active = true on the network in inventory.toml, render, push, then flip the relay address on the upstream router (ip dhcp relay address on Cisco NX-OS — not ip helper-address).
• Add a new DNS zone: create the zone in NetBox; the catalog-zone consumer on the BIND nodes auto-loads it within seconds.
• Find Proxmox guests not yet in DNS: python3 scripts/discover-undns-vms.py (read-only diff against NetBox).
• Watch live Kea logs: ssh debian@10.0.2.232 'sudo journalctl -fu isc-kea-dhcp4-server' (or .233).