Using Ansible with Docker to Automate Container Management

Using Docker to run your applications is great for consistency and portability. But setting up a Docker environment isn’t always straightforward. It still requires:

• Installing Docker
• Configuring the Docker daemon
• Setting up networking and permissions
• Managing dependencies and firewall rules
• Building and running Docker images

Completing these tasks manually might be fine for a few machines, but not if you’re working with a larger setup or scaling out.

That’s where Ansible comes in. 

Using Ansible to manage Docker simplifies the automation of the container lifecycle, particularly across multiple hosts. Ansible can install Docker, deploy containers, manage images, configure networks, and handle orchestration tasks using YAML playbooks without requiring agents on the target systems.

This makes it useful for integrating Docker into broader CI/CD or infrastructure pipelines, especially when Docker is just one part of the overall stack. 

Why not just use shell scripts?

You could write shell scripts instead, but they can be messy and harder to manage. They usually run line-by-line, and if something fails midway, you might end up with a half-configured server. 

That doesn’t happen with Ansible. It’s declarative, so you just tell it how the final setup should look, and it figures out how to get there. It’ll also skip previously completed steps, which makes it safe to run again and again.

So, if you’re managing Docker environments across multiple machines, using Ansible can make the process smoother, safer, and easier to scale.

Example: Ansible playbook for Docker

The following demonstrates how we can use an Ansible playbook to install specific dependency packages on your Docker servers and install the Docker Engine. 

This playbook can be used to spin up hundreds of Docker servers just by running the ansible-playbook command instead of running these steps individually on each server:

Ansible also provides you with a set of modules that can be used to perform internal Docker tasks such as running Docker containers, building images, configuring networks, and more. In the next section, we will delve deeper into all the modules Ansible offers to manage Docker.

Below is a small example of how effective Ansible can be to manage specific Docker tasks: 

The Ansible modules for managing Docker are part of the community.docker collection, which is maintained and regularly updated.  These modules help automate specific Docker-related tasks and promote idempotency across your Docker configurations.

Commonly used modules include:

• docker_container: Manages the lifecycle of Docker containers (start, stop, restart, etc.).
• docker_image: Pulls, builds, and manages Docker images.
• docker_network: Creates and manages Docker networks.
• docker_volume: Handles Docker volumes for persistent storage.
• docker_login: Manages Docker registry logins.
• docker_compose: Deploys applications using Docker Compose files.
• docker_prune: Removes unused Docker resources.
• docker_swarm, docker_service: For managing Docker Swarm and services.
  

To use the Docker modules, you will need to first install the collection on your Ansible control node by running the following:

1. docker_container module

The docker_container module allows you to use commands such as docker run, docker stop, docker restart, and docker rm. It also allows you to specify the ports, environment variables, and volumes you want to use for that container.

Example 1: Starting a Docker container (NGINX)

Example 2: Bind mounting volumes and setting environment variables

2. docker_image

The docker_image module lets you pull, build, and remove images from a Docker server. It can be very useful when you want to streamline your deployments through a CI/CD pipeline.

Example 1: Pulling the latest Redis image

Example 2: Building an image from a local directory

Example 3: Removing an image

3. docker_network

The docker_network module allows you to create and manage Docker networks.

Example: Creating a Bridge Network and attaching a container to that network

5. docker_volume

In Docker, we often need to maintain some level of persistent data. The docker_volume module can deploy Docker volumes to store persistent data and remove volumes.

Example 1: Creating and mounting a Docker volume

Example 2: Removing a Docker volume

6. docker_login

The docker_login module can assist in logging into private Docker repositories and pulling an image right from your Ansible playbook run:

7. docker_compose

If your Docker environment is running from Docker Compose, Ansible also supports this. You just need to specify the directory that contains your docker-compose.yml file. 

This approach can be useful for a multi-container environment.

You can also apply conditionals within Ansible, which can be beneficial in triggering your workflows. Conditionals allow you to manipulate the way your containers are run and avoid unexpected changes. 

For example, typically, you would want to recreate your Docker containers if a new image is being pulled. Here, you can apply a conditional to recreate your Docker container when the image being used by that container changes. 

Example: Using Ansible modules to manage your Docker application

The following example shows a high-level application deployment using Docker with Ansible to demonstrate a real-world scenario of using Ansible to manage your Docker application. 

From installing Docker, pulling the Docker image, to deploying the application container:

