Sanitized mirror from private repository - 2026-03-29 13:33:25 UTC

2026-03-29 13:33:25 +00:00
commit 75d4f4e02b
1280 changed files with 331190 additions and 0 deletions
--- a/docs/automation/ansible-playbooks.md
+++ b/docs/automation/ansible-playbooks.md
@@ -0,0 +1,401 @@
+# 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/<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.
+
+```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 <playbook>.yml -vvv
+```
+
+### Permission Issues
+
+```bash
+# Use sudo
+ansible-playbook <playbook>.yml --ask-become-pass
+```
+
+---
+
+## Links
+
+- [Ansible Documentation](https://docs.ansible.com/)
+- [GitHub Repository](https://github.com/homelab)