Managing infrastructure with Ansible is simple in theory: install Ansible, define an inventory, write playbooks, and connect to remote systems over SSH. In practice, the control node itself often becomes a source of inconsistency. Different laptops, CI runners, jump boxes, and lab servers may have different Ansible versions, Python packages, SSH configurations, and directory layouts.

To solve this problem, I created a containerized Ansible controller image:

docker.io/allamiro1/ansible-controller

The goal is simple: provide a reusable Ansible control node that can run anywhere Docker runs, while keeping configuration, inventory, SSH access, and logs outside the container.

Why Containerize the Ansible Control Node?

Ansible is agentless, but it still depends heavily on the control environment. The machine running Ansible needs the correct Ansible version, Python dependencies, SSH client configuration, inventory files, roles, collections, and logging paths.

In a home lab, enterprise lab, or CI/CD environment, this can quickly become messy. One engineer may run Ansible from a laptop. Another may run it from a shared Linux server. A CI job may run it from a temporary runner. Over time, the control node becomes difficult to reproduce.

A Docker-based Ansible controller helps standardize this layer.

Instead of rebuilding the control environment manually, the controller image provides:

• Ansible CLI preinstalled
• OpenSSH server for remote access into the controller
• A non-root ansible user
• Passwordless sudo inside the container
• Host-mounted configuration under /configs
• Host-mounted logs under /var/log/ansible
• Support for both linux/amd64 and linux/arm64

This makes the image useful for labs, training environments, CI/CD testing, and portable infrastructure automation.

Why Use a Containerized Ansible Controller?

Normally, Ansible is installed directly on a Linux system:

sudo apt install ansible

That works, but it ties the automation environment to the host. Over time, the host may change. Packages get upgraded. Python dependencies change. SSH configuration changes. Logs are written locally. Different users may have different environments.

With a containerized controller, the execution environment becomes predictable.

• The host provides the files.
• The container provides the tools.
• The remote systems receive the automation.

This separation is the main benefit.

Recommended Directory Layout

A simple project layout can look like this:

ansible-controller-project/
├── configs/
│   ├── ansible.cfg
│   ├── inventory/
│   │   └── hosts.ini
│   ├── playbooks/
│   │   └── site.yml
│   ├── roles/
│   └── group_vars/
├── logs/
│   └── ansible.log
└── ssh/
    └── authorized_keys

The configs directory contains the Ansible configuration, inventory, playbooks, roles, and variables.

The logs directory stores Ansible logs from inside the container.

The ssh directory contains the public key used to SSH into the controller as the ansible user.

This layout keeps the container disposable. You can remove and recreate the container without losing your actual automation files.

Creating the Host Directories

Start by creating the required directories:

mkdir -p configs/inventory
mkdir -p configs/playbooks
mkdir -p configs/roles
mkdir -p configs/group_vars
mkdir -p logs
mkdir -p ssh

If you want to SSH into the container, copy your public key:

cp ~/.ssh/id_rsa.pub ssh/authorized_keys

If your public key has a different name, adjust the command:

cp ~/.ssh/id_ed25519.pub ssh/authorized_keys

Example ansible.cfg

Create the Ansible configuration file:

cat > configs/ansible.cfg <<'EOF'
[defaults]
inventory = /configs/inventory/hosts.ini
retry_files_enabled = False
host_key_checking = False
log_path = /var/log/ansible/ansible.log

[privilege_escalation]
become = True
become_method = sudo
become_user = root

[ssh_connection]
pipelining = True
EOF

This tells Ansible to read the inventory from:

/configs/inventory/hosts.ini

and write logs to:

/var/log/ansible/ansible.log

For lab environments, disabling host key checking may be convenient. For production, host key checking should be enabled and managed properly.

Example Inventory

Create a simple inventory file:

cat > configs/inventory/hosts.ini <<'EOF'
[all]
server1 ansible_host=192.0.2.10 ansible_user=admin
EOF

For a more realistic environment, you can organize hosts by role:

[web]
web1 ansible_host=10.10.10.11 ansible_user=admin
web2 ansible_host=10.10.10.12 ansible_user=admin

[database]
db1 ansible_host=10.10.20.11 ansible_user=admin

[linux:children]
web
database

Example Playbook

Create a basic test playbook:

