Skip to content

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

curl -sSL \
    https://s3.amazonaws.com/traefikee/examples/v1.1.1/swarm/traefikee-swarm-v1.1.1.tar.gz | tar xvz
./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.

docker network create --driver=overlay traefikee-net
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.

# With the TRAEFIKEE_LICENSE_KEY environment variable previously defined
echo -n ${TRAEFIKEE_LICENSE_KEY} | docker secret create traefikee-license -
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:

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

Validate that your bootstrap node is up and running:

docker service ls
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.

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

Validate that your control nodes are up and running:

docker service ls
ID                  NAME                       MODE                REPLICAS            IMAGE                                 PORTS
t84ssl5lix70        traefikee_bootstrap-node   replicated          1/1                 store/containous/traefikee:v1.0.0
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.

docker service rm traefikee_bootstrap-node
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.

traefikeectl connect --swarm
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.

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

Validate that your data node is up and running:

docker service ls
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.

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

Validate that your data node is up and running:

docker service ls
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.

traefikeectl list-nodes
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.

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.