infra-automation/README.md

# Ansible Infrastructure Automation

Enterprise-grade Ansible infrastructure with security-first principles, modularity, and scalability.

## Quick Start

```bash
# Test connectivity with SSH config inventory
ansible all -i plugins/inventory/ssh_config_inventory.py -m ping

# Test connectivity with Libvirt dynamic inventory
ansible running_vms -i plugins/inventory/libvirt_kvm.py -m ping

# Use static development inventory
ansible all -i inventories/development/hosts.yml -m ping

# Run a playbook
ansible-playbook -i inventories/development/hosts.yml site.yml
```

## Project Structure

```
.
├── README.md                       # This file
├── CLAUDE.md                       # Development guidelines and standards
├── ansible.cfg                     # Ansible configuration
├── site.yml                        # Master playbook
│
├── inventories/                    # Inventory configurations
│   ├── production/                 # Production (dynamic only)
│   ├── staging/                    # Staging (dynamic only)
│   └── development/                # Development environment
│       ├── hosts.yml               # Static inventory
│       ├── libvirt_kvm.yml         # Libvirt config
│       └── group_vars/             # Group variables
│           ├── all.yml
│           ├── kvm_guests.yml
│           └── hypervisors.yml
│
├── plugins/                        # Custom plugins
│   └── inventory/                  # Dynamic inventory scripts
│       ├── ssh_config_inventory.py # SSH config parser
│       └── libvirt_kvm.py          # Libvirt/KVM discovery
│
├── roles/                          # Ansible roles
├── playbooks/                      # Playbooks
├── collections/                    # Ansible collections
│
├── docs/                           # Documentation
│   ├── inventory.md                # Inventory documentation
│   └── [other docs]
│
└── cheatsheets/                    # Quick reference guides
    └── inventory.md                # Inventory cheatsheet
```

## Infrastructure Overview

### Current Environment

| Component | Type | Description |
|-----------|------|-------------|
| **odin** | External VPS | Mail server (Debian 13) |
| **grokbox** | Hypervisor | KVM/libvirt host (physical) |
| **pihole** | VM Guest | DNS/DHCP server (via grokbox) |
| **mymx** | VM Guest | Mail server (via grokbox) |
| **derp** | VM Guest | Development VM (via grokbox) |
| **seed** | VM Guest | Discovery pending |

### Network Architecture

```
Internet
    │
    ├─── odin (65.108.217.156) ─────────── External VPS
    │
    └─── grokbox (grok.home.serneels.xyz)
             │
             └─── virbr0 (192.168.122.0/24) ── NAT Network
                      │
                      ├─── pihole (192.168.122.12)
                      ├─── mymx (192.168.122.119)
                      ├─── derp (192.168.122.99)
                      └─── seed (192.168.129.1)
```

## Available Inventory Solutions

### 1. SSH Config Parser (Dynamic)
**Best for:** Quick discovery from existing SSH configuration

```bash
ansible all -i plugins/inventory/ssh_config_inventory.py --list-hosts
```

### 2. Libvirt/KVM Dynamic Inventory
**Best for:** Real-time VM discovery with state and resource information

```bash
ansible running_vms -i plugins/inventory/libvirt_kvm.py -m ping
```

### 3. Static YAML Inventory (Development)
**Best for:** Detailed host metadata and development environments

```bash
ansible all -i inventories/development/hosts.yml --list-hosts
```

## Key Features

### Security-First Design
- SELinux/AppArmor enforcement
- Automated security updates
- SSH hardening (key-based auth, no root login)
- File integrity monitoring (AIDE)
- System auditing (auditd)
- Secrets management with Ansible Vault

### Scalability
- Dynamic inventory for infrastructure discovery
- Fact caching for performance
- Parallel execution with configurable forks
- ProxyJump for nested VM access
- Efficient SSH connection reuse

### Modularity & Reusability
- Role-based architecture
- OS-agnostic design (Debian/RHEL families)
- Comprehensive variable management
- Task tagging for selective execution
- Molecule testing framework

## Documentation

