ansible-role-docker

Installs Docker from official Docker binaries archive (no PPA or apt repository). For managing Docker daemon systemd is used. Should work with basically every Linux OS using systemd.

Versions

I tag every release and try to stay with semantic versioning. If you want to use the role I recommend to checkout the latest tag. The master branch is basically development while the tags mark stable releases. But in general I try to keep master in good shape too. A tag like 13.0.0+29.4.3 means this is release 13.0.0 of this role and it's meant to be used with Docker version 29.4.3. If the role itself changes X.Y.Z before + will increase. If the Docker version changes XX.YY.ZZ after + will increase. This allows to tag bugfixes and new major versions of the role while it's still developed for a specific Docker release.

Changelog

Change history:

See full CHANGELOG

Recent changes:

14.0.0+29.4.3

• BREAKING

  • remove Debian 11 support

• UPDATE

  • update Docker to v29.4.3
  • add Ubuntu 26.04 support
  • add Debian 13 support
  • update docker-compose binary only when needed
  • ensure needed kernel modules for Docker are loaded
  • ensure python3-apt installed on Archlinux + Debian based OSes

• MOLECULE

  • use own githubixx Vagrant boxes
  • update tests

• OTHER CHANGES

  • update .yamllint
  • truthy value should be "true" / fix file permissions
  • fix line length in .github/workflows/release.yml

13.1.0+28.3.2

