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.dockersrc: https://github.com/githubixx/ansible-role-docker.gitversion: 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: 666docker_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 Archlinuxdocker_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/#daemondockerd_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" versiondocker_compose_version: "2.38.2"# The directory where to "docker-compose" binary will be installeddocker_compose_bin_directory: "/usr/local/bin"# Owner of the "docker-compose" binarydocker_compose_bin_owner: "root"# Group of the "docker-compose" binarydocker_compose_bin_group: "root"# File permissions of "docker-compose" binarydocker_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_hostsroles:
- 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