Installing Traefik Enterprise Edition with Multiple Control Nodes on TraefikEE on Docker Swarm with Compose Files¶

This installation guide is for experts who want to fine-tune their TraefikEE (Traefik Enterprise Edition) installation.

It covers how to install TraefikEE using docker compose files in a Docker Swarm cluster.

Swarm Knowledge

Assistance with configuring or setting up a Docker Swarm cluster is not included in this guide. If you need more information related to Docker Swarm, start with the following resources:

Requirements¶

The traefikeectl tool
A Docker Swarm (swarm mode) cluster:
- Version: >= 1.13 (minimum API version 1.25)
- At least 3 manager nodes, and 1 worker node
Docker client
- Version: >= 1.13 (minimum API version 1.25)
- Configured to communicate with your swarm cluster by setting correctly the --host flag or the DOCKER_HOST environment variable, and the security options according to your setup. For more information see here.
Bootstrap and control node containers can reach https://v3.license.containous.cloud.

Ingress ports requirements

TraefikEE publishes multiple ports on your cluster 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

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

Download and Extract Compose Files¶

Command

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

Create the TraefikEE Network¶

Create the network being used by TraefikEE to communicate internally.

Command

docker network create --driver=overlay traefikee-net

Expected output

pmvxcxzucmcshro6tfpta7az2 # newly created network ID, differs per execution

Note

You can personalize the network name being used, however make sure to report it in the following commands.

Create the TraefikEE License Secret¶

Create the docker swarm secret containing your license.

Command

# With the TRAEFIKEE_LICENSE_KEY environment variable previously defined
echo -n ${TRAEFIKEE_LICENSE_KEY} | docker secret create traefikee-license -

Expected output

g7akfclckt71e0sej85doj8x4 # newly created secret ID, will difer per execution

Choose a Cluster Name¶

TraefikEE needs a common identifier called the cluster name (specified using the --clustername option) in order to recognize its resources. By default, the cluster name used by traefikeectl is traefikee, you can customize it but you will then need to specify the --clustername option for each traefikeectl command. In the following guide examples, we kept the default cluster name, thus we do not need to use the --clustername option.

Create the Bootstrap Node¶

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.

To do so, you need to edit the compose files and add the following snippet into each of them:

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:319"

Open the file ./bootstrap-node.yml with your favorite editor:
- Replace the ${TRAEFIKEE_LICENSE_SECRET} variable with the name of the secret which contains the license as described here
- Replace the ${TRAEFIKEE_SWARM_NETWORK} variable with traefikee-net (or the one you chose)
- Replace the ${TRAEFIKEE_EXPECTED_CONTROL_NODES} variable with the desired number of control nodes
- Replace the ${TRAEFIKEE_LOG_LEVEL} variable with the desired log level (among DEBUG, INFO, ERROR and WARN)
- Replace the ${TRAEFIKEE_CLUSTER_NAME} variable with the desired cluster name
- Replace the line --timeout=120 with --timeout=600
Save the file.

Note

Instead of replacing environment variables in the file, you can export them in your shell.

Create the bootstrap node to initialize the cluster:

Command

docker stack deploy --compose-file=./bootstrap-node.yml traefikee

Expected output

Creating service traefikee_bootstrap-node

Validate that your bootstrap node is up and running:

Command

docker service ls

Expected output

ID                  NAME                         MODE                REPLICAS            IMAGE                                PORTS
zlo1lgc0u436        traefikee_bootstrap-node   replicated          1/1                 store/containous/traefikee:v1.0.0

Create the Control Nodes¶

Open the file ./control-node.yml with your favorite editor:
- Replace the ${TRAEFIKEE_CLUSTER_NAME} variable with the desired cluster name traefikee
- Replace the ${TRAEFIKEE_SWARM_NETWORK} variable with traefikee-net (or the one you chose)
- Replace the ${TRAEFIKEE_CONTROL_NODE_JOIN_TOKEN} variable with the name of the secret containing the control node join token. In our casetraefikee-control-node-join-token
- Replace the ${TRAEFIKEE_PEER_ADDRESSES} variable with the address of the bootstrap node and control node service. In our case traefikee_bootstrap-node:4242,traefikee_control-node:4242
- Replace the ${TRAEFIKEE_CONTROL_NODE_REPLICAS_COUNT} variable with the number of control nodes you want to deploy. Must be an odd number
- Replace the ${TRAEFIKEE_LOG_LEVEL} variable with INFO (or DEBUG if needed)
- Replace the ${TRAEFIKEE_DASHBOARD_PORT} variable with the desired ingress port for the dashboard (default: 8080)
- Replace the ${TRAEFIKEE_CTLAPI_PORT} variable with the desired ingress port for the control API (default 55055)
Save the file.

Note

Instead of replacing environment variables in the file, you can export them in your shell.

Command

docker stack deploy --compose-file=./control-node.yml traefikee

Expected output

Creating service traefikee_control-node

Validate that your control nodes are up and running:

Command

docker service ls

Expected output

ID                  NAME                       MODE                REPLICAS            IMAGE                                 PORTS
...
t37nf8xvpw3b        traefikee_control-node     global              3/3                 store/containous/traefikee:v1.0.0   *:8080->8080/tcp
...

