# 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:

```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`.