Nik Afiq 87a9303cc3
Some checks failed
validate / lint (push) Failing after 2s
fix: address code review on pia-gateway auto-recovery controller
- Serialize every mutating command (recover, renew, register,
  rewrite-config, pause, resume, state-reset) on the shared lock,
  acquired BEFORE state is read rather than after: reading first and
  locking only around the write let a slower command silently clobber
  whatever a faster one wrote in between — in particular, an operator
  pause could be lost to an in-flight recovery pass that read state
  before the pause ran and only saved its own copy back afterwards.
- Fix emergency_close() to reposition its VLAN 50 DROP to the first
  effective FORWARD position when it exists but has been pushed down
  by something else (e.g. an out-of-band ufw reload) — a bare `-C`
  existence check said nothing about position.
- Tighten wait_for_verified()'s handshake freshness check from >= to >
  since_epoch: wg show and since_epoch are both whole seconds, so a
  handshake at exactly the same second as since_epoch is
  indistinguishable from a stale, pre-activation one and must not
  count as proof of a new one.
- Fix the Ansible config-validation task to fail on any exit code
  outside status's three documented health exits (0/1/2), not just on
  5 — verified live against the real program (no wg/ip/iptables on
  this dev machine reproduces the "nothing configured yet" first-run
  case; status correctly returns 1, and broken/missing config.json
  correctly returns 5 and is now caught).
- Correct the live fault-injection drill in the role README: port
  1337 is only the addKey registration API port, not the tunnel's own
  WireGuard UDP endpoint (derive that from `wg show pia-wg endpoints`
  instead), and make the packet-capture check direction-aware
  (`tcpdump -Q out`) so it can't conflate a real egress leak with
  VLAN 50's normal inbound arrival on enp1s0.

Added 6 tests (86 total, all passing): emergency-close repositioning
past a preceding ACCEPT, pause/resume blocking on an in-flight
lock holder and surviving into a subsequent recovery pass, and the
handshake boundary at exactly/one-second-either-side of since_epoch.

yamllint, ansible-playbook --syntax-check, and ansible-lint (diffed
against main — no new finding categories) all pass. No live changes;
nothing pushed to main.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-22 15:51:02 +09:00
..

Ansible

This directory contains host-level automation. It bootstraps machines, installs K3s, prepares storage, and manages services that intentionally run outside the cluster.

Inventory

inventory.yaml defines four groups:

Group Host Purpose
k3s_server minisforum K3s server at 10.10.40.53
k3s_agents debian K3s agent and NFS storage at 10.10.40.20
mac_mini mac-mini Docker/Ollama host at 10.10.40.30
gpu_workstation gpu-node K3s agent with NVIDIA GPU passthrough at 10.10.40.12 (spot-tainted)

All hosts use the nik user and the SSH key configured in inventory.yaml.

Collections

Install the third-party collections this repo's roles depend on before running any playbook:

ansible-galaxy collection install -r ansible/requirements.yml

(community.general, ansible.posix, community.docker.)

Common Playbooks

ansible-playbook -i ansible/inventory.yaml ansible/playbooks/bootstrap-minisforum.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-k3s.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-nfs-debian.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/join-debian-agent.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-gpu-node.yaml -K

Additional services:

export GITEA_RUNNER_TOKEN=...
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-monitoring.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-gitea-runner.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-glances-debian.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-ollama.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/deploy-watch-party.yaml
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/wireguard.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/homeassistant.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/pia-gateway.yaml -K
ansible-playbook -i ansible/inventory.yaml ansible/playbooks/vlan50-parent.yaml -K

Roles

Role Responsibility
common Packages, user setup, firewall, base data directories
docker Docker CE install (Debian and Ubuntu); depended on by homeassistant
nvidia NVIDIA driver, CUDA toolkit, and containerd/Docker GPU runtime config
k3s-server K3s server install, kubeconfig fetch, Helm install, primary node label
k3s-agent K3s agent join and storage/GPU node label
nfs-server Export /mnt/storage from Debian to the K3s server
monitoring Host directories and ownership for Prometheus/Loki
gitea-runner Gitea Actions runner systemd service
glances Host-level Glances service
ollama Ollama service on the Mac Mini and GPU node (branches on OS)
watch-party Watch Party Docker Compose deployment on the Mac Mini
wireguard WireGuard server configuration (inbound home-VPN access — phone/Mac clients)
pia-gateway Minisforum's PIA WireGuard egress gateway for VPN VLAN 50 (policy routing, kill switch, health checks) — see its own README
vlan50-parent nik-debian's tagged VLAN 50 parent interface (enp1s0.50) for Multus — see its own README
homeassistant Standalone Home Assistant deployment (Docker Compose + systemd on minisforum) — this is the only thing serving ha.home.arpa, not legacy/dead

Notes

  • K3s version is defined in three places and must be kept in sync: roles/k3s-server/defaults/main.yaml, roles/k3s-agent/defaults/main.yaml, and the override in host_vars/gpu-node.yaml.
  • setup-gitea-runner.yaml reads GITEA_RUNNER_TOKEN from the local environment.
  • The K3s role disables bundled Traefik because Traefik is managed by Argo CD.
  • The Debian storage role exports /mnt/storage; several Kubernetes manifests mount that export directly.
  • Keep host automation idempotent where practical. These playbooks are meant to be rerunnable during rebuilds.
  • To see the real K3s join token (needed once, to populate vault_k3s_node_token), pass -e k3s_show_token=true to setup-k3s.yaml; it's suppressed by default. Same pattern for WireGuard client configs via -e wireguard_show_client_configs=true on wireguard.yaml.