Remove the Bootstrap Node¶

After the deployment of control nodes, the bootstrap node will stop automatically. Please wait until it is properly stopped.

Once it is, you can run the following command to remove it from your swarm cluster.

Command

docker service rm traefikee_bootstrap-node

Expected output

traefikee_bootstrap-node

Connect traefikeectl to the New Cluster¶

Custom Control API Port

If you specified a different control API port than the default value (55055) when creating the control node, do not forget to specify the --swarm.ctlapiport option when running traefikeectl connect.

Configure traefikeectl to gain access to the new cluster.

Command

traefikeectl connect --swarm

Expected Output

Retrieving TraefikEE Control credentials...ok
Removing cluster credentials from platform...ok
Credentials saved in "$HOME/.config/traefikee/traefikee", please make sure to keep them safe as they can never be retrieved again.
✔ Successfuly gained access to the cluster. You can now use other traefikeectl commands.

One-time operation

When running traefikeectl connect, your credentials will be retrieved and stored locally on your workstation. It will not be possible to retrieve them again in the future without re-installing a TraefikEE cluster.

Remember to keep your credentials safe!

Create the Data Nodes¶

Two options are available here:

Global mode: will spawn one data node per swarm worker.
Replicated mode: will spawn a specific amount of data nodes.

Global Mode¶

Open the file ./data-node-global.yml with your favorite editor:
- Replace the ${TRAEFIKEE_CLUSTER_NAME} variable with the desired cluster name traefikee
- Replace the ${TRAEFIKEE_SWARM_NETWORK} variable with traefikee-net (or the one you chose)
- Replace the ${TRAEFIKEE_SWARM_NETWORK_AUTODISCOVERY_ENABLED} variable with false or true
- Replace the ${TRAEFIKEE_DATA_NODE_JOIN_TOKEN} variable with the name of the secret containing the data node join token. In our case, traefikee-data-node-join-token
- Replace the ${TRAEFIKEE_PEER_ADDRESSES} variable with the address of the control node service. In our case, traefikee_control-node:4242
- Replace the ${TRAEFIKEE_LOG_LEVEL} variable with INFO (or DEBUG if needed)
- Replace the ${TRAEFIKEE_HTTP_PORT} variable with 80 (or any other port you want)
- Replace the ${TRAEFIKEE_HTTPS_PORT} variable with 443 (or any other port you want)
Save the file.

Note

Instead of replacing environment variables in the file, you can export them in your shell.

Command

docker stack deploy --compose-file=./data-node-global.yml traefikee

Expected output

Creating service traefikee_data-node

Validate that your data node is up and running:

Command

docker service ls

Expected output

ID                  NAME                       MODE                REPLICAS            IMAGE                                 PORTS
t37nf8xvpw3b        traefikee_control-node   global              3/3                 store/containous/traefikee:v1.0.0   *:8080->8080/tcp
khcwbiffzocq        traefikee_data-node      global              2/2                 store/containous/traefikee:v1.0.0   *:80->80/tcp, *:443->443/tcp

Replicated Mode¶

Open the file ./data-node-replicated.yml with your favorite editor:
- Replace the ${TRAEFIKEE_CLUSTER_NAME} variable with the desired cluster name traefikee
- Replace the ${TRAEFIKEE_SWARM_NETWORK} variable with traefikee-net (or the one you chose)
- Replace the ${TRAEFIKEE_DATA_NODE_JOIN_TOKEN} variable with the name of the secret containing the data node join token. In our case, traefikee-data-node-join-token
- Replace the ${TRAEFIKEE_PEER_ADDRESSES} variable with the address of the control node service. In our case, traefikee_control-node:4242
- Replace the ${TRAEFIKEE_DATA_NODE_REPLICAS_COUNT} variable with the amount of data nodes you want
- Replace the ${TRAEFIKEE_LOG_LEVEL} variable with INFO (or DEBUG if needed)
- Replace the ${TRAEFIKEE_HTTP_PORT} variable with 80 (or any other port you want)
- Replace the ${TRAEFIKEE_HTTPS_PORT} variable with 443 (or any other port you want)
Save the file.

Note

Instead of replacing environment variables in the file, you can export them in your shell.

Command

docker stack deploy --compose-file=./data-node-replicated.yml traefikee

Expected output

Creating service traefikee_data-node

Validate that your data node is up and running:

Command

docker service ls

Expected output

ID                  NAME                       MODE                REPLICAS            IMAGE                                 PORTS
t37nf8xvpw3b        traefikee_control-node   global              3/3                 store/containous/traefikee:v1.0.0   *:8080->8080/tcp
c4e7eqjir9gk        traefikee_data-node      replicated          1/1                 store/containous/traefikee:v1.0.0   *:80->80/tcp, *:443->443/tcp

Validate your Deployment¶

You can use traefikeectl list-nodes from inside a control node container to see the nodes of your TraefikEE cluster.

Command

traefikeectl list-nodes

Expected Output

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

Configure your TraefikEE Cluster¶

You can use traefikeectl deploy to configure your cluster.

Command

traefikeectl deploy --docker.swarmmode

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.

What's Next?

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