DEV Community

Python-T Point
Python-T Point

Posted on • Originally published at pythontpoint.in

⚙️ Ansible roles vs playbooks for Docker provisioning — which one should you use?

#ai #machinelearning #python #ansible

⚙️ Architecture — Why Ansible Roles and Playbooks Matter

Ansible roles vs playbooks Docker provisioning

Understanding the structural difference between Ansible roles and playbooks is the first step in deciding which pattern fits a Docker provisioning workflow.

📑 Table of Contents

  • ⚙️ Architecture — Why Ansible Roles and Playbooks Matter
  • 📁 Role Structure — Filesystem Layout
  • 📦 Docker Provisioning with Playbooks — Direct Task Execution
  • 🔧 Comparing Roles vs Playbooks — Trade‑offs in Docker Provisioning
  • 🧩 Composing a Scalable Docker Stack — Using Roles to Build Layers
  • 🏗️ Base Role — Docker Engine Installation
  • 🛠️ App Role — Deploy Application Container
  • 🟩 Final Thoughts
  • ❓ Frequently Asked Questions
  • Can I mix roles and inline tasks in the same playbook?
  • Do roles add significant overhead compared to a plain playbook?
  • How do I share a custom Docker role across multiple repositories?
  • 📚 References & Further Reading

📦 Docker Provisioning with Playbooks — Direct Task Execution

Playbooks can provision Docker containers without additional abstraction, suitable for one‑off deployments or simple CI pipelines.

# site.yml
- hosts: docker_hosts become: true tasks: - name: Ensure Docker engine is installed apt: name: docker.io state: present when: ansible_os_family == "Debian" - name: Pull nginx image docker_image: name: nginx source: pull - name: Run nginx container docker_container: name: web image: nginx state: started ports: - "80:80"
Enter fullscreen mode Exit fullscreen mode

What this does: (Also read: 🐍 When to choose ansible roles over playbooks)

  • Installs the Docker daemon on Debian‑based hosts.
  • Pulls the official nginx image from Docker Hub.
  • Starts a container named web exposing port 80.

Running the playbook:

$ ansible-playbook -i inventory.yml site.yml
PLAY [docker_hosts] ************************************************************ TASK [Gathering Facts] *********************************************************
ok: [host1] TASK [Ensure Docker engine is installed] **************************************
changed: [host1] TASK [Pull nginx image] ********************************************************
changed: [host1] TASK [Run nginx container] *****************************************************
changed: [host1] PLAY RECAP *********************************************************************
host1: ok=4 changed=3 unreachable=0 failed=0
Enter fullscreen mode Exit fullscreen mode

Because tasks are defined inline, the playbook is straightforward but repeats Docker‑related logic whenever another project requires the same setup.

Key point: Playbooks give immediate control over Docker provisioning steps, but they lack the modularity of roles for larger environments.

🔧 Comparing Roles vs Playbooks — Trade‑offs in Docker Provisioning

When evaluating Ansible roles vs playbooks for Docker provisioning, the decision hinges on reusability, maintainability, and execution overhead.

Aspect Roles Playbooks
Reusability High – can be imported by many playbooks Low – logic duplicated per playbook
Complexity Management Encapsulated, clear boundaries Flat, can become tangled as tasks grow
Idempotence Handlers enforce idempotent restarts Requires manual when checks
Execution Speed Initial role load adds a few milliseconds (filesystem scan and variable merging) Direct execution is marginally faster for tiny playbooks
Version Control Can be versioned as a standalone collection Versioned only within the playbook file

According to the Ansible documentation, roles are the recommended way to package reusable automation because they enforce a conventional directory layout that tools like ansible-galaxy can consume.

Choosing roles over flat playbooks is a matter of scaling the automation codebase, not just personal preference.

Key point: Roles excel in multi‑project environments where Docker provisioning logic must be shared, while playbooks shine for single‑purpose, quick‑run scenarios.

