Nik Afiq
5a00f5767b
Stage 4 of REFACTOR_PLAN.md. - Merge ansible/ansible.cfg into root ansible.cfg (single source of truth); the dual-config setup silently broke documented commands and lost host_key_checking=False when run from the ansible/ directory. - Add ansible/requirements.yml pinning community.general, ansible.posix, community.docker -- previously undocumented deps of the glances/watch-party roles that would fail a fresh bootstrap. - Align K3s version to v1.32.4+k3s1 across roles/k3s-server, roles/k3s-agent, and host_vars/gpu-node.yaml defaults (was skewed: .2 vs .4). This only changes what a *future* provision installs -- minisforum/debian are still live on v1.32.2+k3s1 until separately upgraded. - Fix kubeconfig fetch/replace path mismatch in k3s-server role: the `fetch` task (flat: true) writes to ~/.kube/config, but `replace` was targeting a /tmp/k3s-minisforum.yaml nothing creates -- would break a fresh rebuild. - gitea-runner: only remove /run/docker.sock when it's actually a directory (task name implied a check that wasn't there); tighten registration-token systemd unit from 0644 to 0600. - nvidia: stop unconditionally reporting `changed` (and restarting Docker) on every run for an idempotent runtime-configure command. - Gate the K3s join-token debug print and WireGuard client-config/QR display behind opt-in vars (k3s_show_token, wireguard_show_client_configs), default off -- both were printing real secrets to console on every run. - Parameterize the docker role for Debian and Ubuntu; homeassistant now depends on it (meta/main.yaml) instead of duplicating a Debian-only Docker install inline. - FQCN cleanup across wireguard, homeassistant, and ollama roles/handlers (bare module names -> ansible.builtin.*/community.general.*/ansible.posix.*), plus a few ansible-lint name-casing/idiom fixes. Handler renames verified against their `notify:` call sites so notifications still fire. - Update ansible/README.md and root README.md: add gpu-node/gpu_workstation (4th host, previously undocumented), docker/nvidia roles, setup-gpu-node.yaml, homeassistant.yaml, requirements.yml install step; correct the "Legacy" homeassistant label (it's the only thing serving ha.home.arpa); correct the Gitea ingress/backup-storage doc-drift; flag the Grafana/Loki static-PV binding drift discovered via live cluster check. Verified: all playbooks pass `ansible-playbook --syntax-check`, yamllint clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
88 lines
3.9 KiB
Markdown
88 lines
3.9 KiB
Markdown
# 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 `192.168.7.77` |
|
|
| `k3s_agents` | `debian` | K3s agent and NFS storage at `192.168.7.183` |
|
|
| `mac_mini` | `mac-mini` | Docker/Ollama host at `192.168.7.96` |
|
|
| `gpu_workstation` | `gpu-node` | K3s agent with NVIDIA GPU passthrough at `192.168.7.98` (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:
|
|
|
|
```bash
|
|
ansible-galaxy collection install -r ansible/requirements.yml
|
|
```
|
|
|
|
(`community.general`, `ansible.posix`, `community.docker`.)
|
|
|
|
## Common Playbooks
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
## 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 |
|
|
| `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`.
|