This tool converts an Ansible inventory into a fully isolated Docker-based cluster:

• Each Ansible host is mapped to a Docker container
• SSH access is preserved
• Port conflicts are avoided using session-based offsets
• Multiple clusters can run in parallel
• No modification is made to the host system

It is especially useful for testing playbooks such as: https://github.com/ISC-HEI/ansible-playbooks

• Infrastructure-as-Inventory
  The Ansible inventory defines the entire cluster topology.

• Session-based isolation
  Each cluster runs in its own session (S01, S02, …).

• Automatic Docker Compose generation
  No manual Docker configuration is required.

• Playbook execution
  Run Ansible ping or full playbooks against the cluster.

• Clean lifecycle
  Start, test, and destroy clusters cleanly.

• Menu for easy utilisation.

Ansible Inventory

• Session Inventory (localhost with port offsets)
• docker-compose.yml
• Docker containers (SSH enabled)
• ansible / ansible-playbook execution

The following tools are required:

• docker and docker-compose
  • Add { "userns-remap": "default" } in /etc/docker/daemon.json
• python3 + ven
• ansible

Clone this repository:

git clone https://github.com/ISC-HEI/ansible-sample-conf.git
cd ansible-sample-conf

(Optional) Clone the playbooks repository:

cd ..
git clone https://github.com/ISC-HEI/ansible-playbooks.git

Activate a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

This repo provied a menu for easy utilisation, start it like that:

./menu.py

The entry point for CLI commands is:

./cluster.py

Create a new isolated cluster session from an Ansible inventory:

./cluster.py start -i inventory/inventory.yml

This will:

• Create a new session (S01, S02, …)
• Generate a docker-compose file
• Generate a session-specific inventory

Ping all hosts in the active session:

./cluster.py run

Run a specific playbook:

./cluster.py run -t path/to/playbook.yml

If multiple sessions exist, specify one:

./cluster.py run -s S02

Show all active sessions:

./cluster.py sessions

Verbose mode:

./cluster.py sessions -v

Stop all running clusters:

./cluster.py stop

Stop clusters and remove Docker images:

./cluster.py stop --rmi

./cluster.py start -i inventory/inventory.yml
./cluster.py run
./cluster.py run -t playbooks/site.yml
./cluster.py stop

• Supports a single YAML inventory file or a directory of YAML files
• Hosts must define ansible_port
• SSH access is exposed on localhost with a session-based port offset
• The inventory is automatically rewritten for local execution

Minimal example:

web01:
  ansible_port: 22

Because Docker containers share the host kernel:

• Kernel modules (modprobe) will not work
• Low-level system operations may behave differently
• Docker images are minimal and may require additional packages

You can customize the images in:

Dockerfiles/Dockerfile.*

Apache License 2.0

Ansible Playbooks: https://github.com/ISC-HEI/ansible-playbooks