DmitryHomeLab 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:
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
Workflow
- Describe the desired infrastructure change.
- Add or update a role/playbook.
- Run the smallest safe check or playbook.
- Document non-obvious decisions in the project notes.