Skip to content

Advanced Installation of Traefik Enterprise Edition On-Premise

This installation guide is for experts who want to install their TraefikEE cluster (Traefik Enterprise Edition) On-Premise.

Work In Progress

This documentation is a first version and will be improved in the next releases.

Requirements

  • In order to start a Traefikee cluster with 3 control nodes and 2 data nodes, prepare 6 Virtual Machines:
    • VM1: 10.10.0.1 → bootstrap-node
    • VM2: 10.10.0.2 → control-node-1
    • VM3: 10.10.0.3 → control-node-2
    • VM4: 10.10.0.4 → control-node-3
    • VM5: 10.10.0.5 → data-node-1
    • VM6: 10.10.0.6 → data-node-2

Virtual Machine networking

All of the virtual machines must be able to communicate with each other. Only the virtual machines which contain data nodes must be reachable from the internet.

Number of Virtual Machines

Multiple TraefikEE nodes can be installed on the same virtual machine. To allow it, each node must specify its:

  • advertise and listen address with its own port on the machine
  • sock
  • statedir

Please refer to the documentation for more details

Install traefikee

First, download traefikee on each virtual machine, by using one of the following links:

Check the integrity of the downloaded file

Use the sha256 checksums of the binaries:

# Compare this value to the one found in SHA256SUMS.txt
sha256sum traefikee_linux-amd64
# Compare this value to the one found in SHA256SUMS.txt
shasum -a256 traefikee_darwin-amd64
# Compare this value to the one found in SHA256SUMS.txt
Get-FileHash traefikee_windows-amd64.exe -Algorithm SHA256

Copy the traefikee binary to your PATH or add its location to your environment ($PATH or %PATH% depending on your OS) and make sure it's executable:

# Example with /usr/local/bin
# These command may need sudo rights
cp traefikee_linux-amd64 /usr/local/bin/traefikee
chmod a+x /usr/local/bin/traefikee

# Should print "/usr/local/bin/traefikee"
command -v traefikee
# Example with C:\Program Files
Copy-Item "traefikee_windows-amd64.exe" -Destination "C:\Program Files\traefikee.exe"

# Should print "C:\Program Files\traefikee.exe"
where traefikee

You can now test your installation by executing traefikee:

traefikee
Usage: traefikee [flags] <command> [<arguments>]

Use "traefikee <command> --help" for help on any command.

Initialize the bootstrap server

The "Bootstrap node" is an ephemeral control node, responsible for initializing the cluster with your license information.

traefikee bootstrap \
    --hostname=bootstrap \
    --advertise=10.10.0.1:4242 \
    --listen=10.10.0.1:4242 \
    --licensekey=fakeLicense \
    --api \
    --expectedNodes=3 \
    --timeout=300

Customize the sock

By default, the TraefikEE sock is created in /var/run/traefikee.sock. The option --sock allows customizing the path.

Customize the state directory

By default, the TraefikEE state directory is created in /var/lib/traefikee_state. The option --statedir allows customizing the path.

Dashboard security

The option --api allows exposing the TraefikEE dashboard on the port 8080 only on Control Nodes. TraefikEE does not manage the security to access to its dashboard.

Bootstrap stopped after 5 minutes

If all the control nodes are not started within 5 minutes, the control plane is not initialized and then the bootstrap node will stop automatically and the cluster will not be created. To avoid this, you can tune the timeout parameter. For example, to make the bootstrap wait for up to 600 seconds:

  • --timeout=600

Check if the bootstrap node started by listing the cluster nodes from the virtual machine which contains the bootstrap node.

The bootstrap node's role should be Control Node (Current Leader):

traefikee list-nodes
Name           Role
----           --------------
bootstrap      CONTROL NODE (Current Leader)

Get Tokens

Get the control node's token generated by the bootstrap node:

traefikee env | grep 'CONTROL_NODE_TOKEN' | cut -d '"' -f2

Repeat the same for the data node's token:

traefikee env | grep 'DATA_NODE_TOKEN' | cut -d '"' -f2

How to use the tokens?

All the nodes require a token are required to start. Tokens can be stored in environment variables on each virtual machine, by setting it over SSH for example. In the following commands, tokens have been stored in environment variables:

  • ${CONTROL_NODE_TOKEN}: control node token
  • ${DATA_NODE_TOKEN}: data node token

Create the Control Nodes

Create the 3 control nodes for your cluster by launching the following commands on each control node virtual machine:

  • Control node 1
traefikee start-control-node \
    --hostname=control-node-1 \
    --peeraddresses=10.10.0.1:4242,10.10.0.3:4242,10.10.0.4:4242 \
    --advertise=10.10.0.2:4242 \
    --listen=10.10.0.2:4242 \
    --token=${CONTROL_NODE_TOKEN}
  • Control node 2
