The modern infrastructure landscape is characterized by increasing complexity, diverse operating system environments, and the critical need for consistent, reproducible automation. Traditional methods of managing configuration management tools like Ansible often lead to the notorious "it works on my machine" phenomenon, where discrepancies between local development environments, continuous integration (CI) systems, and production runners cause deployment failures and operational instability. Running Ansible inside a Docker container represents a paradigm shift in how automation is executed, offering a portable, reproducible execution environment that decouples the automation logic from the underlying host operating system. By encapsulating Ansible, its specific version, the Python runtime, and all necessary collections within a Docker image, organizations can ensure that every team member and every CI/CD runner operates with the exact same software stack. This approach eliminates the need to install Ansible directly on local machines or CI/CD runners, thereby removing dependency conflicts, simplifying onboarding, and guaranteeing that the automation pipeline is truly portable across any system capable of running Docker. The strategic adoption of containerized Ansible not only streamlines daily operations but also fortifies the reliability of infrastructure-as-code workflows, making it an essential practice for contemporary DevOps and site reliability engineering teams.

The Strategic Imperative for Containerized Automation

The decision to run Ansible within a container is driven by several compelling technical and operational advantages that address common pain points in infrastructure management. The primary benefit is consistency. In traditional setups, different team members might have different versions of Ansible installed locally, or their system Python environments might have conflicting packages that interfere with automation scripts. By using a Docker container, every team member and every CI/CD run utilizes the identical Ansible version, Python version, and collection set. This uniformity ensures that a playbook that succeeds in a local test environment will behave identically in the production deployment pipeline, significantly reducing debugging time and enhancing deployment confidence.

Another critical advantage is the elimination of local installation requirements. Developers and operators do not need to clutter their local machines with Ansible binaries, Python virtual environments, or associated system libraries. They simply pull the pre-built Docker image and execute it. This is particularly valuable in environments where administrative privileges are restricted, or where the host operating system is not Linux-based, such as macOS or Windows. The container provides a standardized Linux environment for Ansible to operate within, regardless of the host OS.

Version switching becomes trivial when Ansible is containerized. Different projects may require different versions of Ansible or specific collections that are incompatible with other projects. With a containerized approach, each project can define its own Dockerfile or use a specific image tag, allowing teams to run multiple versions of Ansible side-by-side without conflict. For instance, a legacy project might require Ansible 2.9, while a new microservices initiative uses Ansible 9.2.0. These can coexist seamlessly because they are isolated within their respective containers.

The clean environment aspect is also significant. Running Ansible in a container ensures that there are no conflicts with system Python packages or other tools installed on the host. The container is ephemeral and isolated, meaning that the automation state remains pure and unaffected by residual data from previous runs or host-specific configurations. This isolation is particularly beneficial for security and hygiene, as it prevents the accumulation of temporary files or credentials on the host system.

Finally, portability is the cornerstone of this approach. A containerized Ansible image works on any system that runs Docker, whether it is a developer's laptop, a shared build server, or a cloud-based CI/CD runner. This universality simplifies the automation pipeline, making it truly portable and resilient to changes in the underlying infrastructure. The following table summarizes the key benefits of running Ansible in a Docker container.

Utilizing Official and Community Ansible Images

Before diving into custom image creation, it is important to understand the available official and community-maintained Ansible Docker images. The Ansible community maintains container images that are ready to use out of the box. One such image is the Ansible Creator Execution Environment, which can be pulled from Quay.io. This image provides a robust foundation for running Ansible playbooks and ad-hoc commands.

To pull the latest Ansible image, one can execute the following command:

bash docker pull quay.io/ansible/creator-ee:latest

Once the image is available locally, it can be used to run ad-hoc commands. For example, to ping all hosts defined in a local inventory file, the following command mounts the user's SSH keys and the current working directory into the container:

bash docker run --rm \ -v ~/.ssh:/root/.ssh:ro \ -v $(pwd):/ansible:rw \ -w /ansible \ quay.io/ansible/creator-ee:latest \ ansible all -i inventory.ini -m ping

In this command, the -v ~/.ssh:/root/.ssh:ro flag mounts the user's SSH directory as read-only, ensuring that the container can authenticate with remote hosts without modifying the local keys. The -v $(pwd):/ansible:rw flag mounts the current directory into the container at /ansible with read-write access, allowing the playbook and inventory files to be accessed and modified if necessary. The -w /ansible flag sets the working directory inside the container to /ansible. While official images provide a convenient starting point, they may not always meet the specific requirements of a project, such as custom system dependencies or specific collection versions. Therefore, for production use, it is often recommended to build a custom image that includes exactly what the project needs.

