Dmitry
83 lines
2.2 KiB
Markdown
83 lines
2.2 KiB
Markdown
# 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.
|