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

```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)