Ansible Playbook Toolkit

A reusable toolkit for managing Ansible deployments with venv support, role updates, and dynamic playbook generation.

Features

• CLI tool for deploying and testing Ansible playbooks
• Automatic venv creation and management with uv
• Conditional role updates (galaxy, git, submodules)
• Dynamic services.yml generation from templates
• Standalone update scripts

Requirements

• Bash
• Git
• Ansible (optional, auto-installed in venv)
• uv (optional, auto-installed)

Installation

Add as a git submodule to your Ansible project:

git submodule add <repository-url> playbook
git submodule update --init --recursive

Your project should have:

• galaxy-roles/ directory (for Ansible Galaxy roles)
• git-roles/ directory (for local git roles)
• deploy/ directory with inventory files
• services variable defined (list of services with name/repo/version)

Usage

From your project root:

./playbook/playbook.sh [options] <action> [args]

When one or more update options are provided without an action, the tool runs only the requested setup updates.

Actions

• deploy <env>: Deploy to environment
• test <env>: Test inventory connectivity
• upgrade: Upgrade Ansible in venv
• version: Show versions
• help: Show help

Options

• -R: Update roles (galaxy and git)
• -S: Generate services.yml
• -M: Update git submodules
• -U <url>: uv install URL
• -E <dir>: venv directory

Examples

# Test with updates
./playbook/playbook.sh -R -S test staging

# Generate services.yml only
./playbook/playbook.sh -S

# Update roles and git submodules only
./playbook/playbook.sh -R -M

# Deploy with role updates
./playbook/playbook.sh -R deploy production

# Show versions
./playbook/playbook.sh version

Configuration

Set environment variables for customization:

• PLAYBOOK_USE_BASE_ANSIBLE=1: Use system Ansible instead of venv
• PLAYBOOK_VENV_DIR: Venv directory (default: ../.venv)
• PLAYBOOK_REPO_ROOT: Path to project root (default: ..)

Troubleshooting

• Ensure Git and Ansible are installed
• Check paths if using custom locations
• Run ./playbook/playbook.sh version to verify setup