cat > configs/playbooks/site.yml <<'EOF'
---
- name: Test Ansible controller
  hosts: all
  become: true

  tasks:
    - name: Check connectivity
      ansible.builtin.ping:

    - name: Print hostname
      ansible.builtin.command: hostname
      register: hostname_output
      changed_when: false

    - name: Show hostname
      ansible.builtin.debug:
        var: hostname_output.stdout
EOF

This playbook tests connectivity and prints the hostname of each managed node.

Running the Container

Run the Ansible controller container:

docker run -d --name ansible-ctrl \
  -p 2222:22 \
  -v "$PWD/configs":/configs:rw \
  -v "$PWD/logs":/var/log/ansible:rw \
  -v "$PWD/ssh/authorized_keys":/home/ansible/.ssh/authorized_keys:ro \
  allamiro1/ansible-controller:latest

The mount points are important:

Host path                  Container path
------------------------------------------------
./configs                  /configs
./logs                     /var/log/ansible
./ssh/authorized_keys      /home/ansible/.ssh/authorized_keys

The container exposes SSH on port 2222 on the host.

Accessing the Controller

You can SSH into the container:

ssh -p 2222 ansible@localhost

Once inside, test Ansible:

ansible all -m ping

Run a playbook:

ansible-playbook /configs/playbooks/site.yml

Because the configuration is mounted from the host, Ansible automatically uses:

/configs/ansible.cfg
/configs/inventory/hosts.ini

Running Ansible Without SSHing Into the Container

You can also execute Ansible commands directly using docker exec:

docker exec -it ansible-ctrl ansible all -m ping

Run a playbook:

docker exec -it ansible-ctrl ansible-playbook /configs/playbooks/site.yml

This is useful for scripts and CI/CD pipelines because you do not need an interactive SSH session.

Checking Logs

Ansible logs are written inside the container to:

/var/log/ansible/ansible.log

Because this path is mounted to the host, you can view logs directly:

cat logs/ansible.log

Or follow them live:

tail -f logs/ansible.log

This is useful when testing playbooks or troubleshooting failed automation runs.

Example Docker Compose File

For repeated use, Docker Compose is cleaner than a long docker run command.

Create docker-compose.yml:

services:
  ansible-controller:
    image: allamiro1/ansible-controller:latest
    container_name: ansible-ctrl
    ports:
      - "2222:22"
    volumes:
      - ./configs:/configs:rw
      - ./logs:/var/log/ansible:rw
      - ./ssh/authorized_keys:/home/ansible/.ssh/authorized_keys:ro
    restart: unless-stopped

Start it:

docker compose up -d

Enter the container:

docker exec -it ansible-ctrl bash

Run Ansible:

ansible all -m ping

Stop it:

docker compose down

How This Helps in Real Environments

This pattern is useful when you want the Ansible control node to be consistent across different systems.

For example, you can use it in:

Home labs
Training labs
CI/CD runners
Temporary automation environments
Jump-server-style automation hosts
Testing environments before production rollout

The same container image can be used by multiple engineers, while each environment mounts its own inventory, variables, playbooks, and SSH keys.

This keeps automation portable without forcing every host to install Ansible directly.

Important Security Notes

This container should be treated as an automation control node. It may have access to SSH keys, inventories, privileged accounts, and playbooks that can change remote systems.

For safer use:

Use read-only mounts where possible
Do not mount private keys unless required
Avoid storing secrets directly in inventory files
Use Ansible Vault for sensitive values
Enable host key checking in production
Restrict access to the SSH port
Keep the image updated
Review vulnerability scan results

The Docker Hub vulnerability scan currently shows a high number of vulnerabilities for some image tags. That should be addressed before using the image in sensitive or production environments.Possible hardening steps include reducing the base image size, removing unnecessary packages, rebuilding regularly, adding CI/CD image scanning, and publishing a hardened variant.

Conclusion

Containerizing the Ansible control node is a practical way to make automation workflows more portable and reproducible. By separating the image from the configuration, inventory, SSH keys, and logs, the controller remains disposable while the automation content remains persistent and version-controlled.

The allamiro1/ansible-controller image is a small step toward cleaner infrastructure automation workflows. It provides a simple pattern: package the toolchain, mount the configuration, run the automation, and keep the host environment clean.

Project Links and References

Project Links

• GitHub Repository: https://github.com/allamiro/ansible-controller
• Docker Hub Image: https://hub.docker.com/r/allamiro1/ansible-controller
• Docker Pull Command:

docker pull allamiro1/ansible-controller:latest