Ansible Learning Lab

Developed with: Claude Code Agent + Kimi LLM + Superpowers Skills

A production-grade Ansible learning project covering roles, templates, handlers, Vault encryption, dynamic inventory, Molecule testing, and code quality tooling.

Features

• Roles: common, nginx, mysql, app_deploy
• Templates: Jinja2 Nginx config, Flask app, systemd service
• Handlers: Service reload/restart triggers
• Ansible Vault: Encrypted sensitive variables
• Dynamic Inventory: Python script auto-discovers Docker containers
• Testing: Molecule with Docker driver for each role
• Code Quality: ansible-lint, yamllint, pre-commit hooks
• IDE Integration: VS Code workspace configuration

Prerequisites

• Python 3.11+
• Poetry (pipx install poetry or brew install poetry)
• Docker Desktop
• VS Code (recommended)

Quick Start

# 1. Clone and enter project
git clone <repo-url> && cd ansible-learning-lab

# 2. Install dependencies (creates isolated virtual environment)
poetry install

# 3. Activate virtual environment (Poetry 2.0+)
eval $(poetry env activate)

# 4. Verify tools
ansible --version
molecule --version
ansible-lint --version

# --- Alternative: without activating, prefix every command with `poetry run` ---
# poetry run ansible --version
# poetry run molecule --version
# poetry run ansible-lint --version

# 5. Start Docker test environment (run from project root)
docker compose -f tests/docker-compose.yml up -d

# 6. Test Ansible connectivity (run from project root)
ansible all -i inventory/docker.yml -m ping

# 7. Run full site deployment (run from project root)
ansible-playbook -i inventory/docker.yml playbooks/site.yml

# 8. Run all Molecule tests (run from project root)
./scripts/ci-local.sh

Project Structure

.
├── ansible.cfg              # Ansible configuration
├── pyproject.toml           # Poetry dependencies
├── tests/
│   └── docker-compose.yml   # Local test nodes
├── inventory/
│   ├── docker.yml           # Static inventory
│   └── dynamic/             # Dynamic inventory script
├── group_vars/              # Group variables
├── host_vars/               # Host variables
├── playbooks/
│   ├── site.yml             # Main playbook
│   ├── deploy_web.yml       # Web tier only
│   └── setup_database.yml   # DB tier only
└── roles/
    ├── common/              # System baseline
    ├── nginx/               # Web server
    ├── mysql/               # Database
    └── app_deploy/          # Flask application

VS Code Setup

Install the recommended extensions when prompted. VS Code is pre-configured to:

• Use the Poetry virtual environment Python interpreter
• Run ansible-lint on save
• Format YAML files automatically
• Provide task shortcuts (Ctrl+Shift+P > "Tasks: Run Task")

Code Quality

All quality checks run locally via Poetry:

# Run Ansible linter
poetry run ansible-lint

# Run YAML linter
poetry run yamllint .

# Run pre-commit hooks manually
poetry run pre-commit run --all-files

# Run full CI suite (lint + all Molecule tests)
poetry run ./scripts/ci-local.sh

Pre-commit hooks are installed automatically. They run on every git commit.

Role Testing with Molecule

Each role has Molecule tests:

# Test a specific role
cd roles/nginx && poetry run molecule test

# Test all roles
for role in roles/*/; do
    cd "$role" && poetry run molecule test && cd - > /dev/null
done

Dynamic Inventory

The dynamic inventory script auto-discovers Docker containers:

# View generated inventory
python inventory/dynamic/docker_inventory.py --list

# Use dynamic inventory with playbooks
ansible-playbook -i inventory/dynamic/docker_inventory.py playbooks/site.yml

Ansible Vault

Sensitive variables are encrypted with Ansible Vault:

# View encrypted file
ansible-vault view group_vars/all/vault.yml --vault-password-file vault_password_file

# Edit encrypted file
ansible-vault edit group_vars/all/vault.yml --vault-password-file vault_password_file

Learning Points by Role

Role	Concepts
common	Variables, loops (loop), conditionals (when)
nginx	Jinja2 templates, handlers (notify/handlers)
mysql	Vault encryption, no_log, service management
app_deploy	Role dependencies, systemd, variable precedence
Dynamic Inventory	Custom Python inventory plugins
Molecule	Convergence, idempotence, verification testing