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)
• Per-environment 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

examples/run.sh is the bootstrap wrapper template used by Boxcar consuming repositories. Copy it to the consuming repository root as run.sh; do not run it in place inside this toolkit checkout. The copied wrapper initializes the top-level playbook/ and vault/ repositories, then delegates to playbook/playbook.sh.

Your project should have:

• galaxy-roles/ directory (for Ansible Galaxy roles)
• git-roles/ directory (for local git roles)
• deploy/ directory with inventory files
• deploy/<env>/group_vars/all/services.yml (or fallback group_vars/all/services.yml) with a services list (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
• services [env]: Generate deploy/<env>/services.yml (all envs when env omitted)
• 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 deploy/<env>/services.yml before deploy or test (codegen only: services [env])
• -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 for all environments
./playbook/playbook.sh services

# Generate services.yml for one environment
./playbook/playbook.sh services actual

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

Troubleshooting

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