DEBOPS.DOCKER_SERVER(5)

NAME
debops.docker_server - Manage Docker server using Ansible

SYNOPSIS

debops run service/docker_server [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

Docker <https://docker.com/> is a lightweight virtualization platform based on Linux kernel features that allow creation and management of isolated application environments.

The debops.docker_server role can be used to install and configure Docker service on Debian/Ubuntu hosts. To role supports installation of Docker from OS distribution repositories, as well as from the upstream repository.

GETTING STARTED

  Initial configuration

By default Docker is installed from Debian repositories. Users can enable upstream Docker APT repositories using the docker_server__upstream boolean variable. When it's set to True, the debops.extrepo Ansible role will be used to configure the repository. Upstream and Debian versions can be downgraded and upgraded as needed, but the role doesn't remove packages that are no longer needed by either version.

The docker-compose command doesn't exist when upstream Docker is installed. Users can use the docker compose subcommand instead, since Compose is implemented as a Go plugin.

The role can configure systemd-resolved service on the host to listen for DNS queries on the docker0 interface. This way, Docker containers can utilize the host's DNS resolver to resolve hostnames and FQDNs. This works with the default network configuration used by Docker.

The role can configure the firewall (via the debops.ferm role) to allow connections to ports used in Docker Swarm <https://docs.docker.com/engine/swarm/admin_guide/> mode; this is disabled by default. Currently, Swarm setup is not implemented and needs to be performed manually.

  Docker and systemd integration

Some of the Docker configuration options need to be configured via systemd units, to override command line arguments (for example the -H or --host option cannot be modified using the daemon configuration file) or define environment variables for the daemon (for example HTTP/HTTPS proxy which should be used to access external sites). This can be done using the debops.systemd Ansible role, which is included in the service/docker_server.yml playbook.

The docker_server__systemd__dependent_units variable can be used to add systemd configuration which will be applied to the host when the Docker service is configured. For example, to add HTTP proxy configuration, define this in the Ansible inventory:

docker_server__systemd__dependent_units:
  - name: 'docker.service.d/proxy.conf'
    comment: 'Proxy configuration for Docker'
    raw: |
      [Service]
      Environment="http_proxy=http://proxy.example.com:3128"
      Environment="https_proxy=http://proxy.example.com:3128"
      Environment="no_proxy=localhost,127.0.0.1,docker-registry.example.com,.corp"
    state: 'present'
    restart: 'docker.service'

This will add the /etc/systemd/system/docker.service.d/proxy.conf unit on the host and restart the docker.service unit after the playbook is finished.

  Example inventory

To configure Docker on a given remote host, it needs to be added to the [debops_service_docker_server] Ansible inventory group:

[debops_service_docker_server]
hostname

  Example playbook

Here's an example playbook that can be used to manage Docker:

---
- name: Manage Docker server
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_docker_server' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: extrepo
      tags: [ 'role::extrepo', 'skip::extrepo' ]
      extrepo__dependent_sources:
        - '{{ docker_server__extrepo__dependent_sources }}'
    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services', 'role::ferm' ]
      etc_services__dependent_list:
        - '{{ docker_server__etc_services__dependent_list }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ docker_server__ferm__dependent_rules }}'
    - role: docker_server
      tags: [ 'role::docker_server', 'skip::docker_server' ]
    - role: systemd
      tags: [ 'role::systemd', 'skip::systemd' ]
      systemd__dependent_units:
        - '{{ docker_server__systemd__dependent_units }}'

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::docker_server
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

role::docker_server:config
    Run tasks related to Docker configuration.

role::docker_server:admins
    Manage access to Docker daemon by UNIX accounts.

  Other resources

List of other useful resources related to the debops.docker_server Ansible role:

•   Manual pages: docker(1) <https://manpages.debian.org/docker(1)>, docker-run(1) <https://manpages.debian.org/docker-run(1)>, Dockerfile(5) <https://manpages.debian.org/Dockerfile(5)>, docker-compose(1) <https://manpages.debian.org/docker-compose(1)>

•   Docker <https://wiki.debian.org/Docker> page on Debian Wiki

•   Docker <https://wiki.archlinux.org/index.php/Docker> page on Arch Linux Wiki

•   Docker documentation page <https://docs.docker.com/>

•   Docker guide for Ansible <https://docs.ansible.com/ansible/latest/scenario_guides/guide_docker.html>

•   Official DebOps image in the Docker Hub: debops/debops <https://hub.docker.com/r/debops/debops> (see also Quick start with Docker)

DEFAULT VARIABLE DETAILS

Some of debops.docker_server default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  docker_server__configuration

The docker_server__*_configuration variables contain the contents of the /etc/docker/daemon.json configuration file in the form of YAML dictionary entries in a list. These entries are merged into a complete JSON file during configuration file generation. The Universal Configuration system is used to manage the file contents and can be used to easily set up all needed Docker configuration options.

Users can read the Docker documentation <https://docs.docker.com/config/daemon/> about the /etc/docker/daemon.json configuration file to learn more details about it and what can be set using this file.

  Examples

Change the default data directory of the Docker daemon (directory must be created separately, for example with the debops.resources role):

docker_server__configuration:
  - name: 'rootdir'
    config:
      'data-root': '/srv/data/docker'
    state: 'present'

Set custom object labels <https://docs.docker.com/config/labels-custom-metadata/> on the Docker daemon:

docker_server__configuration:
  - name: 'custom-labels'
    config:
      'labels':
        - 'com.example.environment=production'
        - 'com.example.storage=extfs'
    state: 'present'

Users can check the docker_server__default_configuration for the default configuration options included in the role.

  Syntax

Configuration entries are defined as YAML dictionaries with specific syntax:

name
    Required. An identifier for a particular section of the configuration, not used otherwise. Entries with the same name parameter are merged together and can affect each other in order of appearance.

config
    Required. YAML dictionary with Docker configuration options, which will be merged recursively during generation of the /etc/docker/daemon.json configuration file.

state
    Optional. If not specified or present, a given configuration will be included in the generated configuration file. If absent, a given configuration will not be included in the generated file (this cannot be used to remove existing configuration entries if they are specified in an entry with a different name). If ignore, a given configuration entry will not be evaluated during role execution.

AUTHOR
Maciej Delmanowski, Robin Schneider, Imre Jonk

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others