Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 29 ยท Real-World Practice

Ansible with Docker, Terraform and CI/CD

Combine Ansible with Terraform, Docker and CI pipelines: provision then configure, community.docker modules, idempotent deploys and rolling updates with serial.

Ansible rarely works alone. A real delivery chain has a tool that creates machines (Terraform, a cloud console), a tool that configures them (Ansible), containers that package the application (Docker), and a pipeline that runs everything the same way every time (GitHub Actions, GitLab CI). Knowing where each tool stops and the next begins keeps your automation simple.

This lesson shows how the pieces connect: Terraform output feeding Ansible, the community.docker modules, an Ansible step inside a CI pipeline, and rolling updates with serial. For the shell-level view of the same toolchain see Automation with Ansible and Terraform, and for Docker itself start with What Is Docker?.

Terraform, Docker, a CI service and real servers cannot run on this site, so the commands, playbooks and pipeline files below are read-only. The runnable examples are JavaScript stand-ins that model the data flow (Terraform output to inventory) and the rollout logic (batches and failure limits). Each one says so.

Who does what

A useful rule: Terraform owns what exists, Ansible owns what is inside it. Terraform is good at declaring networks, virtual machines, load balancers and DNS records, and at tracking them in state. Ansible is good at packages, files, users, services and deployments on machines that already exist. Both are declarative and both aim to be idempotent, so you can re-run either one safely.

flowchart LR
  T["Terraform<br/>create servers"] --> O["Outputs<br/>(IP addresses)"]
  O --> I["Ansible inventory"]
  I --> A["Ansible playbook<br/>configure and deploy"]
  A --> S["Running service"]
  C["CI pipeline"] -.runs.-> T
  C -.runs.-> A

Terraform creates, its outputs describe what it made, Ansible configures that, and CI runs both in a repeatable order.

From Terraform to Ansible

