Skip to content

README.md

Latest commit

 

History

History
281 lines (208 loc) · 11.2 KB

README.md

File metadata and controls

281 lines (208 loc) · 11.2 KB
Raw

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 14.1.0+29.8.1 means this is release 14.1.0 of this role and it's meant to be used with Docker version 29.8.1. 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.1.0+29.8.1

  • UPDATE

    • update Docker to v29.8.1 (including bundled containerd v2.3.5 and runc v1.5.1)
    • update Docker Compose to v5.5.1
    • add opt-in Docker Compose CLI plugin and simultaneous standalone/plugin installation

  • MOLECULE

    • run Molecule idempotence and read-only verification by default

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

  • 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.1.0+29.8.1

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.8.1"
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 and 24.04 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"

# Set to "standalone" for the docker-compose command, "plugin" for the
# docker compose CLI plugin, or "both" to install both commands.
# When unset, neither form of Compose is installed.
# docker_compose_type: "standalone"

# Docker Compose version for either installation type
docker_compose_version: "5.5.1"

# Directory for the standalone docker-compose binary
docker_compose_bin_directory: "/usr/local/bin"

# Directory for the system-wide Docker CLI plugin
docker_compose_plugin_directory: "/usr/local/lib/docker/cli-plugins"

# 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

Docker Compose

Docker Compose is not installed unless docker_compose_type is set. Choose one of:

Value Command Installed binary
standalone docker-compose {{ docker_compose_bin_directory }}/docker-compose
plugin docker compose {{ docker_compose_plugin_directory }}/docker-compose
both Both commands Both paths

For example, set docker_compose_type: "plugin" to enable the Docker CLI plugin for all users, or docker_compose_type: "both" to keep scripts using the standalone command working while also enabling the plugin. The standalone destination remains /usr/local/bin; the plugin defaults to /usr/local/lib/docker/cli-plugins. Both forms use docker_compose_version and the existing binary owner, group, and permissions settings. The role downloads release binaries with upstream SHA-256 checksums and updates each selected installation when its version differs.

Changing the mode or unsetting it does not remove a binary installed previously at the other path. Upgrading an opted-in host from Compose 2 to the new Compose 5 default is a major-version change; pin docker_compose_version to the previous release if necessary.

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 each selected Compose binary when enabled. Updating Compose alone does not restart the Docker service.

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 test

This will set up virtual machines (VMs) with different supported Linux operating systems, install the docker role, check idempotence, and verify Docker's operation.

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