traefikee start-control-node \
    --hostname=control-node-2 \
    --peeraddresses=10.10.0.1:4242,10.10.0.2:4242,10.10.0.4:4242\
    --advertise=10.10.0.3:4242 \
    --listen=10.10.0.3:4242 \
    --token=${CONTROL_NODE_TOKEN}
  • Control node 3
traefikee start-control-node \
    --hostname=control-node-3 \
    --peeraddresses=10.10.0.1:4242,10.10.0.2:4242,10.10.0.3:4242\
    --advertise=10.10.0.4:4242 \
    --listen=10.10.0.4:4242 \
    --token=${CONTROL_NODE_TOKEN}

Verify that you have 4 TraefikEE nodes (3 control nodes and 1 bootstrap) that are control nodes by launching the following from a Control Node virtual machine:

traefikee list-nodes --details
ID                         Name            Membership  Status  Availability  Role
--                         ----            ----------  ------  ------------  ----
ge4ssbnjmsjw3h5bftrkkv5xv  control-node-3  ACCEPTED    READY   ACTIVE        CONTROL NODE
o92ldyepge8379vbo0ktaixi4  control-node-1  ACCEPTED    READY   ACTIVE        CONTROL NODE
v9m7zaq16ipo0ihhstovjo96r  bootstrap-node  ACCEPTED    DOWN    ACTIVE        CONTROL NODE
wnlqy33k9knic4eb44o4an0ve  control-node-2  ACCEPTED    READY   ACTIVE        CONTROL NODE (Current Leader)

Bootstrap down

The list-nodes command shows that the bootstrap node is in state DOWN. The bootstrap node automatically downs when the number of control nodes specified in the option expectedNodes is reached or when the timeout is exceeded. If the bootstrap node is not automatically stopped, refer to the section below to stop it manually.

Remove the Bootstrap Node

TraefikEE requires an odd number of control nodes to work flawlessly.

Remove the Bootstrap node (by launching a kill command on the TraefikEE process on the bootstrap virtual machine) to have 3 control nodes (instead of 4):

ps -ef | grep traefikee | awk '{print $2}' | xargs kill -9

Periodically, the cluster cleans the node list and stops tracking the deleted nodes.

Check that there are 3 control nodes left after 1 minute:

traefikee list-nodes
Name            Role
----            --------------
control-node-1  CONTROL NODE (Current Leader)
control-node-3  CONTROL NODE
control-node-2  CONTROL NODE

Important

The Bootstrap node was the previous leader and is now removed from the cluster. The Control nodes elected a new leader. This behavior is what happens when a control node, acting as a leader, is going down in production: TraefikEE stays available.

Create Data Nodes

Create the data nodes, to handle your application traffic by launching the following commands on each data node virtual machine:

  • Data node 1
traefikee start-data-node \
    --hostname=data-node-1 \
    --peeraddresses=10.10.0.1:4242,10.10.0.2:4242,10.10.0.3:4242,10.10.0.4:4242 \
    --token=${DATA_NODE_TOKEN}
  • Data node 2
traefikee start-data-node \
    --hostname=data-node-2 \
    --peeraddresses=10.10.0.1:4242,10.10.0.2:4242,10.10.0.3:4242,10.10.0.4:4242 \
    --token=${DATA_NODE_TOKEN}

Check that the TraefikEE cluster contains the 2 data nodes:

traefikee list-nodes
Name                        Role
----                        --------------
control-node-3              CONTROL NODE
control-node-1              CONTROL NODE (Current Leader)
control-node-2              CONTROL NODE
data-node-1                 DATA NODE
data-node-2                 DATA NODE

Deploy a configuration

A TraefikEE cluster is created without any default configuration. To allow control nodes to listen to a provider and data nodes to manage incoming Traefik, execute the following command on a control node virtual machine:

traefikee deploy --entryPoints='Name:http Address::80' \
    --entryPoints='Name:https Address::443 TLS' \
    --defaultentrypoints=http,https \
    --consul.endpoint=10.10.0.10:8500 \
    --consul.watch \
    --consul.prefix=traefik
[INFO] The loglevel and the TraefikeeLog loglevel will be set to the default level("info")

The command described above allows the control nodes to get the backends and frontends stored in a Consul Key Value Store (reachable at the address 10.10.0.10:8500).

Data nodes expose these backends and frontends on the port 80 and 443 (in TLS).

Load balance between data nodes

TraefikEE does not manage load balancing between data nodes. It can be managed thanks to an IP table rule for example.

File provider

The Traefik File Provider is not implemented yet in TraefikEE.