Installing Traefik Enterprise Edition on Docker Swarm¶

This page guides you through the installation of TraefikEE (Traefik Enterprise Edition) on Docker Swarm Mode.

Docker Knowledge

Assistance with configuring or setting up a Docker Swarm Mode cluster are not included in this guide. If you need more information about Docker and Swarm, start with the following resources:

Requirements¶

The traefikeectl tool
A Docker Swarm cluster:
- Supported versions: 17.06 to 18.09
- At least 1 manager swarm node and 1 worker swarm node
Bootstrap and control node containers can reach https://v3.license.containous.cloud.

Accessing the swarm cluster

Just like the Docker CLI, traefikeectl relies on the same environment variables to set up its connection with your swarm cluster.

If you are installing on a remote cluster, please make sure to have the DOCKER_HOST, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY environment variables properly configured before using traefikeectl.

One-Line Installation¶

Installation behind a proxy

In order to be able to install TraefikEE behind a proxy, you must define the HTTP_PROXY and HTTPS_PROXY environment variables for each TraefikEE container.

In other words, you need to customize the compose files and add the following snippet into each of them, and perform a customized one-line installation.

services:
  control-node: # or bootstrap-node or data-node.
    # [...]
    environment:
      HTTP_PROXY: "http://127.0.0.1:3129"
      HTTPS_PROXY: "http://127.0.0.1:3129"

To install TraefikEE in Docker Swarm Mode, use the traefikeectl install command line described in the Getting Started page. By default, the traefikeectl install command line deploy a cluster with 1 Control Node and 2 Data Nodes. Adding the option --swarm allows installing TraefikEE in a Swarm cluster:

Command

traefikeectl install \
  --licensekey="XXXXXXXXX" \
  --dashboard \
  --swarm

Install a cluster with more than one Control Node

To install a TraefikEE cluster with more than one control node, set the option --controlnodes to the number of control nodes you want. Only an odd number of control node is accepted.

Command

traefikeectl install \
  --licensekey="XXXXXXXXX" \
  --dashboard \
  --swarm \
  --controlnodes=3 \
  --datanodes=4

Configure your Ingress

TraefikEE publishes multiple ports to the swarm ingress routing mesh to handle external traffic:

The HTTP and HTTPS ports (default: 80 and 443) one the data-node service
The Control API port, used by traefikeectl to communicate with traefikee (default: 55055), and the dashboard port, where the dashboard is served (default: 8080) on the control-node service

All those ports are customizable with traefikeectl using the following options: --swarm.http, --swarm.https, --swarm.dashboard and --swarm.ctlapi.

Customizing the ports can be useful if the standard ports are already used or in order to run multiple clusters in parallel.

The previous command installs TraefikEE on your Docker Swarm infrastructure, with the following elements:

A Control Plane on Docker Swarm managers
A Data Plane on Docker Swarm workers

All the available installation options are listed on the traefikeectl Reference Page.

Customizing the One-Line Installation¶

Under the hood, traefikeectl relies on multiple compose files to perform the installation. To fully customize your setup and leverage the automatic traefikeectl installation, you can download and tweak those compose files and make traefikeectl use your customized version instead of the original ones, using the --swarm.composefilespath option.

Getting the Compose Files¶

Command

# In a subdirectory only containing compose files, here `./compose`
curl -sSL \
    https://s3.amazonaws.com/traefikee/examples/v1.2.1/swarm/traefikee-swarm-v1.2.1.tar.gz | tar xvz

Expected output

./bootstrap-node.yml
./control-node.yml
./data-node-global.yml
./data-node-replicated.yml
./single-control-node.yml

Custom Installation¶

Using the option --swarm.composefilespath, you can tell traefikeectl to use your customized compose files.

Command

traefikeectl install \
  --licensekey="XXXXXXXXX" \
  --dashboard \
  --swarm.composefilespath="./compose"
  --swarm

Validate Installation¶

Validate that the TraefikEE cluster is installed correctly:

Command

traefikeectl list-nodes

Expected Output One Control Node

Name          Availability  Role          Leader
----          ------------  ----          ------
e51a496c9ebc  ACTIVE        CONTROL NODE  YES
6222392b53dc  ACTIVE        DATA NODE
bfd19ebc1afa  ACTIVE        DATA NODE

Expected Output More than one Control Node

Name          Availability  Role          Leader
----          ------------  ----          ------
e51a496c9ebc  ACTIVE        CONTROL NODE  YES
d3eeec1dbfd1  ACTIVE        CONTROL NODE
77bd1afab740  ACTIVE        CONTROL NODE
6222392b53dc  ACTIVE        DATA NODE
bfd19ebc1afa  ACTIVE        DATA NODE

Your TraefikEE on Docker Swarm cluster is ready.

Backup your Installation¶

Don't forget to setup regular backups using the traefikeectl backup command. More information can be found in the backup and restore documentation.

Uninstall¶

The cluster can be uninstalled with traefikeectl uninstall:

Command

traefikeectl uninstall

More information about the uninstall options can be found on the traefikeectl Reference Page.

What's Next?

Now that you have an up running cluster, you can configure your routing.