Choosing the Right Ansible Connection Plugin for Docker‑Based Workloads

Decision Problem

When you want to run Ansible tasks inside Docker containers you must decide how the control host reaches the target. The choice determines whether you need an SSH daemon inside the container, whether you can use privilege escalation, and how tightly coupled the control host is to Docker.

Constraints to Consider

• Containers may not run an SSH service.
• Existing inventory and privilege‑escalation (become) policies must remain valid.
• Control host may or may not have Docker installed.
• Performance and overhead of the connection method should be acceptable.

Supported Connection Options (Ansible 2.9+)

Plugin	Requirements	Typical Use‑Case	Pros	Cons
local	No extra packages; runs on control host.	Managing the host itself or containers that expose a service on the host network.	Fast, no SSH key management.	Cannot execute commands inside the container’s namespace; only host‑level tasks.
ssh	SSH client and a running SSH daemon inside the container.	When containers expose an SSH service or you need full Ansible feature set.	Standard Ansible workflow; works with existing inventory.	Requires SSH keys, increases image size, adds network latency.
docker	Python package docker‑py on control host; Docker daemon reachable.	Directly exec commands inside containers without SSH.	No SSH daemon needed, lightweight, agent‑less.	Only works with Docker; control host must have Docker; may conflict with restricted Python environments.

Trade‑off Analysis

• Speed vs. Flexibility
  Local is fastest but limited to host tasks. Docker gives near‑local speed with container access, while SSH adds network hops.
• Security Footprint
  SSH requires key distribution and can expose the container to external SSH access. Docker stays within the Docker socket, reducing surface area.
• Compatibility
  SSH works with any remote system that can run an SSH server. Docker is Docker‑only; if you later need to target Kubernetes pods or VMs, you’ll need another plugin.
• Privilege Escalation
  All plugins support become, but inside containers you must ensure the container allows sudo or su and that capabilities are not dropped.

Concrete Implementation: Using the Docker Plugin

Below is a minimal example that installs nginx inside a running container named webapp. The playbook uses the docker connection plugin, which requires the docker‑py package on the control host.

Inventory (inventory.ini)

webapp ansible_connection=docker ansible_docker_extra_args='--tlsverify'

The ansible_docker_extra_args variable is optional and can be used to pass Docker client flags such as TLS verification.

Playbook (deploy.yml)

- hosts: webapp
  gather_facts: false
  tasks:
    - name: Ensure nginx is installed
      ansible.builtin.apt:
        name: nginx
        state: present
      become: true

Run the playbook with a dry‑run to confirm idempotency:

ansible-playbook -i inventory.ini deploy.yml --check

If the output shows no changes, run without --check to apply the configuration.

Verification Steps

1. Ping Test
   Verify connectivity:

   ansible -i inventory.ini webapp -m ansible.builtin.ping

2. Check Package State
   After applying the playbook, inspect the container:

   docker exec webapp dpkg -l | grep nginx

3. Privilege Escalation Test
   Confirm become works inside the container by running a task that requires root, e.g., creating a file in /root.

Limitations & Practical Tips

• Ensure the control host’s Docker socket is accessible (usually /var/run/docker.sock).
• Containers that drop the CAP_SYS_ADMIN capability or run as non‑root may reject sudo commands; test become_method beforehand.
• If you need to target non‑Docker hosts in the same run, mix plugins by specifying ansible_connection per host.
• The docker plugin does not support gather_facts by default; set gather_facts: false or use the docker_facts module if needed.

When to Choose Which Plugin

• Use local when you only need to manage the host or when containers expose services on the host network.
• Use ssh when containers run an SSH daemon or you require a fully generic remote connection for future expansion to VMs or other hosts.
• Use docker when you want lightweight, agent‑less control inside Docker containers and the control host can run Docker.

By aligning the plugin choice with these constraints and trade‑offs, you can keep your Ansible automation efficient, secure, and maintainable.