I have transferred this role to its own collection.
In future, I will not accept or process any further pull requests or issues here.

Please use the linked collection from now on!

ansible role for docker deployment of generic container applications

• pip module ruamel.yaml

Ansible Collections

• bodsch.core in Version > 1.0.14

ansible-galaxy collection install bodsch.core

or

ansible-galaxy collection install --requirements-file collections.yml

Tested on

• Arch Linux
• Debian based
  • Debian 10 / 11
  • Ubuntu 20.10

container_reporting:
  changes: true
  failed: true

container_fail:
  error_at_launch: true

container_env_directory: /opt/container

container_registry:
  host: ''
  username: ''
  password: ''

container: []

container_pre_tasks: []
container_post_tasks: []

container_use_network: true
container_network: []

container_comparisons:
  # '*': ignore
  image: strict   # don't restart containers with older versions of the image
  env: strict     # we want precisely this environment
  labels: ignore
  
# filter container by 
container_filter:
  # ["name", "hostname", "image"]
  by: ""
  names: []
  
container_default_behavior: "compatibility"
container_clean_update_fact: true

If there is a change in the started containers, a report can be issued.
This can concern both changes and failures.

container_reporting:
  changes: true
  failed: true

If there was an error when starting a container, you can define here whether you want to ignore the error.

container_fail:
  error_at_launch: true

Defines the directory in which the environment data and the properties are persisted.

container_env_directory: /opt/container

Configures a container registry.
If host, username and password are defined, a corresponding login to the registry is also carried out.

container_registry:
  host: ''
  username: ''
  password: ''

If you need to obtain containers from more than one registry, you can also configure them accordingly (Only available from version >2.5.1):

container_registry:
  # Log into DockerHub
  - username: 'docker'
    password: 'rekcod'
  # Log into private registry and force re-authorization
  - username: 'yourself'
    password: 'secrets3'
    host: 'your.private.registry.io'
    reauthorize: true

You can define your own pre- or post-tasks.
The individual scripts are executed before or after (re)starting the containers.
For example, you can use them to remove old container images, volumes or other things.

container_pre_tasks: []
container_post_tasks: []

A few example scripts can be found under files:

• prune.sh
• list_all_container.sh
• list_all_images.sh
• remove_stopped_container.sh
• remove_untagged_images.sh
• parse_container_fact.sh

It is possible to allow the respective containers to use one (or more) network.

container_use_network: true
container_network:
  - name: docker_network
    subnet: 172.3.27.0/24
    gateway: 172.3.27.2
    iprange: 172.3.27.0/26

  - name: monitoring
    state: absent
    enable_ipv6: false
    subnet: 172.9.27.0/24
    gateway: 172.9.27.2
    iprange: 172.9.27.0/26

The default configuration for docker_container.comparisons.
Allows you to specify how properties of existing containers are compared with module options to decide whether or not to recreate/update the container.

see also

container_comparisons:
  # '*': ignore
  image: strict   # don't restart containers with older versions of the image
  env: strict     # we want precisely this environment
  labels: ignore

In a large environment, there are many containers that need to be considered during a run.
To reduce the runtime, or to roll out only certain containers, these can be filtered. The filter criteria available here are name, hostname and image.

container_filter:
  # ["name", "hostname", "image"]
  by: ""
  names: []

For example:

container_filter:
  by: hostname
  names:
    - hello-world-1

or

container_filter:
  by: image
  names:
    - busybox:latest

In older versions of the docker_container module, various module options used to have default values.
This caused problems with containers which use different values for these options.

The default value is now no_defaults.
To restore the old behavior, set it to compatibility, which will ensure that the default values are used when the values are not explicitly specified by the user.

This affects the auto_remove, detach, init, interactive, memory, paused, privileged, read_only and tty options.

see also

container_default_behavior: "compatibility"

To enable the necessary restart of a container over an error, a corresponding facts is created. This fact can be evaluated in a post-task, for example.
By default, the created fact is removed after a successful run. For test and development purposes, the deletion can be deactivated.

Please note that containers may be restarted with each new run of the role!

