Nik Afiq 89d289addf feat: add periodic kill-switch reassertion timer
Found live, 2026-09-22: after fixing pia-killswitch.sh's FORWARD-jump
repositioning and getting one pia-gateway register attempt past the
safety check, the very next attempt - roughly an hour later, no
reboot, no UFW reload, no script content change in between - hit the
identical "FORWARD jump to kill-switch chain is not first" failure
again. This disproves the earlier assumption that kube-router/dockerd
reassert their own position-1 jumps only at boot/restart scale:
kube-router resyncs on ordinary Kubernetes API events, and this
cluster's CronJobs (ca-sync, porkbun-ddns, gitea-backup) each
create/delete a Pod every few minutes - plausible triggers for
kube-router's own reconciliation loop, and therefore plausible
triggers for this drift, recurring on a timescale of minutes.

The reposition logic itself (previous commit) is correct - it just
only ran on the existing triggers (boot, UFW reload, an
Ansible-detected script content change), none of which fired between
the two attempts.

Adds pia-killswitch-reassert.timer/.service: re-runs the already fully
idempotent pia-killswitch.sh every pia_healthcheck_interval_sec (same
cadence as the health check), giving it regular chances to run instead
of only sporadic ones. Deliberately separate from
pia-gateway-recover.timer and NOT gated by pia_auto_recovery_enabled -
this is the kill switch continuing to assert its own already-
established, narrowly-scoped state (source rule, table default,
FORWARD jump position), the same kind of thing it already does
unconditionally at boot and after a UFW reload, just on a schedule
too - not the higher-level automatic recovery/registration logic the
plan was deliberately cautious about running unattended.

Unblocked live in the meantime with a manual
`sudo systemctl restart pia-killswitch.service`.

Offline checks: yamllint, ansible-playbook --syntax-check, rendered
templates (Jinja2 + bash -n on the updated script), ansible-lint
(diffed against main - no new finding categories), full pia_gateway.py
test suite (94/94, unaffected by this change) all pass.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-22 19:08:28 +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.