• UPDATE

  • Automatically detect system type (e.g. darwin, linux, etc) and architecture types (e.g. x86_64, aarch64, arm64, etc (contribution by @prakasa1904)

• MOLECULE

  • Archlinux Vagrant box needs nameserver entry in /etc/resolv.conf to make DNS resolution work

13.0.0+28.3.2

• UPDATE

  • update Docker to v28.3.2
  • update Docker Compose to v2.38.2

• MOLECULE

  • Use generic/arch Vagrant box instead of archlinux/archlinux (no longer available)
  • Install openssl package for Archlinux
  • Install archlinux-keyring for Archlinux
  • Removed Ubuntu 20.04 because reached end of life
  • Remove vars/ubuntu-20.yml as Ubuntu 20.04 support was dropped
  • Removed 'Upgrade the whole system' task

• OTHER CHANGES

  • update .yamllint
  • fix ansible-lint issues
  • add .ansible directory to .gitignore

Installation

• Directly download from Github (Change into Ansible roles directory before cloning. You can figure out the role path by using ansible-config dump | grep DEFAULT_ROLES_PATH command):
  git clone https://github.com/githubixx/ansible-role-docker.git

• Via ansible-galaxy command and download directly from Ansible Galaxy:
  ansible-galaxy role install githubixx.docker

• Create a requirements.yml file with the following content (this will download the role from Github) and install with
  ansible-galaxy role install -r requirements.yml (change version if needed):

---
roles:
  - name: githubixx.docker
    src: https://github.com/githubixx/ansible-role-docker.git
    version: 14.0.0+29.4.3

Role Variables

# Directory to store downloaded Docker archive and unarchive binary files.
docker_download_dir: "/opt/tmp"

# Docker version to download and use.
docker_version: "29.4.3"
docker_user: "docker"
docker_group: "docker"
docker_uid: 666
docker_gid: 666

# Directory to store Docker binaries. Should be in your search PATH!
docker_bin_dir: "/usr/local/bin"

# Kernel modules required for Docker bridge networking on minimal hosts.
docker_kernel_modules:
  - overlay
  - br_netfilter
  - bridge
  - veth

# For Archlinux the values of this variable can either be "iptables" or
# "nftables". For all other OSes "iptables" is a requirement as Docker
# depends on "iptables" command. In case of Archlinux "nftables" also
# includes "iptables" so both work.
#
# Ubuntu 22.04, 24.04 and Debian 11 allows to install "iptables" and "nftables"
# in parallel.
#
# So for Archlinux if either "iptables" or "iptables-nft" package is
# already installed this role won't change anything. For all other OSes
# "iptables" package is a requirement. So even if "nftables" package is
# already installed this role will install "iptables" package.
#
# Possible values:
# - iptables # Possible for all supported OSes
# - nftables # Only for Archlinux
docker_firewall_flavor: "iptables"

# Settings for "dockerd" daemon. Will be provided as parameter to "dockerd" in
# systemd service file for Docker. These variables and it's values can be
# overridden with `dockerd_settings_user` variable. Also additional variables
# can be added of course. For possible values see:
# https://docs.docker.com/engine/reference/commandline/dockerd/#daemon
dockerd_settings:
  "host": "unix:///run/docker.sock"
  "log-level": "info"
  "storage-driver": "overlay2"
  "iptables": "true"
  "ip-masq": "true"
  "mtu": "1500"

# To override settings defined in `dockerd_settings` this variable can be
# used. Of course additional variables can be added too. The example below
# would add the "--debug=true" switch to `dockerd` e.g. For possible values
# see:
# https://docs.docker.com/engine/reference/commandline/dockerd/#daemon
# dockerd_settings_user:
#   "debug": "true"

# The directory from where to copy the Docker CA certificates. By default this
# will expand to user's LOCAL $HOME (the user that run's "ansible-playbook ..."
# plus "/docker-ca-certificates". That means if the user's $HOME directory is
# e.g. "/home/da_user" then "docker_ca_certificates_src_dir" will have a value
# of "/home/da_user/docker-ca-certificates".
docker_ca_certificates_src_dir: "{{ '~/docker-ca-certificates' | expanduser }}"

# The directory where the program "update-ca-certificates" searches for CA
# certificate files (besides other locations).
docker_ca_certificates_dst_dir: "/usr/local/share/ca-certificates"

# Currently only "standalone" is supported. So that means on the remote host
# "docker-compose" command will be available and not the "docker compose"
# plugin (without "-").
# When commented no "docker-compose" will be installed and all "docker_compose_*"
# variables are ignored.
# docker_compose_type: "standalone"

# "docker-compose" version
docker_compose_version: "2.38.2"

# The directory where to "docker-compose" binary will be installed
docker_compose_bin_directory: "/usr/local/bin"

# Owner of the "docker-compose" binary
docker_compose_bin_owner: "root"

# Group of the "docker-compose" binary
docker_compose_bin_group: "root"

# File permissions of "docker-compose" binary
docker_compose_bin_file_perm: "0755"

Variables with no defaults:

# If you've a Docker registry with a self signed certificate you can copy the
# certificate authority (CA) file to the remote host to the CA certificate store.
# This way Docker will trust the SSL certificate of your Docker registry.
# It's important to mention that the CA files needs a ".crt" extension!
# "docker_ca_certificates" is a list so you can specify as much CA files as
# you want. The Ansible role will lookup for the files specified here in
# "docker_ca_certificates_src_dir" (see above). If "docker_ca_certificates"
# is not specified the task will be ignored.
docker_ca_certificates:
  - ca-docker.crt

The settings for dockerd daemon defined in dockerd_settings can be overridden by defining a variable called dockerd_settings_user. You can also add additional settings by using this variable. E.g. if you add the following variables and their values to group_vars/all.yml (or where ever it fit's best for you) dockerd the default settings will be overridden (see above):

dockerd_settings_user:
  "host": "unix:///var/run/docker.sock"
  "log-level": "error"
  "storage-driver": "aufs"
  "iptables": "false"
  "ip-masq": "false"
  "mtu": "1400"

Of course you can add more settings.

Upgrading Docker

If you want to upgrade Docker update docker_version accordingly and run ansible-playbook. The role compares the installed Docker version with docker_version and downloads or reinstalls the binaries when the versions differ. This causes systemd to restart docker.service.

You can still use --extra-vars="upgrade_docker=true" to force a reinstall even if the installed version already matches docker_version. The same flag also forces a reinstall of the standalone docker-compose binary when enabled.

To avoid restarting all Docker daemons on all of your hosts at once consider using --limit or reduce parallel Ansible tasks with --forks.

Example Playbook

- hosts: docker_hosts
  roles:
    - githubixx.docker

Testing

This role has a small test setup that is created using Molecule, libvirt (vagrant-libvirt) and QEMU/KVM. Please see my blog post Testing Ansible roles with Molecule, libvirt (vagrant-libvirt) and QEMU/KVM how to setup. The Molecule test configuration is available in this repository.

Afterwards molecule can be executed:

molecule converge

This will setup a few virtual machines (VM) with different supported Linux operating systems and installs docker role.

To run a few tests:

molecule verify

To clean up run

molecule destroy

License

GNU GENERAL PUBLIC LICENSE Version 3

Author Information

http://www.tauceti.blog