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

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