🧩 Composing a Scalable Docker Stack — Using Roles to Build Layers

Layered roles enable a full Docker stack: engine installation, network configuration, and application container deployment. (More onPythonTPoint tutorials)

🏗️ Base Role — Docker Engine Installation 

# roles/docker_engine/tasks/main.yml
- name: Install Docker package apt: name: docker.io state: present when: ansible_os_family == "Debian" - name: Enable Docker service systemd: name: docker enabled: true state: started
Enter fullscreen mode Exit fullscreen mode

What this does:

  • Installs the Docker daemon on Debian hosts.
  • Ensures the docker service starts on boot and is running.

🛠️ App Role — Deploy Application Container 

# roles/webapp/tasks/main.yml
- name: Pull application image docker_image: name: myorg/webapp tag: latest source: pull - name: Run application container docker_container: name: webapp image: myorg/webapp:latest state: started ports: - "8080:80" env: ENV: production restart_policy: always
Enter fullscreen mode Exit fullscreen mode

What this does:

  • Pulls a private image from a registry.
  • Runs the container with port mapping, environment variables, and a restart policy equivalent to systemd’s always.

Playbook that composes the roles:

# site.yml
- hosts: docker_hosts become: true roles: - docker_engine - webapp
Enter fullscreen mode Exit fullscreen mode

Execution output:

$ ansible-playbook -i inventory.yml site.yml
PLAY [docker_hosts] ************************************************************ TASK [docker_engine: Install Docker package] ********************************
changed: [host1] TASK [docker_engine: Enable Docker service] *********************************
changed: [host1] TASK [webapp: Pull application image] ****************************************
changed: [host1] TASK [webapp: Run application container] *************************************
changed: [host1] PLAY RECAP *********************************************************************
host1: ok=4 changed=4 unreachable=0 failed=0
Enter fullscreen mode Exit fullscreen mode

Because each concern lives in its own role, extending the stack—e.g., adding a monitoring sidecar—requires only a new role, leaving existing files untouched.

Key point: Layered roles turn Docker provisioning into a composable library, making future extensions trivial.

🟩 Final Thoughts

The choice between Ansible roles and playbooks for Docker provisioning reflects the size and longevity of the automation effort. For a single, ad‑hoc container launch, a concise playbook delivers the result with minimal scaffolding. When the same Docker setup must be reproduced across environments, teams, or CI pipelines, encapsulating the logic in roles provides a clean, version‑controlled abstraction that scales without duplication.

Adopting the role‑based pattern also aligns with Ansible’s broader ecosystem—roles can be published to Ansible Galaxy, consumed as collections, and governed by linting tools. This alignment reduces technical debt as the infrastructure evolves.

❓ Frequently Asked Questions

Can I mix roles and inline tasks in the same playbook?

Yes. Ansible allows a play to list both roles: and tasks:. Inline tasks run after the role’s tasks unless you explicitly order them with pre_tasks or post_tasks.

Do roles add significant overhead compared to a plain playbook?

The overhead is limited to a one‑time directory scan and variable merging, typically a few milliseconds per host, which is negligible compared to Docker image pulls or container startups.

How do I share a custom Docker role across multiple repositories?

Publish the role as an Ansible Galaxy collection or host it in a private Git repository. Consumers can then add it to requirements.yml and install it with ansible-galaxy collection install -r requirements.yml.

💡 Want to practise this hands-on? DigitalOcean gives new accounts $200 free credit for 60 days — enough to spin up a full Linux/Docker/Kubernetes environment at no cost.

📚 Recommended reading: Best DevOps & cloud books on Amazon — from Linux fundamentals to Kubernetes in production, curated for working engineers.

📚 References & Further Reading

  • Official Ansible role documentation — explains layout and best practices: docs.ansible.com
  • Docker module reference for Ansible — details parameters for docker_image and docker_container: docs.ansible.com
  • Docker Engine installation guide — official steps for Debian‑based systems: docs.docker.com

Top comments (0)