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
| Module | Job |
|---|---|
| community.docker.docker_image | Pull, build, or remove images |
| community.docker.docker_container | Create, start, stop, and remove containers |
| community.docker.docker_network | Manage networks |
| community.docker.docker_volume | Manage volumes |
| community.docker.docker_compose_v2 | Run Docker Compose projects |
| community.docker.docker_login | Sign in to a registry |
| community.docker.docker_prune | Remove 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_policyso containers survive reboots - Use
docker_container_infoto 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.
