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.

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.

Install control-node dependencies locally:

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

Run from ansible/:

ansible-playbook playbooks/check.yml

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

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

Or bootstrap the token from mini-pc with sudo:

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

OpenVPN transport:

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

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

When a task needs privilege escalation:

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