ansible/docs/reference/architecture.md

Architecture Overview

Technical architecture and design of the Ansible infrastructure management system.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Control Machine                         |
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Ansible    │  │   Makefile   │  │    Vault     │       │
│  │   Engine     │  │  Automation  │  │   Secrets    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────┬───────────────────────────────────────┘
                      │ SSH + Tailscale VPN
    ┌─────────────────┴──────────────────────────────┐
    │                                                │
┌───▼────────┐  ┌──────────────┐  ┌─────────────────▼────────┐
│    Dev     │  │   Service    │  │      Infrastructure      │
│  Machines  │  │     VMs      │  │         VMs              │
├────────────┤  ├──────────────┤  ├──────────────────────────┤
│ • dev01    │  │ • giteaVM    │  │ • Proxmox Controller     │
│ • bottom   │  │ • portainerVM│  │ • Future VMs             │
│ • desktop  │  │ • homepageVM │  │                          │
└────────────┘  └──────────────┘  └──────────────────────────┘

Network Topology

Physical Network

• LAN: 192.168.1.0/24 (typical home/office network)
• Proxmox Host: Hypervisor for VM management
• Physical Machines: Direct network access

Tailscale Overlay Network

• Mesh VPN: Secure peer-to-peer connections
• 100.x.x.x: Tailscale IP range
• Zero-config: Automatic NAT traversal
• End-to-end encryption: WireGuard protocol

Host Groups

Development (dev)

Purpose: Developer workstations and environments

• Hosts: dev01, bottom, debianDesktopVM
• OS: Debian/Ubuntu
• Roles: Full development stack

Services

Purpose: Self-hosted services and applications

Gitea (gitea)

• Host: giteaVM
• OS: Alpine Linux (lightweight)
• Service: Git repository hosting

Portainer (portainer)

• Host: portainerVM
• OS: Alpine Linux
• Service: Container management UI

Homepage (homepage)

• Host: homepageVM
• OS: Debian
• Service: Service dashboard

Infrastructure (ansible)

Purpose: Ansible control and automation

• Host: Ansible controller VM
• OS: Ubuntu Server
• Service: Infrastructure automation

Local (local)

Purpose: Local machine management

• Host: localhost
• Connection: Local (no SSH)

Playbook Architecture

Core Playbooks

playbooks/development.yml     # Development environment setup
├── roles/maintenance     # System updates
├── roles/base           # Core packages
├── roles/ssh            # SSH hardening
├── roles/user           # User management
├── roles/development    # Dev tools
├── roles/shell          # Shell config
├── roles/docker         # Container platform
├── roles/applications   # Desktop apps
├── roles/snap           # Snap packages
├── roles/tailscale      # VPN setup
├── roles/monitoring     # Monitoring tools

playbooks/local.yml          # Local machine
├── roles/base
├── roles/shell
├── roles/development
└── roles/tailscale

playbooks/maintenance.yml    # System maintenance
└── roles/maintenance

playbooks/tailscale.yml       # VPN deployment
└── roles/tailscale

playbooks/infrastructure/proxmox-vm.yml   # KVM VM provisioning (controller VM, etc.)
└── roles/proxmox_vm

playbooks/app/site.yml                    # Proxmox app stack (LXC-first)
├── playbooks/app/provision_vms.yml       # Proxmox API provisioning (LXC/KVM)
└── playbooks/app/configure_app.yml       # Guest OS + app configuration over SSH

Role Dependencies

base
├── Required by: all other roles
├── Provides: core utilities, security tools
└── Dependencies: none

ssh
├── Required by: secure access
├── Provides: hardened SSH, firewall
└── Dependencies: base

user
├── Required by: system access
├── Provides: user accounts, sudo
└── Dependencies: base

development
├── Required by: coding tasks
├── Provides: git, nodejs, python
└── Dependencies: base

docker
├── Required by: containerization
├── Provides: Docker CE, compose
└── Dependencies: base

tailscale
├── Required by: secure networking
├── Provides: mesh VPN
└── Dependencies: base

Data Flow

Configuration Management

1. Variables → inventories/production/group_vars/all/main.yml
2. Secrets → inventories/production/group_vars/all/vault.yml (encrypted)
3. Host Config → inventories/production/host_vars/<hostname>.yml
4. Role Defaults → roles/*/defaults/main.yml
5. Tasks → roles/*/tasks/main.yml
6. Templates → roles//templates/.j2
7. Handlers → roles/*/handlers/main.yml

Execution Flow

make command
    ↓
Makefile target
    ↓
ansible-playbook
    ↓
Inventory + Variables
    ↓
Role execution
    ↓
Task processing
    ↓
Handler notification
    ↓
Result reporting

Security Architecture

Defense in Depth

Network Layer

• Tailscale VPN: Encrypted mesh network
• UFW Firewall: Default deny, explicit allow
• SSH Hardening: Key-only, rate limiting

Application Layer

• Fail2ban: Intrusion prevention
• Package signing: GPG verification
• Service isolation: Docker containers

Data Layer

• Ansible Vault: Encrypted secrets
• SSH Keys: Ed25519 cryptography

Access Control

User → SSH Key → Jump Host → Tailscale → Target Host
         ↓           ↓           ↓           ↓
      Ed25519    Bastion    WireGuard    Firewall
                            Encryption    Rules

Storage Architecture

Configuration Storage

/etc/              # System configuration
/opt/              # Application data
/usr/local/        # Custom scripts
/var/log/          # Logs and audit trails

Monitoring Architecture

System Monitoring

• btop/htop: Process monitoring
• iotop: I/O monitoring
• nethogs: Network per-process
• Custom dashboards: sysinfo, netinfo

Log Management

• logwatch: Daily summaries
• journald: System logs
• fail2ban: Security logs

Scalability Considerations

Horizontal Scaling

• Add hosts to inventory groups
• Parallel execution with ansible forks
• Role reusability across environments

Vertical Scaling

• Proxmox VM resource adjustment
• Docker resource limits
• Service-specific tuning

Technology Stack

Core Technologies

• Ansible: 2.9+ (Configuration management)
• Python: 3.x (Ansible runtime)
• Jinja2: Templating engine
• YAML: Configuration format

Target Platforms

• Debian: 11+ (Bullseye, Bookworm)
• Ubuntu: 20.04+ (Focal, Jammy, Noble)
• Alpine: 3.x (Lightweight containers)

Service Technologies

• Docker: Container runtime
• Tailscale: Mesh VPN
• SystemD: Service management
• UFW: Firewall management

Best Practices

Code Organization

1. One role = one responsibility
2. Idempotent tasks
3. Proper handler usage
4. Template for configuration
5. Defaults for flexibility

Security

1. Vault for all secrets
2. Least privilege principle
3. Regular updates
4. Audit logging
5. Network segmentation

Operations

1. Test in check mode
2. Use tags for selective runs
3. Document changes
4. Version control everything
5. Monitor and alert