# HomeLab Ansible

Ansible is the control plane for HomeLab infrastructure changes.

## Contract

- The operator keeps passwords, SSH access and network reachability working.
- The agent changes infrastructure only through inventory, roles and playbooks in this directory.
- Manual server changes are allowed only for break-glass recovery; afterwards they must be captured in Ansible.
- Secrets stay outside git. Use `.env`, vault files or local prompt input, not committed variables.

## Layout

- `inventory/hosts.yml` — canonical host list and host-specific facts.
- `playbooks/` — entry points for tasks.
- `roles/` — reusable configuration units.

## Current Groups

- `ru-vps` — public VPS, JumpHost, qdevice, ZeroTier member.
- `pve_nodes` — Proxmox hosts: `cloud-pc`, `mini-pc`.
- `lxc_infra` — infrastructure LXC containers: `pbs`, `zt-cloud`, `zt-mini`.
- `vpn_openvpn` — OpenVPN transport hosts: `ru-vps`, `wg-mini`.
- `shell_hosts` — hosts with unified bash config: `ru-vps`, `cloud-pc`, `mini-pc`.
- `servers` — all managed hosts.

## First Checks

Install control-node dependencies locally:

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
ansible-galaxy collection install -r requirements.yml -p collections
```

Run from `ansible/`:

```bash
ansible-playbook playbooks/check.yml
```

For Proxmox API playbooks, create ignored `.env` from `.env.example` and load it:

```bash
cp .env.example .env
. ./.env
.venv/bin/ansible-playbook playbooks/pve-wg-mini.yml
```

Or bootstrap the token from `mini-pc` with sudo:

```bash
.venv/bin/ansible-playbook playbooks/bootstrap-pve-api-token.yml -K
```

OpenVPN transport:

```bash
.venv/bin/ansible-playbook playbooks/openvpn-vps-mini.yml -K
.venv/bin/ansible-playbook playbooks/openvpn-check.yml
```

Bootstrap the Ansible service account on shell hosts:

```bash
.venv/bin/ansible-playbook -i inventory/hosts.yml playbooks/bootstrap-ansible-user.yml -K
```

When a task needs privilege escalation:

```bash
ansible-playbook playbooks/<name>.yml -K
```

## Workflow

1. Describe the desired infrastructure change.
2. Add or update a role/playbook.
3. Run the smallest safe check or playbook.
4. Document non-obvious decisions in the project notes.