¶ Ansible & IaC Runbook
¶ Summary
This page explains how infrastructure changes are automated. In simple terms: Ansible playbooks handle repeatable setup and maintenance so servers can be created, configured, and updated consistently.
Detailed repository roles and playbook groups are documented below.
Ansible is the main infrastructure-as-code layer for host bootstrap, VM lifecycle, Docker/Swarm setup, shared storage wiring, and Proxmox-specific configuration. The source of truth for these playbooks lives in the HomeLab repository.
¶ Repository Role
The HomeLab repo is used to:
- Bootstrap newly created VMs.
- Deploy and delete Swarm-host VMs.
- Configure Docker, shared volumes, and node roles.
- Install and configure Keepalived on Swarm managers.
- Manage CephFS mounts and Ceph-related integration points.
- Apply Proxmox-specific changes such as the MS-01 Thunderbolt/USB4 ring.
- Stage and manage security tooling.
¶ Primary Entry Points
The repo README and Ansible README document playbooks/new-vm.yml as the main end-to-end bootstrap playbook for a fresh VM, with core and docker bootstrap tasks chained together. The same docs also describe top-level playbooks for CephFS mount repair, security rollout, scanner staging, and site-wide orchestration.
The common pattern is:
cd ~/HomeLab/ansible
ansible-playbook -i hosts.ini playbooks/new-vm.yml --ask-vault-pass
Use the vault prompt when secrets are needed. For narrow maintenance, run the specific playbook rather than the full bootstrap.
¶ Key Playbook Groups
¶ Top-Level Playbooks
playbooks/new-vm.yml— full bootstrap for a new VM.playbooks/cephfs-mount.yml— detect, repair, and persist CephFS mounts.playbooks/security-bootstrap.yml— stage the security VM and supporting services.playbooks/security-agents.yml— install Wazuh/Falco agents where appropriate.playbooks/security-scanners.yml— stage scanner configuration.playbooks/site.yml— full security rollout.
The repository also includes helper scripts for installing Ansible, setting up GitHub SSH access, importing into Gitea, configuring NFS, and preparing Proxmox Backup Server workflows.
¶ Docker Playbooks
The Docker section of the repo handles Swarm provisioning and day-2 node configuration.
Important examples include:
provision-swarm.ymlsetup-shared-volumes.ymlcreate-lab-network.ymlinstall-ceph-rbd-plugin.ymlupdate-portainer.yml- GPU setup playbooks for Intel, AMD, and NVIDIA hosts
¶ Proxmox Playbooks
The Proxmox section includes host tuning and hardware-specific setup.
Important examples include:
configure-thunderbolt-ring.yml— configure the MS-01 ring.proxmox-ceph-tuning.ymlproxmox-iommu.ymlproxmox-update.ymlvendor-resetand passthrough-related playbooks
¶ VM Lifecycle Playbooks
The VM section covers actual VM creation and destruction workflows.
Important examples include:
clone-ubuntu-vm.ymlcreate-swarm-host-vms.ymldestroy-swarm-host-vms.ymlnew-vm.ymlteardown-ubuntu.yml
¶ How It Fits the Lab
In practice, Ansible is used for:
- Creating or cloning VMs in Proxmox.
- Bootstrapping those VMs with base OS, Docker, storage mounts, and lab-specific defaults.
- Wiring nodes into Docker Swarm and shared storage.
- Maintaining supporting infrastructure such as CephFS mounts and Proxmox node configuration.
- Supporting security and monitoring side systems.
¶ Security split
Security is intentionally split across Swarm and host-level automation:
| Tool | Managed by | Purpose |
|---|---|---|
| Wazuh | HomeLab Ansible | VM/endpoint inventory and vulnerability visibility. |
| Falco | HomeLab Ansible | Runtime behavior monitoring on Swarm nodes. |
| Greenbone | HomeLab Ansible | Scanner stack staged on the security VM. |
| Trivy | Docker Swarm | Scheduled repo/image scanning from Compose-Files/Security/trivy.yml. |
¶ Storage and host wiring
- CephFS mounts are repaired and persisted through
playbooks/cephfs-mount.yml. - Unraid NFS Docker volumes are created from HomeLab automation and consumed by Swarm stacks as external volumes.
- Docker nodes that run Redis need
vm.overcommit_memory=1applied at the host level. - Intel GPU nodes are labeled for Plex/Jellyfin hardware transcoding placement.
- The
Laboverlay network is created by the Docker network role. - Keepalived provides the Swarm manager VIP at
10.0.30.40.
¶ Keepalived role
The keepalived role installs the package, writes /etc/keepalived/keepalived.conf, starts the service, and enables it on boot. It runs on the Swarm manager inventory group during playbooks/docker/provision-swarm.yml.
| Setting | Value |
|---|---|
| VIP | 10.0.30.40 |
| VRRP instance | VI_1 |
| Router ID | 31 |
| Default interface | bond0, with playbook fallback to the default interface when needed |
| MASTER | First host in swarm_managers |
| BACKUP | Remaining Swarm managers |
¶ Before running a playbook
- Confirm the inventory host group matches the intended target.
- Check whether the playbook needs vault secrets.
- Prefer a narrow playbook for maintenance instead of
site.yml. - Read the task names before running anything destructive against Proxmox or Swarm hosts.
- After the run, check the affected service in Uptime Kuma or Docker Swarm before moving on.
¶ Useful command patterns
cd ~/HomeLab/ansible
ansible-playbook -i hosts.ini playbooks/cephfs-mount.yml --check
ansible-playbook -i hosts.ini playbooks/security-agents.yml --ask-vault-pass
ansible-playbook -i hosts.ini playbooks/new-vm.yml --ask-vault-pass
¶ Related Repositories
- HomeLab — infrastructure automation and host/bootstrap playbooks.
- Docker-Swarm — compose files, stack definitions, and backup-related container workflows.
- HiveMind — GitOps-style reconciler that watches Git and applies Swarm changes.