The simplest bridge is a Terraform output. Terraform can print its outputs as JSON, and a small script (or a playbook's from_json filter) turns them into an inventory:

HCL
output "web_ips" {
  value = aws_instance.web[*].public_ip
}
Terminal
terraform output -json > tf-output.json
ansible-playbook -i inventory.ini site.yml

There are also Ansible collections that read Terraform state directly and expose its resources as inventory (look for cloud.terraform on Galaxy), and Ansible can call Terraform itself with a module, but the output-to-inventory handoff is easy to understand and debug. Another popular route is to skip the handoff entirely: tag servers in Terraform, then use a dynamic inventory plugin that groups hosts by those tags.

One practical problem is timing: a server that Terraform has just created may not accept SSH yet. Start your playbook with a wait:

YAML
- hosts: all
  gather_facts: false
  tasks:
    - name: Wait until SSH answers
      ansible.builtin.wait_for_connection:
        timeout: 300
    - name: Now gather facts
      ansible.builtin.setup:

Stand-in: Terraform output to an inventory

The code below takes an object shaped like the output of terraform output -json (the addresses are from a documentation range, not real servers) and prints an INI inventory. It is a model of the handoff, not a Terraform feature.

JS Turn Terraform outputs into an inventory

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Add a third address to web_ips and run it again: the inventory grows by one line, and so would your fleet.

Managing containers with community.docker

If your application is a container, Ansible can install Docker (with the normal package modules) and then manage containers declaratively through the community.docker collection. Install it once with ansible-galaxy collection install community.docker. These modules talk to the Docker daemon on the managed node through a Python library there, so check the collection's documentation for the exact requirement of your version.

YAML
- name: Log in to the registry
  community.docker.docker_login:
    registry_url: registry.example.com
    username: "{{ registry_user }}"
    password: "{{ registry_password }}"
  no_log: true

- name: Run the application container
  community.docker.docker_container:
    name: shop
    image: "registry.example.com/shop:{{ app_version }}"
    state: started
    restart_policy: unless-stopped
    published_ports:
      - "8080:8080"
    env:
      APP_ENV: production

The key to idempotence is the pinned image tag. If the container named shop already runs that exact image and settings, the task reports ok; if you change app_version, the module notices the difference, recreates the container, and reports changed. Using latest hides changes from Ansible, because the tag text never changes even when the image behind it does. Other useful modules are docker_image (pull, or build from a directory containing a Dockerfile), docker_network, docker_volume and docker_compose_v2 for running a Compose project (see Introduction to Docker Compose).

Building images is usually better done in CI, not on every production host: build once, push to a registry, and let Ansible only pull and run. See Docker in CI for that half and Deploying on a Single Host for the manual version of what the playbook automates.

Ansible inside a CI pipeline

A pipeline runs ansible-playbook on a clean runner, so every run starts from the same place. A GitHub Actions job might look like this:

YAML
name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Ansible
        run: pipx install ansible-core
      - name: Install collections
        run: ansible-galaxy collection install -r requirements.yml
      - name: Load the SSH key
        run: |
          install -m 700 -d ~/.ssh
          echo "${{ secrets.DEPLOY_SSH_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan -H "${{ vars.DEPLOY_HOST }}" >> ~/.ssh/known_hosts
      - name: Check the playbook
        run: ansible-playbook -i inventories/production site.yml --check --diff
      - name: Deploy
        run: ansible-playbook -i inventories/production site.yml -e app_version=${{ github.sha }}

The same shape works in GitLab CI: a job with an image that has Ansible installed, secrets in CI variables, and the same ansible-playbook command. Some habits matter more than the syntax:

  • Never print secrets. Keep keys in the CI secret store, set no_log: true on tasks that handle passwords, and use Ansible Vault for variables kept in the repository.
  • Do not turn off host key checking to make the pipeline pass. Record the host's key (as ssh-keyscan does above, ideally from a pinned, trusted source) so you are protected against impostors.
  • Run lint and a check-mode pass first (see Testing, Linting and Debugging), and require approval before the production job.
  • Pin versions of ansible-core and collections in requirements.yml so a pipeline does not change behaviour overnight.
  • Make jobs safe to re-run. If the deploy fails halfway, running it again should finish the job, which is exactly what idempotent tasks give you.

Rolling updates with serial

Updating every server at once is risky: a bad release takes the whole service down. The serial keyword makes a play run on a batch of hosts at a time, finishing the whole play on one batch before starting the next.

YAML
- hosts: app
  serial:
    - 1          # canary: one host first
    - "25%"      # then a quarter of the fleet
    - "100%"     # then everyone left
  max_fail_percentage: 20
  tasks:
    - name: Take the host out of the load balancer
      community.general.haproxy:
        backend: app
        host: "{{ inventory_hostname }}"
        state: disabled
      delegate_to: lb1

    - name: Deploy the new version
      community.docker.docker_container:
        name: shop
        image: "registry.example.com/shop:{{ app_version }}"
        state: started
        restart: true

    - name: Wait for the health check
      ansible.builtin.uri:
        url: "http://{{ inventory_hostname }}:8080/health"
        status_code: 200
      register: health
      until: health.status == 200
      retries: 10
      delay: 3

    - name: Put the host back
      community.general.haproxy:
        backend: app
        host: "{{ inventory_hostname }}"
        state: enabled
      delegate_to: lb1

Two settings protect you. max_fail_percentage aborts the whole play when the share of failed hosts in a batch goes above that number. any_errors_fatal: true is the strict version: a single failure anywhere aborts the play. A failed host is also removed from the rest of the play, so it keeps the old version while you investigate. The tasks that talk to the load balancer use delegate_to, which runs a task on a different machine while still using the current host's variables (see Handlers, Tags and Task Control).

Stand-in: a rolling update with batches

The stand-in walks six hosts in batches of 1, 2 and the rest, simulates a health check that fails on app3, and applies a failure limit. It models the decision logic of serial and max_fail_percentage, not Ansible's executor.

JS Rolling update with serial batches

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With a limit of 0 the first failure stops the rollout and three hosts never see the new version. With a limit of 60 the rollout continues past one failed host, which may or may not be what you want, so choose the number on purpose. The complete, hands-on version of this idea is Project: Deploy an Application with Rolling Updates.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which split of responsibilities is the most common?

    Terraform declares and tracks infrastructure; Ansible configures and deploys onto machines that exist. Both are re-runnable.
  2. 2. Why does docker_container with image: shop:latest often hide changes from Ansible?

    Idempotence depends on comparing the configured image reference. A pinned version or digest changes when you release; latest stays the same string.
  3. 3. What does serial: [1, "25%", "100%"] do?

    serial controls batch sizes. A first batch of one host acts as a canary before larger batches follow.
  4. 4. A pipeline fails on the SSH host key prompt. What is the safe fix?

    Disabling host key checking removes protection against man-in-the-middle attacks. Pre-loading the real key keeps the check and makes the job non-interactive.

Summary

  • Terraform owns what exists; Ansible owns what is inside it; CI runs both repeatably.
  • Pass Terraform outputs to Ansible as inventory, or use tags with a dynamic inventory plugin, and wait for SSH before configuring new machines.
  • community.docker modules manage containers idempotently when images are pinned; build and push images in CI, then let Ansible pull and run.
  • In pipelines keep secrets in the CI store, pin versions, keep host key checking, run lint and check mode first, and make jobs safe to re-run.
  • serial with max_fail_percentage (and any_errors_fatal) gives canary-style rolling updates; delegate_to handles load balancer steps.

Next: Project: Provision a Web Server.