# 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 -m ping # Specific group ansible kvm_guests -i -m ping # With verbose output ansible all -i -m ping -vvv ``` ### Gather Facts ```bash ansible all -i -m setup ``` ### Run Ad-Hoc Commands ```bash # Check uptime ansible all -i -m shell -a "uptime" # Check disk usage ansible all -i -m shell -a "df -h" # List running VMs on hypervisor ansible hypervisors -i -m shell -a "virsh list --all" ``` ### Execute Playbooks ```bash # Full run ansible-playbook -i site.yml # Check mode (dry-run) ansible-playbook -i site.yml --check # Limit to group ansible-playbook -i site.yml --limit kvm_guests # With tags ansible-playbook -i 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 -m ping -vvv # Check SSH config cat ~/.ssh/config ``` ### Inventory Issues ```bash # Validate inventory ansible-inventory -i --list # Check specific host ansible-inventory -i --host # Graph structure ansible-inventory -i --graph ``` ### Python/Libvirt Issues ```bash # Check Python version ansible all -i -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