Overall, Ansible supports all these modules to manage your Docker application and automate the manual steps involved in your workflows.

In the previous examples, we installed Docker through Ansible simply by adding the Docker repository and installing docker-ce. However, in a real-world scenario, you will need to install a couple of prerequisites and also have other Docker components installed and configured. 

In this section, we will explore a full Docker installation using Ansible.

Before continuing, it is important to have a separate inventory file that lists all the servers you want to deploy and configure Docker onto. The following is a sample inventory file:

To install Docker, you will need the following prerequisites installed on the server before triggering a Docker install:

•  apt-transport-https
•  ca-certificates
• curl
• gnupg
• lsb-release

You can install these prerequisites by using an Ansible loop in your Ansible playbook as shown below:

Once you have the prerequisites installed, you can add the Docker GPG keys for the Docker repository and the repository itself and trigger the install:

It is also best practice to make sure the Docker service is fully on and ready to be used with the following task:

Adding the following is optional, but it is recommended to have a separate Docker group and separate users added to that group for Docker access:

You can also utilize the task below to ensure the Docker service is fully available before continuing to any key Docker deployment step to avoid any playbook failures:

These steps are necessary to automate the installation of Docker on your server, preventing you from having to go through multiple servers and install/configure Docker. 

Installing Docker with Ansible roles

You can also convert these installation steps into an Ansible role to simplify it even further. You can create an Ansible role, such as docker_install, and have all the tasks listed under a main.yml. Here is a high-level structure of the role:

Now, all you have to do in your playbooks is call the docker_install role as follows to install Docker:

In this section, we will show various ways you can use Ansible to manage your Docker environment.

1. Control Docker environment startup order

In a Docker environment where the database, cache, and application are containerized, it is important to ensure the database and other dependent containers are up and running before the application container gets triggered so that the application can run properly without any errors.

With Ansible, we can orchestrate this process and ensure there is proper timing in place for the services to start up before the application container is triggered. 

In the following playbook, we are using:

• PostgreSQL database container
• Redis cache container 
• Node.js application container. 

We need to ensure there are proper mechanisms for all the dependent services: 

2. Rolling updates with Ansible

To deploy a new Docker image to our existing containerized application, we will need a strategy with no downtime for our application. We can also use Ansible to assist us in properly rolling out our new image to all our containers. 

In the following example, we have a set of Docker containers spread across five servers. To avoid bringing down the entire application, we will utilize Ansible’s serial feature, which allows us to perform a clean image rollout to each server one at a time. 

3. Manage containers without Docker modules

Managing the Docker environment with Ansible doesn’t always need to be through the Ansible Docker module collection. You may experience a scenario where the Docker module isn’t fulfilling the required task. You can utilize the shell module to run Docker commands on your servers. 

In the following example, we are performing a one-time DB migration command within a container:

You can also use the shell module to run the Docker logs command to retrieve container logs: 

This approach can also help extract a list of containers to a text file: 

As you can see, this approach increases flexibility in managing your Docker environment. 

4. Backup Docker volume

You can also use Ansible to backup Docker volumes by spinning up a separate Alpine container:

To build Docker images using Ansible and automate the docker build process, you can use the docker_image module.

In the following examples, we will go over different ways we can use the docker_image module: 

1. Building an image from a local Dockerfile: 

2. Building an image from a Git repository:

3. Passing in build arguments (Pass in environment variables/secrets.):

4. Cleaning the image build without cache:

5. Force image build even if the image exists:

6. Build and push the image to the registry:

In this section, we will demonstrate deploying a full web application on Docker using Ansible. 

For this demo, we are hosting an Apache Airflow application. This open-source data platform schedules, authors, and monitors data workflows and pipelines. The technology stack used in this deployment will include a PostgreSQL database, Redis Cache, and the Apache Airflow application. 

We will also be placing all our configurations in a docker-compose file based on Apache Airflow documentation.

The following will be our file structure for this deployment: 

Starting off with the inventory file, this will include the server host name/IP address:

We will be passing in our Airflow UID through environment variables listed in our .env file:

The docker-compose file will include all the containers we will be deploying, along with all the necessary configurations required for a full Airflow Application Deployment: 

And, finally, here is our main playbook we will use to deploy our Docker environment for Airflow, which is Docker, creating the necessary directories for Airflow, copying over the docker-compose file, and starting all the containers: 

