Running playbooks¶

Use the willhallonline/ansible image to run Ansible without installing it directly on your workstation or CI runner.

The standard convention is:

mount your project at /ansible
set --workdir=/ansible
keep ansible.cfg, inventories, roles, collections, and playbooks in the mounted project

Interactive shell¶

Open a shell to inspect the image or debug commands:

docker run --rm -it willhallonline/ansible:latest /bin/sh

With your project mounted:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  /bin/sh

Inside the shell:

ansible --version
ansible-playbook --version
ansible-inventory -i inventory.ini --graph

One-shot playbook run¶

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook playbook.yml

With inventory and an SSH key:

docker run --rm -it \
  -v $(pwd):/ansible \
  -v ~/.ssh/id_rsa:/home/ansible/.ssh/id_rsa:ro \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml

Canonical compact example:

docker run --rm -it \
  -v $(pwd):/ansible \
  -v ~/.ssh/id_rsa:/home/ansible/.ssh/id_rsa \
  willhallonline/ansible:latest \
  ansible-playbook playbook.yml

Inventory files¶

INI inventory:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml

YAML inventory:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventories/production.yml site.yml

Inspect inventory before running tasks:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-inventory -i inventory.ini --list

Extra variables¶

Simple key-value variables:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml -e app_env=staging

JSON variables:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml \
  -e '{"app_env":"staging","deploy_version":"1.2.3"}'

Variables from a mounted file:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml -e @vars/staging.yml

Limit and tags¶

Limit hosts:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml --limit webservers

Run tagged tasks:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml --tags deploy

Skip tagged tasks:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml --skip-tags destructive

Check mode and diff mode¶

Preview changes:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml --check

Show supported file diffs:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml --check --diff

Note

Check mode depends on module support. Treat it as a safety preview, not a perfect simulation.

Environment variables¶

Set Ansible variables with Docker -e:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  -e ANSIBLE_CONFIG=/ansible/ansible.cfg \
  -e ANSIBLE_HOST_KEY_CHECKING=False \
  -e ANSIBLE_FORCE_COLOR=true \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml

Useful variables:

ANSIBLE_CONFIG=/ansible/ansible.cfg
ANSIBLE_HOST_KEY_CHECKING=False
ANSIBLE_FORCE_COLOR=true
ANSIBLE_STDOUT_CALLBACK=yaml
ANSIBLE_ROLES_PATH=/ansible/roles
ANSIBLE_COLLECTIONS_PATH=/ansible/collections

Host key checking

Disable host key checking only for disposable labs. Use a managed known_hosts file for production and CI.

Project ansible.cfg¶

[defaults]
inventory = inventory.ini
roles_path = roles
collections_paths = collections
stdout_callback = yaml
retry_files_enabled = False
host_key_checking = True

[ssh_connection]
pipelining = True

Then run:

docker run --rm -it -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest ansible-playbook site.yml

Exit codes¶

ansible-playbook returns 0 on success and non-zero on failure. This makes the same command suitable for scripts and CI:

set -euo pipefail
docker run --rm -v $(pwd):/ansible --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml