ansible/infra-automation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7e89e93c9f582f6de8d4656cdaac828faabcdda1
infra-automation/README.md
ansible 7e89e93c9f Update documentation for PRIVATE submodules structure 
📚 Documentation Update - Repository Security Enhancement

Changes:
1. Updated README.md:
   - Clarified submodule structure (both PRIVATE)
   - Updated Quick Start with submodule commands
   - Updated Project Structure diagram
   - Added SSH agent initialization

2. Created docs/submodule-workflow.md:
   - Comprehensive submodule usage guide
   - Clone, update, and workflow procedures
   - Security considerations for both submodules
   - Troubleshooting section
   - Best practices and compliance notes

3. Made ansible-inventories PRIVATE:
   - Protects internal network topology
   - Protects IP addresses and hostnames
   - Updated all documentation to reflect PRIVATE status

4. Updated inventories submodule reference:
   - Points to latest commit with security updates

Security Rationale:
- inventories → PRIVATE: Protects network topology, IP addresses
- secrets → PRIVATE: Protects SSH keys, vault files
- Main repo → PUBLIC: Playbooks and roles only

Repository Structure:
├── infra-automation (PUBLIC)
├── inventories (PRIVATE)
└── secrets (PRIVATE)

Benefits:
✅ Network topology protection
✅ Sensitive data isolation
✅ Proper access controls
✅ Independent version control
✅ Security-first approach

Documentation:
- docs/submodule-workflow.md: Complete submodule guide
- docs/git-ssh-setup.md: SSH configuration
- README.md: Updated project structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-11 14:47:12 +01:00

346 lines
9.1 KiB
Markdown
Raw Blame History

# 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
```bash
# 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
```bash
# 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
```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
Reference in New Issue View Git Blame Copy Permalink