| Document | Description |
|----------|-------------|
| [CLAUDE.md](CLAUDE.md) | Complete development guidelines and standards |
| [docs/inventory.md](docs/inventory.md) | Inventory configuration and usage |
| [cheatsheets/inventory.md](cheatsheets/inventory.md) | Quick reference guide |

## Requirements

### Control Node
- Python 3.6+
- Ansible 2.10+
- SSH client with ProxyJump support

### Managed Nodes
- Python 3.x
- SSH server
- `ansible` user with passwordless sudo

### Optional Dependencies
```bash
# For libvirt dynamic inventory
apt-get install python3-libvirt  # Debian/Ubuntu
dnf install python3-libvirt      # RHEL/Rocky/Fedora
```

## Configuration

### ansible.cfg Example

```ini
[defaults]
inventory = ./inventories/development/hosts.yml
roles_path = ./roles
collections_path = ./collections
remote_user = ansible
become = True
become_method = sudo

# Performance
forks = 20
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400

# SSH
host_key_checking = False
ssh_args = -o ControlMaster=auto -o ControlPersist=600s

[inventory]
enable_plugins = yaml, ini, script, auto

[privilege_escalation]
become = True
become_method = sudo
become_user = root
become_ask_pass = False
```

## Common Tasks

### Test Connectivity
```bash
# All hosts
ansible all -i <inventory> -m ping

# Specific group
ansible kvm_guests -i <inventory> -m ping

# With verbose output
ansible all -i <inventory> -m ping -vvv
```

### Gather Facts
```bash
ansible all -i <inventory> -m setup
```

### Run Ad-Hoc Commands
```bash
# Check uptime
ansible all -i <inventory> -m shell -a "uptime"

# Check disk usage
ansible all -i <inventory> -m shell -a "df -h"

# List running VMs on hypervisor
ansible hypervisors -i <inventory> -m shell -a "virsh list --all"
```

### Execute Playbooks
```bash
# Full run
ansible-playbook -i <inventory> site.yml

# Check mode (dry-run)
ansible-playbook -i <inventory> site.yml --check

# Limit to group
ansible-playbook -i <inventory> site.yml --limit kvm_guests

# With tags
ansible-playbook -i <inventory> site.yml --tags "install,configure"
```

## Development Guidelines

Please refer to [CLAUDE.md](CLAUDE.md) for complete development guidelines including:
- Security requirements
- Role development standards
- Testing procedures
- Documentation requirements
- LVM partitioning schema
- Package management
- And much more...

## Troubleshooting

### Connection Issues
```bash
# Test SSH connectivity
ssh -J grokbox ansible@192.168.122.12

# Test with verbose Ansible
ansible pihole -i <inventory> -m ping -vvv

# Check SSH config
cat ~/.ssh/config
```

### Inventory Issues
```bash
# Validate inventory
ansible-inventory -i <inventory> --list

# Check specific host
ansible-inventory -i <inventory> --host <hostname>

# Graph structure
ansible-inventory -i <inventory> --graph
```

### Python/Libvirt Issues
```bash
# Check Python version
ansible all -i <inventory> -m setup -a "filter=ansible_python_version"

# Install libvirt support
apt-get install python3-libvirt  # Debian/Ubuntu
dnf install python3-libvirt      # RHEL/Rocky

# Test libvirt connection
virsh -c qemu+ssh://grok@grok.home.serneels.xyz/system list
```

## Contributing

1. Follow guidelines in [CLAUDE.md](CLAUDE.md)
2. Use feature branches for development
3. Test roles with Molecule
4. Update documentation
5. Create pull request for review

## Security

- **Never commit secrets** to version control
- Use **Ansible Vault** for sensitive data
- Rotate SSH keys every 90-180 days
- Regular security audits with Lynis/OpenSCAP
- Keep systems updated with automatic security patches

## Support

- Documentation: [docs/](docs/)
- Cheatsheets: [cheatsheets/](cheatsheets/)
- Guidelines: [CLAUDE.md](CLAUDE.md)

---

**Project Version:** 1.0.0
**Last Updated:** 2025-11-10
**Maintainer:** Ansible Infrastructure Team