Swarmroles

Ansible roles for deploying a docker swarm.

Status

Source	Shields
Project
Health
Repository
Activity

Installation

ansible-galaxy collection install joellefkowitz.swarmroles

Motivating example

Select the first member of the manager group and have them initiate a swarm.

- hosts: &swarm_initiator manager[0]
  user: root
  vars:
    - domains: example.com
  roles:
    - joellefkowitz.swarmroles.swarm_initiator

Register the first member of the manager group as the swarm_initiator and pass the swarm tokens to the rest of the manager group. Provide a list of images to pull and a docker username if the images require a login for access. An access token can be issued under the environemnt variable name DOCKER_ACCESS_TOKEN.

- hosts: manager
  user: root
  vars:
    - docker_username: joellefkowitz
    - pull_images:
        - joellefkowitz/example:0.1.0_prod

  pre_tasks: &register_swarm_initiator
    - name: Fetch the swarm initiator host
      set_fact:
        swarm_initiator: "{{groups['manager'][0]}}"

  roles:
    - role: joellefkowitz.swarmroles.swarm_manager
      swarm_join_addr: "{{ hostvars[swarm_initiator]['swarm_join_addr'] }}"
      swarm_manager_token: "{{ hostvars[swarm_initiator]['swarm_manager_token'] }}"

Perform the same registration for all members of the worker group.

- hosts: worker
  user: root
  pre_tasks: *register_swarm_initiator
  roles:
    - role: joellefkowitz.swarmroles.swarm_worker
      swarm_join_addr: "{{ hostvars[swarm_initiator]['swarm_join_addr'] }}"
      swarm_worker_token: "{{ hostvars[swarm_initiator]['swarm_worker_token'] }}"

Have a manager deploy the swarm. Copy over the compose file and any environment files required.

- hosts: *swarm_initiator
  user: root
  vars:
    - stack_name: prod
    - compose_file: docker-compose.yml
    - env_files:
        - prod.example.env
  roles:
    - joellefkowitz.swarmroles.stack_deployer

Roles

base

Installs python and setuptools

---

docker

Installs the docker engine for Ubuntu

Extends

• base

---

swarm_initiator

Initializes a docker swarm

Extends

• docker

Sets facts

• swarm_join_addr
• swarm_manager_token
• swarm_worker_token

---

swarm_manager

Joins a docker swarm as a manager and pulls a list of images.

Extends

• docker

Variables

• swarm_join_addr
• swarm_manager_token
• docker_username
• pull_images (List of strings)

Environment

• DOCKER_ACCESS_TOKEN

Notes

• Docker login will only be attempted when docker_username is defined

---

swarm_worker

Joins a docker swarm as a worker

Extends

• docker

Variables

• swarm_join_addr
• swarm_worker_token

---

stack_deployer

Deploys a stack to a docker swarm

Extends

• docker

Variables

• deploy_dir (Defaults to 'deploy')
• compose_file
• env_files (List of strings)
• stack_name

---

Tests

To run unit tests:

grunt tests:unit

To generate a coverage report:

grunt tests:coverage

Documentation

This repository's documentation is hosted on readthedocs.

To generate the sphinx configuration:

grunt docs:generate

Then build the documentation:

grunt docs:build

Tooling

To run linters:

grunt lint

To run formatters:

grunt format

Before commiting new code:

grunt precommit

This will run linters, formaters, generate a test coverage report and the sphinx configuration.

Versioning

This repository adheres to semantic versioning standards. For more inforamtion on semantic versioning visit SemVer.

Bump2version is used to version and tag changes. For example:

bump2version patch

Changelog

Please read this repository's CHANGELOG for details on changes that have been made.

Contributing

Please read this repository's guidelines on CONTRIBUTING for details on our code of conduct and the process for submitting pull requests.

Contributors

• Joel Lefkowitz - Initial work - Joel Lefkowitz

Remarks

Lots of love to the open source community!