Ansible Role: Docker

This role helps install and set up the Docker Engine. It supports managing user credentials and adding custom storage options. It's been tested on CentOS 7.3, Debian Jessie, Ubuntu Trusty, and Ubuntu Xenial. RHEL 7.x is also supported to some extent.

Table of Contents

• Requirements
• Dependencies
• Role Variables
  • Execution Control
  • Docker Python Library
  • Docker Engine Repository
  • Docker Engine Storage Configuration
  • Docker Engine
  • Docker Engine Users and Groups
  • Docker Engine Registry Credentials
  • Container Networks
  • Container Images
  • Container Execution
• Example Playbook
• Testing and Contributing
• License
• Author Information

Requirements

This role requires Ansible 2.2 or newer for it to work properly.

NOTE: Versions 2.x.x and above of this role ONLY support the YY.MM version format (e.g. docker-ce-17.03.1). For older versions (e.g. docker-engine-1.13.1), please use the 1.x.x version of this role.

NOTE: Docker Inc. no longer provides publicly available repositories for their Enterprise Edition. Version 2.0.0 of this role removed support for enterprise repository management. However, it can still install and manage the Enterprise Edition.

Dependencies

You need the Python docker or docker-py library for anything in the role that's not simply installing Docker Engine. This role will install the correct version if you set it up that way.

NOTE: As of 4/13/2017, Ansible does not support the 2.0.2+ Python library. Support is expected in Ansible 2.4. For more details, see the GitHub issue here: https://github.com/ansible/ansible/issues/22993

Role Variables

Execution Control

These variables let you turn parts of the Docker Role on or off.

Variable Name	Default	Description
external_dependency_delay	20	Time (in seconds) between retries for external dependencies (like repositories or keyservers).
external_dependency_retries	6	Number of times to retry accessing an external dependency.
docker_manage_py	true	Installs the Python Docker library, required for managing containers, credentials, images, and networks.
docker_manage_engine_repo	true	Manages the Docker repository for installation. Supports both Open Source and Commercially Supported Repositories.
docker_manage_engine_storage	false	If true, the role manages the Docker Engine's storage driver. Do not provide storage-driver or storage-opt manually.
docker_manage_engine_users	true	Creates and manages a Docker group to allow user interactions with Docker.
docker_manage_registry_credentials	true	Manages credentials for specified registries. Requires the Docker library.
docker_manage_engine_networks	true	Enables management of Docker networks. Requires the Docker library.
docker_manage_images	true	Manages container image lifecycles. Requires the Docker library.
docker_manage_containers	true	Enables management of container execution. Requires the Docker library.

Docker Python Library

Manages installation of the Python Docker library. If you specify a version that is 2.0.0 or greater, it will replace the older docker-py package.

Variable	Default	Options	Description
docker_py_install	pip	pip or pkg	Type of installation: via pip or a package manager.
docker_py_version	-	-	The specific version of the Docker library to install; defaults to the latest version.
docker_py_pip_upgrade	true	true or false	Whether to allow pip to upgrade during installation.
docker_py_pip_extra_args	-	-	Additional arguments to pass to pip (e.g., -i <local pypi mirror>).

Docker Engine Repository

Controls the repository settings for the Docker Engine.

Variable Name	Default	Options	Description
docker_engine_architecture	amd64	amd64 or armhf	Specifies the target architecture (only armhf is supported on Ubuntu and Debian).
docker_engine_channel	stable	stable or edge	Whether to use the stable or edge release channel. More info can be found in the Docker Installation Documentation.
docker_engine_edition	ce	ce or ee	Use Community Edition (CE) or Enterprise Edition (EE); Enterprise Edition repositories cannot be managed by the role.
docker_engine_repo_gpg_key_server	sks-keyservers.net	-	Keyserver used for repository GPG key validation.
docker_engine_repo_ce_deb_gpg_key	0x8D81803C0EBFCD88	-	The GPG key for the CE Debian repository.
docker_engine_repo_ce_rpm_gpg_key	0xc52feb6b621e9f35	-	The GPG key for the CE RPM repository.

Docker Engine Storage Configuration

Manages the storage driver for the Docker Engine, among other related options.

Note: For all storage drivers, the storage_opts must be provided as an array. More specific options are available in the official Docker documentation here: https://docs.docker.com/engine/reference/commandline/daemon/

Variable Name	Default	Options	Description
docker_engine_storage_driver	-	aufs, btrfs, devicemapper, overlay	The storage driver to use with Docker Engine.
docker_engine_storage_config	-	-	A hash containing information for the specified storage driver.

Docker Engine

These settings control the Docker Engine and its daemon.

Note: If docker_manage_engine_storage is enabled, storage-opt should not be included in docker_engine_opts.

Variable Name	Default	Description
docker_engine_version	-	The Docker Engine version to install; latest will be installed if not specified.
docker_engine_env_vars	-	Key-value pairs passed as environment variables to the Docker Engine.
docker_engine_opts	-	Key-value pairs used as Docker Engine options, e.g. dns: ['8.8.8.8', '8.8.4.4'].

Docker Engine Users and Groups

Manages access for users to interact with Docker.

Variable Name	Default	Description
docker_engine_users	-	Array of usernames to be added to the Docker group, allowing them to use Docker without sudo.

Docker Engine Registry Credentials

Handles authentication for Docker registries.

Variable Name	Description
docker_registry_credentials	An array of hashes with configuration for each Docker registry.

Container Networks

Handles the creation and removal of Docker Networks.

Variable Name	Description
docker_networks	An array of hashes for Docker Network configurations.

Container Images

Manages the lifecycle of Docker images.

Variable Name	Description
docker_images	An array of hashes containing Docker Image settings.

Container Execution

Manages runtime execution of containers.

Variable Name	Description
docker_containers	An array of hashes for Docker Container configurations.

Example Playbook

Refer to the tests directory for various examples.

---
- name: docker
  hosts: all
  connection: local
  gather_facts: True
  tags:
   - 'docker'
  vars:
    docker_manage_py: true
    docker_manage_engine_repo: true
    docker_manage_engine_storage: true
    docker_manage_engine_users: true
    docker_manage_registry_credentials: true
    docker_manage_images: true
    docker_manage_containers: true
    docker_engine_version: '1.12.1'
    docker_engine_storage_driver: devicemapper
    docker_engine_storage_config:
      device: /dev/sdb
    docker_engine_env_vars:
      DOCKER_HOST: /var/run/docker.sock
      TLS_VERIFY: TRUE
    docker_engine_opts:
      dns:
        - '8.8.8.8'
        - '8.8.4.4'
    docker_engine_users:
      - vagrant
    docker_registry_credentials:
      - username: test
        password: testpass
        registry: registry.example.com
    docker_images:
      - name: nginx
        tag: '1.10.1-alpine'
    docker_containers:
      - name: nginx
        image: 'nginx:1.10.1-alpine'
    docker_networks:
      - name: testnet
        driver_options:
          com.docker.network.bridge.name: testnet1
        ipam_options:
          subnet: '10.255.13.1/24'
          gateway: '10.255.13.1'

Testing and Contributing

Please check the CONTRIBUTING.md file in the repository for details on how to contribute.

License

MIT

Author Information

Created by Bob Killen, maintained by the Department of Advanced Research Computing and Technical Services at the University of Michigan.