Ansible Infrastructure Automation

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

Repository Structure

This repository uses git submodules for proper separation of concerns:

• Main Repository (PUBLIC): Playbooks, roles, and infrastructure code
• Inventories Submodule (PRIVATE): Dynamic inventories and host configurations
• Secrets Submodule (PRIVATE): SSH keys, vault files, and sensitive data

Quick Start

Initial Setup

# Clone with submodules (recommended)
git clone --recurse-submodules ssh://git@git.mymx.me:2222/ansible/infra-automation.git
cd infra-automation

# Or initialize submodules after clone
git submodule init
git submodule update

# Set up SSH agent for git operations
source .ssh-agent-init

Basic Usage

# Test connectivity with dynamic inventory
ansible all -i inventories/production/libvirt.yml -m ping

# List inventory
ansible-inventory -i inventories/production/libvirt.yml --list

# Run a playbook
ansible-playbook -i inventories/production/libvirt.yml playbooks/gather_system_info.yml

Project Structure

.
├── README.md                       # This file
├── CLAUDE.md                       # Development guidelines and standards
├── ansible.cfg                     # Ansible configuration
├── site.yml                        # Master playbook
├── .ssh-agent-init                 # SSH agent auto-initialization
│
├── inventories/                    # → Git submodule (PRIVATE)
│   ├── production/                 #   Dynamic libvirt inventory
│   ├── staging/                    #   Staging environment
│   └── development/                #   Development environment
│
├── secrets/                        # → Git submodule (PRIVATE)
│   ├── ssh/                        #   SSH keys for automation
│   ├── machines/                   #   Machine-specific secrets
│   └── vaults/                     #   Ansible vault files
│
├── playbooks/                      # Playbooks
│   ├── gather_system_info.yml      # System information collection
│   ├── configure_swap.yml          # Swap configuration
│   ├── install_qemu_agent.yml      # QEMU guest agent
│   └── audit_docker.yml            # Docker security audit
│
├── roles/                          # Ansible roles
│   ├── system_info/                # Production-ready
│   └── deploy_linux_vm/            # Production-ready
│
├── collections/                    # Ansible collections
├── docs/                           # Documentation
│   ├── submodule-workflow.md       # Submodule usage guide
│   ├── git-ssh-setup.md            # Git SSH configuration
│   └── security/                   # Security 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

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

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

3. Static YAML Inventory (Development)

Best for: Detailed host metadata and development environments

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	Complete development guidelines and standards
docs/inventory.md	Inventory configuration and usage
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

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

Configuration

ansible.cfg Example

[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

# 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

ansible all -i <inventory> -m setup

Run Ad-Hoc Commands

# 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

# 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 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

# 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

# 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

# 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
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/
• Cheatsheets: cheatsheets/
• Guidelines: CLAUDE.md

---

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