# 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 ```bash # Run a specific playbook ansible-playbook ansible/automation/playbooks/.yml # Run for specific host ansible-playbook .yml --limit atlantis # Check mode (dry run) ansible-playbook .yml --check # Verbose output ansible-playbook .yml -v ``` --- ## Backup Playbooks ### backup_configs.yml Backs up configuration files from all hosts. ```bash # 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. ```bash ansible-playbook ansible/automation/playbooks/backup_databases.yml ``` ### backup_verification.yml Verifies backup integrity. ```bash ansible-playbook ansible/automation/playbooks/backup_verification.yml ``` --- ## Container Management ### container_update_orchestrator.yml Updates all containers across hosts. ```bash # 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. ```bash # Get logs for specific service ansible-playbook ansible/automation/playbooks/container_logs.yml -e "service=prometheus" ``` ### container_dependency_map.yml Maps container dependencies. ```bash ansible-playbook ansible/automation/playbooks/container_dependency_map.yml ``` --- ## Health & Monitoring ### health_check.yml Runs comprehensive health check. ```bash 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. ```bash ansible-playbook ansible/automation/playbooks/alert_check.yml ``` ### disk_usage_report.yml Generates disk usage report. ```bash ansible-playbook ansible/automation/playbooks/disk_usage_report.yml ``` --- ## Security ### security_audit.yml Runs security audit. ```bash 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. ```bash ansible-playbook ansible/automation/playbooks/security_updates.yml ``` --- ## System Maintenance ### prune_containers.yml Cleans up Docker resources. ```bash # 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. ```bash ansible-playbook ansible/automation/playbooks/log_rotation.yml ``` --- ## Deployment Playbooks ### deploy_atlantis.yml Deploys all services to Atlantis. ```bash ansible-playbook ansible/homelab/playbooks/deploy_atlantis.yml ``` ### deploy_calypso.yml Deploys all services to Calypso. ```bash ansible-playbook ansible/homelab/playbooks/deploy_calypso.yml ``` ### deploy_concord_nuc.yml Deploys all services to Concord NUC. ```bash ansible-playbook ansible/homelab/playbooks/deploy_concord_nuc.yml ``` ### deploy_homelab_vm.yml Deploys all services to Homelab VM. ```bash ansible-playbook ansible/homelab/playbooks/deploy_homelab_vm.yml ``` --- ## Network Playbooks ### tailscale_management.yml Manages Tailscale nodes. ```bash # 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. ```bash ansible-playbook ansible/automation/playbooks/network_connectivity.yml ``` --- ## Disaster Recovery ### disaster_recovery_orchestrator.yml Orchestrates disaster recovery. ```bash # 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. ```bash ansible-playbook ansible/automation/playbooks/disaster_recovery_test.yml ``` --- ## Certificate Management ### certificate_renewal.yml Checks and renews SSL certificates. ```bash # 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. ```bash ansible-playbook ansible/automation/playbooks/restart_service.yml -e "service=prometheus" ``` ### service_status.yml Gets service status. ```bash ansible-playbook ansible/automation/playbooks/service_status.yml -e "service=nginx" ``` --- ## Inventory ### Listing Hosts ```bash 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 ```bash # 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 ```bash # Test connectivity ansible all -m ping # Debug connection ansible-playbook .yml -vvv ``` ### Permission Issues ```bash # Use sudo ansible-playbook .yml --ask-become-pass ``` --- ## Links - [Ansible Documentation](https://docs.ansible.com/) - [GitHub Repository](https://github.com/homelab)