Traefik reverse-proxy Ansible role

This is an Ansible role which installs Traefik to run as a Docker container wrapped in a systemd service.

This role implicitly depends on the com.devture.ansible.role.systemd_docker_base role.

Usage

Example playbook:

- hosts: servers
  roles:
    - role: galaxy/com.devture.ansible.role.systemd_docker_base

    - role: galaxy/traefik

    - role: another_role

Example playbook configuration (group_vars/servers or other):

traefik_container_network: "{{ my_container_network }}"

traefik_uid: "{{ my_uid }}"
traefik_gid: "{{ my_gid }}"

Security hardening

To avoid the Traefik container from mounting and using the Docker UNIX socket (/var/run/docker.sock) directly, you can also make it talk to the Docker API via TCP using Tecnativa/docker-socket-proxy. The Traefik container can then run with reduced privileges (non-root user, dropped capabilities, etc).

To get this socket proxy installed, you can use the ansible-role-container-socket-proxy role.

Here's some example configuration (e.g. group_vars/servers) which optionally wires them together:

#
# Container Socket Proxy role configuration
#
container_socket_proxy_enabled: true

container_socket_proxy_uid: "{{ my_uid }}"
container_socket_proxy_gid: "{{ my_gid }}"

# Traefik requires read access to the containers APIs to do its job
container_socket_proxy_api_containers_enabled: true

#
# Traefik role configuration
#

# Base Traefik configuration here (see above).

traefik_config_providers_docker_endpoint: "{{ container_socket_proxy_endpoint if container_socket_proxy_enabled else 'unix:///var/run/docker.sock' }}"

traefik_container_additional_networks_auto: |
  {{
    ([container_socket_proxy_container_network] if container_socket_proxy_enabled else [])
  }}

traefik_systemd_required_services_list_auto: |
  {{
    ([container_socket_proxy_identifier + '.service'] if container_socket_proxy_enabled else [])
  }}

Development

pre-commit

You can optionally install a Git pre-commit hook (via mise + prek) that runs formatting and linting checks before each commit. See .pre-commit-config.yaml for which hooks are to be executed.

To install the hook, run the just command below:

just prek-install-git-pre-commit-hook

Molecule

This role supports Molecule, an Ansible testing framework designed for developing and testing Ansible collections, playbooks, and roles.

Refer to this page for details about how to utilize it.

Releases

Tags are created on the GitHub workflow by .github/workflows/autotag.yml, which asks bin/compute-next-tag.sh what the commit on main should be released as. The answer comes from the version pinned in defaults/main.yml and from the tags that already exist, so a commit that only touches documentation or CI is not released at all, and any change to the role itself is — without waiting for a dependency bump to carry it along.

bin/test-compute-next-tag.sh exercises that script against throwaway repositories, and runs as a prek hook.