Archive Legacy Setup And Add Ansible Control Plane

2026-07-08 12:47:37 +03:00
parent 841d56380b
commit 4bafa7d09e
203 changed files with 1663 additions and 11 deletions
@@ -0,0 +1,82 @@
+# 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.