homelab-optimized/docs/automation/ansible-playbooks.md

Ansible Playbook Documentation

Automation playbooks for homelab management

---

Overview

The homelab uses Ansible for automation, configuration management, and orchestration. This document describes available playbooks and how to use them.

---

Directory Structure

ansible/
├── automation/               # Main automation playbooks
│   ├── playbooks/
│   │   ├── backup_*.yml      # Backup operations
│   │   ├── container_*.yml  # Container management
│   │   ├── health_*.yml      # Health checks
│   │   ├── security_*.yml   # Security operations
│   │   └── update_*.yml      # Update operations
│   └── host_vars/            # Host-specific variables
├── homelab/                  # Deployment playbooks
│   ├── playbooks/
│   │   └── deploy_*.yml     # Host deployment
│   ├── roles/                # Ansible roles
│   └── host_vars/           # Host configurations
└── inventory.yml            # Inventory file

---

Quick Reference

Common Commands

# Run a specific playbook
ansible-playbook ansible/automation/playbooks/<playbook>.yml

# Run for specific host
ansible-playbook <playbook>.yml --limit atlantis

# Check mode (dry run)
ansible-playbook <playbook>.yml --check

# Verbose output
ansible-playbook <playbook>.yml -v

---

Backup Playbooks

backup_configs.yml

Backs up configuration files from all hosts.

# Run full backup
ansible-playbook ansible/automation/playbooks/backup_configs.yml

# Backup specific host
ansible-playbook ansible/automation/playbooks/backup_configs.yml --limit atlantis

Backs up:

• Docker compose files
• NPM configurations
• Authentik configs
• Service configurations

backup_databases.yml

Backs up all database containers.

ansible-playbook ansible/automation/playbooks/backup_databases.yml

backup_verification.yml

Verifies backup integrity.

ansible-playbook ansible/automation/playbooks/backup_verification.yml

---

Container Management

container_update_orchestrator.yml

Updates all containers across hosts.

# Dry run
ansible-playbook ansible/automation/playbooks/container_update_orchestrator.yml --check

# Execute
ansible-playbook ansible/automation/playbooks/container_update_orchestrator.yml

container_logs.yml

Retrieves logs from containers.

# Get logs for specific service
ansible-playbook ansible/automation/playbooks/container_logs.yml -e "service=prometheus"

container_dependency_map.yml

Maps container dependencies.

ansible-playbook ansible/automation/playbooks/container_dependency_map.yml

---

Health & Monitoring

health_check.yml

Runs comprehensive health check.

ansible-playbook ansible/automation/playbooks/health_check.yml

# Output JSON
ansible-playbook ansible/automation/playbooks/health_check.yml -e "output_format=json"

Checks:

• Container status
• Resource usage
• Service availability
• Disk space

alert_check.yml

Checks alert status.

ansible-playbook ansible/automation/playbooks/alert_check.yml

disk_usage_report.yml

Generates disk usage report.

ansible-playbook ansible/automation/playbooks/disk_usage_report.yml

---

Security

security_audit.yml

Runs security audit.

ansible-playbook ansible/automation/playbooks/security_audit.yml

# Full audit with scanning
ansible-playbook ansible/automation/playbooks/security_audit.yml -e "full_scan=true"

security_updates.yml

Applies security updates.

ansible-playbook ansible/automation/playbooks/security_updates.yml

---

System Maintenance

prune_containers.yml

Cleans up Docker resources.

# Preview
ansible-playbook ansible/automation/playbooks/prune_containers.yml --check

# Execute
ansible-playbook ansible/automation/playbooks/prune_containers.yml

log_rotation.yml

Configures log rotation.

ansible-playbook ansible/automation/playbooks/log_rotation.yml

---

Deployment Playbooks

deploy_atlantis.yml

Deploys all services to Atlantis.

ansible-playbook ansible/homelab/playbooks/deploy_atlantis.yml

deploy_calypso.yml

Deploys all services to Calypso.

ansible-playbook ansible/homelab/playbooks/deploy_calypso.yml

deploy_concord_nuc.yml

Deploys all services to Concord NUC.

ansible-playbook ansible/homelab/playbooks/deploy_concord_nuc.yml

deploy_homelab_vm.yml

Deploys all services to Homelab VM.

ansible-playbook ansible/homelab/playbooks/deploy_homelab_vm.yml

---

Network Playbooks

tailscale_management.yml

Manages Tailscale nodes.

# List nodes
ansible-playbook ansible/automation/playbooks/tailscale_management.yml -e "action=list"

# Add node
ansible-playbook ansible/automation/playbooks/tailscale_management.yml -e "action=add"

network_connectivity.yml

Tests network connectivity.

ansible-playbook ansible/automation/playbooks/network_connectivity.yml

---

Disaster Recovery

disaster_recovery_orchestrator.yml

Orchestrates disaster recovery.

# Plan only
ansible-playbook ansible/automation/playbooks/disaster_recovery_orchestrator.yml -e "mode=plan"

# Execute recovery
ansible-playbook ansible/automation/playbooks/disaster_recovery_orchestrator.yml -e "mode=execute"

disaster_recovery_test.yml

Tests disaster recovery procedures.

ansible-playbook ansible/automation/playbooks/disaster_recovery_test.yml

---

Certificate Management

certificate_renewal.yml

Checks and renews SSL certificates.

# Check only
ansible-playbook ansible/automation/playbooks/certificate_renewal.yml --check

# Force renewal
ansible-playbook ansible/automation/playbooks/certificate_renewal.yml -e "force_renewal=true"

---

Service Management

restart_service.yml

Restarts a specific service.

ansible-playbook ansible/automation/playbooks/restart_service.yml -e "service=prometheus"

service_status.yml

Gets service status.

ansible-playbook ansible/automation/playbooks/service_status.yml -e "service=nginx"

---

Inventory

Listing Hosts

ansible-playbook -i ansible/inventory.yml --list-hosts all

# Or use ansible-inventory
ansible-inventory -i ansible/inventory.yml --list

Host Groups

Group	Description
synology	All Synology NAS
vms	All virtual machines
nuc	Intel NUC
edge	Edge devices

---

Variables

Common Variables

# Specify environment
-e "env=production"

# Target specific host
-e "target_host=atlantis"

# Output format
-e "output_format=json"

Host Variables

Defined in host_vars/:

• atlantis.yml
• calypso.yml
• homelab.yml
• concord_nuc.yml

---

Troubleshooting

Connection Issues

# Test connectivity
ansible all -m ping

# Debug connection
ansible-playbook <playbook>.yml -vvv

Permission Issues

# Use sudo
ansible-playbook <playbook>.yml --ask-become-pass

---

Links

• Ansible Documentation
• GitHub Repository