container_clean_update_fact: true

A list with the definition of all containers served by this role.

However, not all parameters of the docker_container module have been implemented!

For all supported parameters you should have a look at tasks/launch/launch_container.yml.

container:
  - name: workflow
    image: "{{ container_registry.host }}/workflow:{{ container_tag }}"
    pull: true
    state: started
    restart_policy: always
    dns_servers:
      - "{{ ansible_default_ipv4.address }}"
      networks_cli_compatible: true
      networks:
        - name: coremedia
      capabilities:
        - SYS_ADMIN
      volumes:
        - heapdumps:/coremedia/heapdumps
      published_ports:
        - 40380:8080
        - 40381:8081
        - 40383:40383
        - 40305:5005
      environments:
        DEBUG_ENTRYPOINT: "false"
        # ...
        HEAP_DUMP_FILENAME: workflow-server-heapdump
      properties:
        publisher.maxRecursionDepth: 600

More examples can be found here:

• molecule/default
• molecule/multiple-containe
• molecule/update-container
• molecule/update-properties
• molecule/many-properties

All environments entries are persisted to a separate environments file on the target system.

E.g. under /opt/container/${CONTAINER_NAME}/container.env

The target directory for persistence can be customized via container_env_directory.

All properties entries are persisted to a separate properties file on the target system.

E.g. under /opt/container/${CONTAINER_NAME}/${CONTAINER_NAME}.properties

The target directory for persistence can be customized via container_env_directory.

Since version 2.3, several separate properties files can be created per container. To do this, a list must be created under property_files.

Both properties and property_files can be used in parallel.

For example:

    property_files:
      - name: publisher.properties
        properties:
          # user and password for login to the staging serve
          replicator.user: 'replicator'
          replicator.password: 'replicator'
          # replicator.domain: ''
          replicator.tmp_dir: 'var/tmp'
          #
          publisher.maxRecursionDepth: 200
      - name: database.properties

If no properties is defined here, the associated file is deleted.

The idea behind the cutom_fields is to define corresponding rights in addition to the optional creation of the directories.

For example:

One can persist the data directory in the host system for a solr container and also assign the correct rights to this directory.

However, since it is also possible to mount files or sockets in the container via volumes, it is possible here to prevent the creation of a directory using ignore.

The following variables can be used:

• owner
• group
• mode
• ignore

Example

    volumes:
      - /run/docker.sock:/run/docker.sock:ro
      - /tmp/nginx:/tmp/nginx:ro
      - /dev/foo:/dev/foo:ro
      - testing3:/var/tmp/testing3:rw|{owner="999",group="1000"}
      - testing4:/var/tmp/testing4|{owner="1001",mode="0700"}

The mounts are similar to the volumes. Here, too, it is possible to create persistent directories in the host system via an extension source_handling.

With create, you can control whether the source directory should be created or not. The specification of owner and group enables the setting of access rights.

Example

    mounts:
      - source: /tmp/testing1
        target: /var/tmp/testing1
        type: bind
        source_handling:
          create: true
          owner: "1000"
          group: "1000"
          mode: "0750"
      - source: /tmp/testing2
        target: /var/tmp/testing2
        type: bind
        source_handling:
          create: true
          owner: "800"
          group: "999"
          mode: "0700"
      - source: /tmp/testing5
        target: /var/tmp/testing5
        type: bind 

Local tests are executed in a docker container.
Note that this container must provide its own docker daemon (docker-in-docker).

make
make verify
make destroy

You can call these tests with different Ansible versions:

make -e TOX_ANSIBLE=ansible_6.4
make destroy -e TOX_ANSIBLE=ansible_6.4

The currently testable Ansible versions are defined in tox.ini.

Below molecule, various tests are provided. If none is explicitly specified, default is used.
To call a special test, you can define it via -e TOX_SCENARIO=$TEST.

make -e TOX_SCENARIO=multiple-container
make destroy -e TOX_SCENARIO=multiple-container

• Bodo Schulz

Apache

FREE SOFTWARE, HELL YEAH!