DEBOPS.DOCKER_SERVER(5)

NAME
debops.docker_server - Manage Docker server using Ansible

SYNOPSIS

debops 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

Docker is available in two editions. Community Edition (CE) and Enterprise Edition (EE). Docker EE is not supported on Debian distributions. See also: Docker variants <https://docs.docker.com/install/overview/>.

The Docker package from distribution repositories will be installed by default (on Jessie it means that the jessie-backports repository needs to be available, which is the default in DebOps). You can install the upstream version of Docker by setting the docker_server__upstream: True variable in Ansible’s inventory. Upstream Docker is installed on Debian Stretch by default, since this release does not provide included Docker packages.

A Docker server managed by DebOps does not listen on any TCP ports by default. You can set docker_server__tcp to True if you need remote access to the Docker server. You will also need to tweak your firewall in this case, which is easily done with docker_server__tcp_allow. It is recommended to use the debops.pki role to secure the connection between the client and the Docker server.

On hosts with ferm firewall support enabled, a special post-hook script will be installed that restarts the Docker daemon after ferm is restarted.

The docker-compose script will be installed on hosts with upstream Docker, in a Python virtualenv. It will be automatically available system-wide via a symlink in /usr/local/bin/ directory.

To let the docker daemon trust a private registry with self-signed certificates, add the root CA used to sign the registry's certificate through the debops.pki role.

This role does not support switching from Docker CE to Docker EE on an already installed machine. It does support switching from distribution repository to upstream. However, it is recommended to start with a clean machine if possible.

The debops.docker_server role relies on configuration managed by debops.core, debops.ferm, and debops.pki Ansible roles.

  Useful variables

This is a list of role variables which you most likely want to define in Ansible inventory to customize Docker:

docker_server__tcp
    Enable or disable listening for TLS connections on the Docker TCP port.

docker_server__tcp_allow
    List of IP addresses or subnets that can connect to Docker daemon remotely over TLS.

docker_server__admins
    List of UNIX accounts that have access to Docker daemon socket.

  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: resolvconf
      tags: [ 'role::resolvconf', 'skip::resolvconf' ]
      resolvconf__enabled: True
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::docker_server' ]
      keyring__dependent_apt_keys:
        - '{{ docker_server__keyring__dependent_apt_keys }}'
    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]
      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: python
      tags: [ 'role::python', 'skip::python', 'role::docker_server' ]
      python__dependent_packages3:
        - '{{ docker_server__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ docker_server__python__dependent_packages2 }}'
    - role: docker_server
      tags: [ 'role::docker_server', 'skip::docker_server' ]

  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)

DOCKER VIRTUALENV SUPPORT

  Python and Docker relationship

Docker can be expanded or managed by a few additional Python-based tools. The company behind Docker provides a docker-compose Python script which can be used to manage multiple Docker containers at a time. Ansible provides a few Docker-related modules as well. Therefore a correctly configured Python environment is very useful on a Docker host.

The debops.docker_server Ansible role maintains a separate Python virtualenv environment just for Docker-related Python packages. This is done so that Python modules used by upstream Docker, don't affect the host Python environment. The Docker virtualenv environment is by default located in the /usr/local/lib/docker/virtualenv/ directory but it can be changed if needed.

The docker-compose script will be symlinked in the host environment, in /usr/local/bin/docker-compose, so that the command can be used from the host's shell.

The Python interpreter located in the Docker virtualenv environment will be exposed in the host environment as /usr/local/bin/docker-python. That way you can use it in the Python scripts executed in the host environment. To use the Docker Python interpreter in a script, define it's shebang line as:

#!/usr/bin/env docker-python

  Ansible modules and Docker virtualenv

The default host does not have any Docker-related Python modules available, therefore Ansible modules that interact with Docker, like docker, docker_container, docker_image, etc. will not work out of the box in normal Ansible playbooks and roles. To solve that, you can use the ansible_python_interpreter variable defined at the playbook level. Playbook variables cannot be templated by Jinja, therefore a static value must be used, and relates to the docker-python command exposed earlier.

Here's an example playbook that uses a Python interpreter from the Docker virtualenv environment:

---
- name: Set up a Redis Docker container
  collections: [ 'debops.debops' ]
  hosts: 'docker-host'
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  vars:
    # Use Python from Docker virtualenv
    ansible_python_interpreter: '/usr/bin/env docker-python'
  tasks:
    - name: Manage redis container
      docker_container:
        name: 'local-redis'
        image: 'redis'
        published_ports: [ '127.0.0.1:6379:6379' ]
        restart_policy: 'always'
        state: 'started'

Keep in mind that more extensive playbooks that use Ansible roles or modules other than the Docker-related ones might need to be executed in their own separate plays, to use the host Python interpreter instead of the one maintained in the Docker virtualenv environment. Alternatively, you need to ensure that the Docker virtualenv environment contains all needed Python modules.

  How to access the Docker virtualenv

To enter the Docker virtualenv environment on a host, execute the commands on the root account:

cd /usr/local/lib/docker/virtualenv
source bin/activate

After that you can execute usual pip commands to manage Python packages inside the environment.

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__pip_packages

The docker_server__default_pip_packages and docker_server__pip_packages list variables define what PyPI packages will be installed in the Python virtualenv environment controlled by the debops.docker_server role. You can specify either package names as string, or YAML dictionaries with specific parameters:

name
    Required. The name of the PyPI package to install.

version
    Optional. If specified, install the specified version of the PyPI package instead of the latest one.

state
    Optional. If not specified or present, the package will be installed in the Python virtualenv. If absent, the package will be removed from the Python virtualenv.

path and src
    Optional. If specified together, the role will create a symlink at the path location (should specify an absolute path) to the src file or directory.

    For example usage, see the default variables mentioned above.

AUTHOR
Maciej Delmanowski, Robin Schneider, Imre Jonk

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