From b59e806541bd615581f37e1a460157120d53b6a3 Mon Sep 17 00:00:00 2001 From: Andrea Tosatto Date: Sun, 10 Nov 2019 14:07:44 +0100 Subject: [PATCH] Improve the role documentation (#53) --- README.md | 95 ++++++++++++++++++++--------------- defaults/main.yml | 6 +-- meta/main.yml | 13 +++-- tasks/setup-swarm-cluster.yml | 2 +- 4 files changed, 64 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index bc839a9..04be1c9 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,55 @@ -Ansible Role: Docker Swarm -========================== +# Ansible Role: Docker [![Build Status](https://travis-ci.org/atosatto/ansible-dockerswarm.svg?branch=master)](https://travis-ci.org/atosatto/ansible-dockerswarm) -[![Galaxy](http://img.shields.io/badge/galaxy-atosatto.docker--swarm-blue.svg?style=flat-square)](https://galaxy.ansible.com/atosatto/docker-swarm) +[![License](https://img.shields.io/badge/license-MIT%20License-brightgreen.svg)](https://opensource.org/licenses/MIT) +[![Ansible Role](http://img.shields.io/badge/galaxy-atosatto.docker--swarm-blue.svg?style=flat-square)](https://galaxy.ansible.com/atosatto/docker-swarm) +[![GitHub tag](https://img.shields.io/github/tag/atosatto/ansible-dockerswarm.svg)](https://github.com/atosatto/ansible-dockerswarm/tags) -Setup a Docker Swarm cluster on RHEL/CentOS and Debian/Ubuntu servers -using Docker Engine's "Swarm Mode" (https://docs.docker.com/engine/swarm/). +Setup a Docker on RHEL/CentOS and Debian/Ubuntu servers. +The role supports Docker Engine's "Swarm Mode" (https://docs.docker.com/engine/swarm/) to create a cluster of Docker nodes. -Requirements ------------- +## Requirements An Ansible 2.3 or higher installation. -Role Variables --------------- +## Dependencies -Available variables are listed below, along with default values (see defaults/main.yml): +None. + +## Role Variables + +Available variables are listed below, along with default values (see `[defaults/main.yml](defaults/main.yml)`): + + docker_repo: "{{ docker_repo_ce_stable }}" + +The repository proving the Docker packages. +The [Docker Community](https://www.docker.com/docker-community) stable repository is configured by default. +Additional repositories are defined in `[vars/main.yml](vars/main.yml)` including the edge, test and nightly repositories. +To skip the configuration of the repository and use the system repositories set `skip_repo: true`. + + docker_package_name: "docker-ce" + +Name of the package providing the Docker daemon. - docker_repo: main - # docker_repo: testing - # docker_repo: experimental + docker_package_version: "" -The repo from which install Docker. Override the default to install -testing or experimental docker builds. +Version of the Docker package to be installed on the target hosts. +When set to `""` the latest available version will be installed. docker_dependencies: "{{ default_docker_dependencies }}" -Extra packages that have to installed together with Docker. -The value of `default_docker_dependencies` depends on the target OS family. -> **NB**: If you are installing Docker on a Raspberry running Raspbian or any other Debian-like OS make sure to set -`docker_dependencies: [ ]` otherwise Ansible will fail because the `linux-image-extra-virtual` package is not available for the `arm` architecture (see issue #4). +Additional packages to be installed by the role. +See `[vars/RedHat.yml](vars/RedHat.yml)` and `[vars/Debian.yml](vars/Debian.yml)` for the definition of the `default_docker_dependencies` variable. + + docker_service_state: "started" + docker_service_enabled: "yes" + +State of the Docker service. + + docker_daemon_config: {} + +Dictionary of Docker deamon configuration options to be written to `/etc/docker/daemon.json`. +See [Daemon configuration file](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file) for the detailed documentation of the available options. docker_swarm_interface: "{{ ansible_default_ipv4['alias'] }}" @@ -37,29 +57,28 @@ Setting `docker_swarm_interface` allows you to define which network interface wi docker_swarm_addr: "{{ hostvars[inventory_hostname]['ansible_' + docker_swarm_interface]['ipv4']['address'] }}" -By default, the ip address for raft API will be taken from desired interface. -You can setup listening address where the raft APIs will be exposed, overriding -the `docker_swarm_addr` variable value in your playbook. +Listen address for the Swarm raft API. +By default, the ip address of `docker_swarm_interface`. docker_swarm_port: 2377 -Listening port where the raft APIs will be exposed. +Listen port for the Swarm raft API. - docker_admin_users: + docker_group_name: "docker" + docker_group_users: - "{{ ansible_user }}" -The list of users that has to be added to the `docker_group` to interact with the Docker daemon. +Name of the Docker group and list of users to be added to `docker_group_name` to manage the Docker daemon. **NB**: The users must already exist in the system. - skip_engine: False - skip_group: False - skip_swarm: False - skip_docker_py: False + skip_repo: false + skip_engine: false + skip_group: false + skip_swarm: false + skip_docker_py: false -Setting `skip_engine: True` will make the role skip the installation of `docker-engine`. -If you want to use this role to just install `docker-engine` without enabling `swarm-mode` set `skip_swarm: True`. -To skip the tasks adding the `docker_admin_users` to the `docker_group` set `skip_group: True`. -Finally, the `docker-py` installation task can be skipped setting `skip_docker_py` to `True`. +Switches allowing to disable specific functionalities of the role. +If you want to use this role to install `docker-engine` without enabling `swarm-mode` set `skip_swarm: true`. Swarm node labels ----------------- @@ -93,13 +112,7 @@ You can assign labels to cluster running playbook with `--tags=swarm_labels` **NB**: Please note, all labels that are not defined in inventory will be removed -Dependencies ------------- - -None. - -Example Playbook ----------------- +## Example Playbook $ cat inventory swarm-01 ansible_ssh_host=172.10.10.1 @@ -143,7 +156,7 @@ The `MOLECULE_DRIVER_NAME` and `MOLECULE_TARGET_DISTRO` allows to change the Mol $ MOLECULE_DRIVER_NAME=vagrant MOLECULE_TARGET_DISTRO=ubuntu-1604 tox -To test the role on Ubuntu instead of CentOS set the +To test the role on Ubuntu instead of CentOS set the License ------- diff --git a/defaults/main.yml b/defaults/main.yml index 7aa66af..aa208ae 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -1,5 +1,8 @@ --- +# Repository to be used for the installation of the Docker packages +docker_repo: "{{ docker_repo_ce_stable }}" + # Name of the package providing Docker docker_package_name: "docker-ce" @@ -11,9 +14,6 @@ docker_package_version: "" # Set it to 'latest' to upgrade Docker. docker_package_state: present -# Repository to be used for the installation of the Docker packages -docker_repo: "{{ docker_repo_ce_stable }}" - # Extra packages that have to be installed together with Docker # e.g. linux-image-extra-virtual on some Debian systems docker_dependencies: "{{ default_docker_dependencies }}" diff --git a/meta/main.yml b/meta/main.yml index 5e6901a..f9c2d22 100644 --- a/meta/main.yml +++ b/meta/main.yml @@ -3,7 +3,7 @@ galaxy_info: author: Andrea Tosatto description: Setup a Docker Swarm Cluster on Centos/RHEL, Ubuntu/Debian. - min_ansible_version: 2.2 + min_ansible_version: 2.3 license: MIT issue_tracker_url: https://github.com/atosatto/ansible-dockerswarm/issues @@ -13,15 +13,14 @@ galaxy_info: - 7 - name: Ubuntu versions: - - trusty - - utopic - - vivid - - wily + - disco + - cosmic + - bionic - xenial - name: Debian versions: - - etch - - jessie + - buster + - stretch galaxy_tags: - docker - swarm diff --git a/tasks/setup-swarm-cluster.yml b/tasks/setup-swarm-cluster.yml index 35b98b9..b15dd8a 100644 --- a/tasks/setup-swarm-cluster.yml +++ b/tasks/setup-swarm-cluster.yml @@ -1,6 +1,6 @@ --- -- name: Create a custom swarm network. +- name: Create a custom Swarm network. docker_network: name: docker_gwbridge driver_options: