Ansible Docker Automation

Docker packages an application and everything it needs into a container. Running containers on one laptop is simple. Running them across many servers with consistent settings takes automation. Ansible installs Docker, pulls images, starts containers, creates networks, and cleans up unused items. Think of a shipping port: containers are standard boxes, and Ansible is the crane operator who places each box in the right spot on every ship.

Diagram: What Ansible Controls

  ┌──────────────┐
  │   Ansible    │
  └──────┬───────┘
         │ SSH
         ▼
  ┌──────────────────────────────────────────┐
  │ Docker Host                              │
  │                                          │
  │  Docker Engine                           │
  │   ├── Images    (nginx, mysql, shop-app) │
  │   ├── Networks  (shop_net)               │
  │   ├── Volumes   (db_data)                │
  │   └── Containers                         │
  │        ┌────────┐ ┌────────┐ ┌────────┐  │
  │        │ web    │ │ app    │ │ db     │  │
  │        └────────┘ └────────┘ └────────┘  │
  └──────────────────────────────────────────┘

Prepare the Control Node

The Docker modules live in the community.docker collection. Install the collection on the control node and the Docker SDK for Python on every managed node.

ansible-galaxy collection install community.docker

Install Docker on a Server

- name: Prepare Docker host
  hosts: dockerhosts
  become: true
  tasks:
    - name: Install Docker and the Python SDK
      ansible.builtin.package:
        name:
          - docker.io
          - python3-docker
        state: present

    - name: Start Docker at boot
      ansible.builtin.service:
        name: docker
        state: started
        enabled: true

    - name: Allow the deploy user to run Docker
      ansible.builtin.user:
        name: deploy
        groups: docker
        append: true

Key Modules

ModuleJob
community.docker.docker_imagePull, build, or remove images
community.docker.docker_containerCreate, start, stop, and remove containers
community.docker.docker_networkManage networks
community.docker.docker_volumeManage volumes
community.docker.docker_compose_v2Run Docker Compose projects
community.docker.docker_loginSign in to a registry
community.docker.docker_pruneRemove unused objects

Deploy a Small Web Stack

- name: Deploy shop stack
  hosts: dockerhosts
  tasks:
    - name: Create a private network
      community.docker.docker_network:
        name: shop_net

    - name: Create a volume for database files
      community.docker.docker_volume:
        name: db_data

    - name: Start the database
      community.docker.docker_container:
        name: shop_db
        image: mariadb:10.11
        state: started
        restart_policy: unless-stopped
        networks:
          - name: shop_net
        volumes:
          - db_data:/var/lib/mysql
        env:
          MARIADB_ROOT_PASSWORD: "{{ vault_db_root_password }}"
      no_log: true

    - name: Start the web server
      community.docker.docker_container:
        name: shop_web
        image: nginx:1.25
        state: started
        restart_policy: unless-stopped
        ports:
          - "8080:80"
        networks:
          - name: shop_net

The module checks the current state before acting. A second run reports no change when the containers already match the request, which keeps the playbook idempotent.

Update a Running Container

Pull a new image tag and recreate the container when the image changes.

- name: Pull the new release
  community.docker.docker_image:
    name: nginx
    tag: "1.26"
    source: pull

- name: Recreate the web container
  community.docker.docker_container:
    name: shop_web
    image: nginx:1.26
    recreate: true
    ports:
      - "8080:80"

Build Images

- name: Build the application image
  community.docker.docker_image:
    name: shop-app
    tag: "2.1"
    source: build
    build:
      path: /opt/shop/src

Compose Projects

- name: Start a compose project
  community.docker.docker_compose_v2:
    project_src: /opt/shop
    state: present

Clean Up

- name: Remove stopped containers and dangling images
  community.docker.docker_prune:
    containers: true
    images: true

Practical Tips

  • Pin image tags to exact versions instead of latest
  • Store registry passwords and secrets in Ansible Vault
  • Set restart_policy so containers survive reboots
  • Use docker_container_info to check health before moving on

Try This

Write a playbook that starts an nginx container with the port mapping 8080:80. Open http://localhost:8080 in a browser to see the welcome page. Change the playbook to use state: absent and rerun it to remove the container.

Summary

The community.docker collection brings Docker management into playbooks. Modules install images, create networks and volumes, start containers, and run Compose projects. Declarative tasks check current state and change only what differs. Version pinning, vault-protected secrets, and restart policies make container deployments dependable.