If we have an updated image from Airflow, we can use Ansible to update all our existing Docker containers. 

We can utilize Jinja templating to pass in image versions into a variable in our docker-compose.yml Jinja template, which can be copied over to our main docker-compose.yml file. 

Let’s start by declaring the image tag on a group_vars file (group_vars/all.yml), we will be going from the Airflow image version 3.0.1 to 3.1.0:

We have our entire docker-compose.yml file in a file called docker-compose.yml.j2, but we  only replace specific areas in this file to support our airflow image tag: 

Now we can create a new playbook for updating the airflow version (airflow_version_update.yml), which will:

• Copy the Jinja template to our main docker-compose file
• Pull the latest Airflow image will retrieve the airflow 3.1.0 version
• Restart all Docker containers using the new docker-compose file

Now we can simply run the playbook against our Airflow servers:

This approach can also be used with any other value that is in the docker-compose.yml file, increasing the flexibility of automating your docker-compose environment through Ansible. 

Following best practices to ensure your Docker environment is properly running within Ansible will ensure your playbooks are readable, reusable, secure, and easy to troubleshoot. 

1. Clean your Ansible architecture

Having a clean, organized architecture for your Ansible files is important for your application to deploy successfully and be easy to manage. 

In Ansible, you can create a role for each major function to spread out your tasks properly instead of having all the various tasks in one playbook. 

For example, you can create a separate role for installing Docker, core application, separate databases/cache, etc.

2. Use variables in your playbooks

You might have various values you need to update in your Dockerfile or in your docker-compose.yml file if you are using Docker Compose. Incorporating variables across your playbooks and files can make your deployments more dynamic and easier to manage. 

Instead of hard-coding values across multiple areas in your playbooks, you can set variables across your playbooks and manage all the variable values from one place. This approach simplifies managing your Ansible environment for a containerized application:

Instead of hard-coding image versions like this:

You can use variables as: 

Now all you have to do is just update the variable file along with our other variables:

3. Enforce idempotency across all your playbook tasks

In your playbook tasks that use Docker modules such as docker_container, avoid setting the ‘State’ to ‘restarted’, as this will force a re-create for the container every time the playbook runs. Instead, you can set the ‘State’ to ‘started’ and use the ‘recreate’ flag along with conditionals. 

Avoid using:

Use the following instead: 

4. Create an inventory file for each environment

When managing multi-environment applications through Ansible, it is recommended in any scenario to keep separate inventory files for each of those environments in order to prevent any accidental deployments: 

5. Use tags with your playbook tasks

Tags in Ansible are very powerful. They allow you to trigger certain tasks in your playbooks instead of running the entire playbook each time you run it. Combining tags with the Docker container module can give you more control over different phases in your application deployment lifecycle.

For example, if you want to start only the frontend containers in a Docker environment, set tags to that specific task and add them during the ansible-playbook command run: 

Spacelift’s vibrant ecosystem and excellent GitOps flow are helpful for managing and orchestrating Ansible. By introducing Spacelift on top of Ansible, you can easily create custom workflows based on pull requests and apply any necessary compliance checks for your organization.

Another advantage of using Spacelift is that you can manage infrastructure tools like Ansible, Terraform, Pulumi, AWS CloudFormation, and even Kubernetes from the same place and combine their stacks with building workflows across tools.

You can bring your own Docker image and use it as a runner to speed up deployments that leverage third-party tools. Spacelift’s official runner image can be found here.

Our latest Ansible enhancements solve three of the biggest challenges engineers face when they are using Ansible:

• Having a centralized place in which you can run your playbooks
• Combining IaC with configuration management to create a single workflow
• Getting insights into what ran and where

Provisioning, configuring, governing, and even orchestrating your containers can be performed with a single workflow, separating the elements into smaller chunks to identify issues more easily.

Would you like to see this in action, or just get an overview? Check out this video showing you Spacelift’s Ansible functionality:

If you want to learn more about using Spacelift with Ansible, check our documentation, read our Ansible guide, or book a demo with one of our engineers.

Using Ansible to manage Docker streamlines container operations by automating everything from image pulls and container runs to rolling updates and backups. With purpose-built Docker modules, Ansible helps define consistent, scalable deployments that reduce manual work and errors. 

This article showed how to structure roles, apply conditionals, and follow best practices, giving you a clear path to repeatable, reliable infrastructure automation.