Architecting a Custom Ansible Docker Image

Building a custom Ansible Docker image allows for precise control over the automation environment. This process involves creating a Dockerfile that defines the base image, installs system dependencies, installs Ansible and related tools, and installs necessary Ansible collections. The following is a detailed breakdown of a typical Dockerfile for an Ansible automation environment.

The first step is to define the base image. A slim Python image is often used to keep the container size small while providing the necessary Python runtime. For example:

dockerfile FROM python:3.11-slim

Next, system dependencies that Ansible or its modules might require are installed. These typically include tools for SSH connectivity, password-based authentication, version control, and file synchronization. The following command updates the package list and installs these dependencies:

bash RUN apt-get update && \ apt-get install -y --no-install-recommends \ openssh-client \ sshpass \ git \ rsync \ && rm -rf /var/lib/apt/lists/*

The openssh-client is essential for SSH-based communication with managed hosts. sshpass allows for non-interactive password-based SSH authentication, which can be useful in certain scenarios. git is often required for cloning repositories or using Ansible roles from Git sources. rsync is used for efficient file synchronization. The --no-install-recommends flag helps to keep the image size small by avoiding the installation of recommended but non-essential packages. The rm -rf /var/lib/apt/lists/* command cleans up the package cache to further reduce the image size.

After installing system dependencies, Ansible and related tools are installed using pip. This ensures that the exact versions of Ansible and its plugins are controlled by the Dockerfile. The following command installs Ansible 9.2.0, Ansible-lint 24.2.0, and some common Python libraries used by Ansible modules:

bash RUN pip install --no-cache-dir \ ansible==9.2.0 \ ansible-lint==24.2.0 \ jmespath==1.0.1 \ netaddr==1.2.1

The --no-cache-dir flag prevents pip from caching packages, which helps to keep the image size small. jmespath is a JSON query language used by some Ansible modules, and netaddr is a library for working with IP addresses and networks.

Following the installation of Ansible itself, commonly needed Ansible collections are installed using the ansible-galaxy command. Collections are modular units of Ansible content that include modules, plugins, modules, and roles. The following command installs several popular community collections:

bash RUN ansible-galaxy collection install \ community.general \ ansible.posix \ community.docker

The community.general collection provides a wide range of modules and filters that are widely used in Ansible playbooks. ansible.posix includes modules for managing POSIX systems, such as the firewalld and seboolean modules. community.docker provides modules for managing Docker containers and images.

Finally, the working directory is set to /ansible, and a default command is defined to show the Ansible version when the container is started without additional arguments:

dockerfile WORKDIR /ansible CMD ["ansible", "--version"]

To build the custom Ansible image, the following command is used:

bash docker build -t ansible-runner:9.2.0 -f Dockerfile.ansible .

This command builds the image from the Dockerfile.ansible file in the current directory and tags it as ansible-runner:9.2.0. This custom image can now be used to run Ansible playbooks with the exact configuration required by the project.

Executing Playbooks from the Container

Once the custom Ansible image is built, it can be used to execute playbooks, ad-hoc commands, and linting checks. The basic principle involves mounting the project directory and SSH keys into the container, setting the working directory, and then running the desired Ansible command.

For basic playbook execution, the following command mounts the user's SSH keys and the current directory into the container and runs a playbook:

bash docker run --rm \ -v ~/.ssh:/root/.ssh:ro \ -v $(pwd):/ansible:rw \ -w /ansible \ ansible-runner:9.2.0 \ ansible-playbook -i inventory.ini playbooks/deploy.yml

The flags used in this command have specific functions:
- --rm: Removes the container after it exits, ensuring that no residual containers are left behind.
- -v ~/.ssh:/root/.ssh:ro: Mounts the user's SSH directory as read-only, allowing the container to use the local SSH keys for authentication.
- -v $(pwd):/ansible:rw: Mounts the current directory with read-write access into the container at /ansible, allowing the playbook and inventory files to be accessed and modified.
- -w /ansible: Sets the working directory inside the container to /ansible.

If the playbook uses Ansible Vault to encrypt sensitive variables, the vault password file must also be mounted into the container. The following command demonstrates how to pass the vault password through a file:

bash docker run --rm \ -v ~/.ssh:/root/.ssh:ro \ -v $(pwd):/ansible:rw \ -v ~/.vault_pass:/root/.vault_pass:ro \ -w /ansible \ ansible-runner:9.2.0 \ ansible-playbook -i inventory.ini \ --vault-password-file /root/.vault_pass \ playbooks/deploy.yml

In this command, the -v ~/.vault_pass:/root/.vault_pass:ro flag mounts the vault password file as read-only, and the --vault-password-file /root/.vault_pass argument tells Ansible to use this file for decrypting vaulted variables.

Enhancing Workflow with Wrapper Scripts

To simplify the execution of Ansible commands through Docker, a shell script can be created to wrap the Docker command. This script automates the mounting of SSH keys, setting the working directory, and passing additional flags, making it easier to run Ansible commands from the command line.

The following is an example of a wrapper script named ansible-docker.sh:

```bash

!/bin/bash

ansible-docker.sh - Run Ansible commands inside Docker

IMAGE="ansible-runner:9.2.0"
PROJECTDIR="$(pwd)"
docker run --rm \
-v ~/.ssh:/root/.ssh:ro \
-v "${PROJECTDIR}:/ansible:rw" \
-w /ansible \
-e ANSIBLEFORCECOLOR=true \
-e ANSIBLEHOSTKEY_CHECKING=false \
"${IMAGE}" \
"$@"
```

To use this script, it must first be made executable:

bash chmod +x ansible-docker.sh

Once executable, any Ansible command can be run through Docker by prefixing it with ./ansible-docker.sh. For example:

bash ./ansible-docker.sh ansible-playbook -i inventory.ini playbooks/deploy.yml ./ansible-docker.sh ansible all -i inventory.ini -m ping ./ansible-docker.sh ansible-lint playbooks/

The -e ANSIBLE_FORCE_COLOR=true flag ensures that Ansible output is colorized, improving readability. The -e ANSIBLE_HOST_KEY_CHECKING=false flag disables SSH host key checking, which can be useful for automated environments where host keys may change frequently. However, it is important to note that disabling host key checking can have security implications, so it should be used with caution.

An alternative wrapper script, inspired by earlier work in the community, can also be used. This script, named ansible_helper, mounts specific SSH keys and the playbooks directory:

```bash

!/usr/bin/env bash

docker run --rm -it \
-v ~/.ssh/idrsa:/root/.ssh/idrsa \
-v ~/.ssh/idrsa.pub:/root/.ssh/idrsa.pub \
-v $(pwd):/ansible_playbooks \
-v /var/log/ansible/ansible.log \
walokra/ansible-playbook "$@"
```

This script can be pointed to any inventory file to execute any Ansible command on any host. For example:

bash ./ansible_helper play playbooks/deploy.yml -i inventory/dev -e 'some_var=some_value'

This approach isolates Ansible's dependencies and frees users from the restrictions of Linux distribution package managers, allowing them to use the latest or most suitable versions of Ansible regardless of the host OS.

Configuring Docker Compose for Ansible

For more complex setups, Docker Compose can be used to manage the Ansible container and its associated services. Docker Compose allows for the definition of multiple services, including Ansible and ansible-lint, in a single docker-compose.yml file. This makes it easy to run playbooks, lint playbooks, and execute ad-hoc commands using a unified interface.

The following is an example docker-compose.yml file that defines two services: ansible and ansible-lint. Both services are built from the same Dockerfile but have different entrypoints and default commands.

yaml services: ansible: build: context: . dockerfile: Dockerfile.ansible volumes: - .:/ansible:rw working_dir: /ansible entrypoint: ["ansible-playbook"] command: ["--help"] ansible-lint: build: context: . dockerfile: Dockerfile.ansible volumes: - .:/ansible:rw working_dir: /ansible entrypoint: ["ansible-lint"] command: ["."]

To use this configuration, the following commands can be executed:

```bash

Run a playbook

docker compose run --rm ansible -i inventory.ini playbooks/deploy.yml

Run ansible-lint

docker compose run --rm ansible-lint

Run an ad-hoc command

docker compose run --rm --entrypoint ansible ansible all -i inventory.ini -m ping
```

The docker compose run --rm command runs the specified service in a temporary container and removes it after it exits. The --entrypoint flag can be used to override the default entrypoint for ad-hoc commands.

Integrating Ansible Containers into CI/CD Pipelines

One of the most significant advantages of containerized Ansible is its seamless integration into CI/CD pipelines. By using Docker containers, CI/CD runners can execute Ansible playbooks without needing to install Ansible or manage Python environments on the host. This ensures consistent behavior regardless of the runner's operating system.

GitHub Actions Integration

In GitHub Actions, Ansible can be installed and run within a job step. The following is an example of a GitHub Actions workflow that deploys using Ansible:

yaml name: Ansible Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest container: image: python:3.11-slim steps: - uses: actions/checkout@v4 - name: Install Ansible run: | pip install ansible==9.2.0 ansible-galaxy collection install -r collections/requirements.yml - name: Set up SSH key run: | mkdir -p ~/.ssh echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_ed25519 chmod 600 ~/.ssh/id_ed25519 ssh-keyscan -H ${{ secrets.SERVER_HOST }} >> ~/.ssh/known_hosts - name: Run playbook run: ansible-playbook -i inventory/production.ini playbooks/deploy.yml env: ANSIBLE_HOST_KEY_CHECKING: "false"

In this workflow, the job runs in a container based on the python:3.11-slim image. Ansible is installed using pip, and the required collections are installed from a requirements file. The SSH private key is retrieved from a secret and written to the SSH directory, with appropriate permissions set. The ssh-keyscan command is used to populate the known_hosts file with the public key of the target server. Finally, the playbook is run with ANSIBLE_HOST_KEY_CHECKING set to false to avoid issues with host key verification.

GitLab CI Integration

Similarly, GitLab CI can be configured to run Ansible playbooks. The following is an example .gitlab-ci.yml file that includes linting and deployment stages:

yaml stages: - lint - deploy lint: stage: lint image: python:3.11-slim before_script: - pip install ansible==9.2.0 ansible-lint script: - ansible-lint playbooks/ deploy: stage: deploy image: python:3.11-slim only: - main before_script: - pip install ansible==9.2.0 - ansible-galaxy collection install -r collections/requirements.yml script: - ansible-playbook -i inventory/production.ini playbooks/deploy.yml

In this configuration, the lint stage runs ansible-lint on the playbooks to ensure they adhere to best practices. The deploy stage runs the playbook on the main branch. Both stages use the same base image and install Ansible and required collections before executing the commands.

Network Considerations for Containerized Ansible

When running Ansible in a Docker container, network connectivity to managed hosts is a critical consideration. By default, Docker containers use a bridge network, which allows them to communicate with the host and other containers on the same network. If the managed hosts are on the local network, the container can typically reach them through the bridge network.

However, in some cases, it may be necessary for the container to use the host's network stack directly. This can be achieved using the --network host flag, which is only available on Linux hosts. The following command demonstrates how to run Ansible with host networking:

bash docker run --rm --network host \ -v ~/.ssh:/root/.ssh:ro \ -v $(pwd):/ansible:rw \ -w /ansible \ ansible-runner:9.2.0 \ ansible-playbook -i inventory.ini playbooks/deploy.yml

It is important to note that the --network host flag does not work the same way on macOS and Windows because Docker runs in a VM on these operating systems. In these environments, the default bridge network should work for reaching external hosts. If connectivity issues arise, it may be necessary to adjust the network configuration of the Docker VM or use port forwarding to expose the necessary ports.

Conclusion

Running Ansible inside a Docker container is a powerful strategy for achieving reproducible, consistent, and portable automation. By encapsulating Ansible, its dependencies, and its configuration within a container, teams can eliminate the variability that often plagues traditional automation setups. This approach ensures that every execution, whether on a developer's laptop or in a CI/CD pipeline, uses the exact same software stack, thereby reducing the risk of deployment failures and improving overall operational efficiency. The ability to build custom images with specific versions of Ansible and collections provides the flexibility needed to support diverse projects, while wrapper scripts and Docker Compose configurations simplify daily operations. As infrastructure continues to evolve, the adoption of containerized Ansible will likely become a standard practice for organizations seeking to streamline their automation workflows and enhance their reliability. The detailed exploration of image creation, execution methods, and CI/CD integration presented in this article provides a comprehensive foundation for implementing this approach in real-world environments.

Sources

1. Running Ansible inside a Docker container
2. ansible-playbook Docker Gist