Skip to content

Advanced Installation of Traefik Enterprise Edition many control nodes on 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 installed
  • 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.

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.0.2/swarm/traefikee-swarm-v1.0.2.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. In the following guide examples, the cluster name is set to clustername.

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 clustername
Creating service clustername_bootstrap-node

Validate that your bootstrap node is up and running:

docker service ls
ID                  NAME                         MODE                REPLICAS            IMAGE                                PORTS
zlo1lgc0u436        clustername_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_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 caseclustername-control-node-join-token
    • Replace the ${TRAEFIKEE_PEER_ADDRESSES} variable with the address of the bootstrap node. In our case clustername_bootstrap-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 clustername
Creating service clustername_control-node

Validate that your control nodes are up and running:

docker service ls
ID                  NAME                       MODE                REPLICAS            IMAGE                                 PORTS
t84ssl5lix70        clustername_bootstrap-node   replicated          1/1               store/containous/traefikee:v1.0.0
t37nf8xvpw3b        clustername_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 clustername_bootstrap-node
clustername_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/clustername", 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_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, clustername-data-node-join-token
    • Replace the ${TRAEFIKEE_PEER_ADDRESSES} variable with the address of the bootstrap node. In our case, clustername_bootstrap-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 clustername
Creating service clustername_data-node

Validate that your data node is up and running:

docker service ls
ID                  NAME                       MODE                REPLICAS            IMAGE                                 PORTS
t37nf8xvpw3b        clustername_control-node   global              3/3                 store/containous/traefikee:v1.0.0     *:8080->8080/tcp
khcwbiffzocq        clustername_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_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, clustername-data-node-join-token
    • Replace the ${TRAEFIKEE_PEER_ADDRESSES} variable with the address of the bootstrap node. In our case, clustername_bootstrap-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 clustername
Creating service clustername_data-node

Validate that your data node is up and running:

docker service ls
ID                  NAME                       MODE                REPLICAS            IMAGE                                 PORTS
t37nf8xvpw3b        clustername_control-node   global              3/3                 store/containous/traefikee:v1.0.0     *:8080->8080/tcp
c4e7eqjir9gk        clustername_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.