Installing Traefik Enterprise Edition with Single Control Nodes on TraefikEE 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 1 control node and 2 data nodes, prepare 3 Virtual Machines:
    • VM1: 10.10.0.1 → control-node-1
    • VM2: 10.10.0.2 → data-node-1
    • VM3: 10.10.0.3 → data-node-2
  • Control node VM can reach https://v3.license.containous.cloud.

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

Installation behind a proxy

In order to be able to install TraefikEE behind a proxy, you must make sure that each TraefikEE instance has the proper HTTP_PROXY and HTTPS_PROXY environment variables defined.

State Directory Management

By default, the statedir directory path is /var/lib/traefikee_state.

  • The state directory's contents are used to recover a cluster's state in the event of a control node restart. It has to persist between two executions.
  • In order to re-initialize a cluster, you have to delete the state directory before re-installing it. If this is not done, it will recover its previous state.

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 traefikee_checksums.txt
sha256sum ./traefikee_v1.2.1_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
shasum -a256 ./traefikee_v1.2.1_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
Get-FileHash traefikee_v1.2.1_windows_amd64.zip -Algorithm SHA256
Extract the downloaded archive

Use the following commands to extract the archive:

# Compare this value to the one found in traefikee_checksums.txt
tar -zxvf traefikee_v1.2.1_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
tar -zxvf -a256 ./traefikee_v1.2.1_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
Expand-Archive traefikee_v1.2.1_windows_amd64.zip

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 /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.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 Control Node

First, delete the statedir directory content (by default /var/lib/traefikee_state). Otherwise, the cluster will be started by keeping information from it and will be in an unexpected state.

The control node is responsible for bootstrapping the cluster with your license information. During the cluster life cycle, this node will listen to you providers API to discover the backends. It will share the backends with the data nodes which will expose them.

By default, the traefikee bootstrap command line deploys a cluster with 1 Control Node.

traefikee bootstrap \
    --advertise=10.10.0.1:4242 \
    --listen=10.10.0.1:4242 \
    --licensekey=fakeLicense \
    --api
Node hostname

Nodes names are equal to VM hostnames.

Customize the socket path

By default, the TraefikEE socket is created in /var/run/traefikee.sock. The option --traefikeesocket 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 to the state directory.

Customize the API credential generation directory

By default, TraefikEE stores its generated credentials (certificates and keys) in ./.traefikee. The option --mtlscertsoutputdir allows customizing the path in which they are be stored.

Restoring a backup

In order to perform a backup restoration, specify the --archivepath=./your-backup.tar option instead of the --licensekey option. To find out more about the backup and restore system, see here.

API credentials

When installing your cluster, TraefikEE will generate credentials (certificates and keys) that are necessary to communicate with its API. Make sure never to loose those credentials as TraefikEE will only generate them once per cluster. If you lost them, you will need to re-install your TraefikEE cluster.

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.

Check if the control node started by listing the cluster nodes from the virtual machine which contains it:

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

Get the Data Node Token

Get the data node token generated by the bootstrap node:

traefikee env | grep 'DATA_NODE_TOKEN' | cut -d '"' -f2
How to use the token?

All data nodes require a token to start. The token can be stored in environment variable on each virtual machine, by setting it over SSH for example. In the following commands, the data node token has been stored in the environment variable named ${DATA_NODE_TOKEN}.

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 \
    --peeraddresses=10.10.0.1:4242 \
    --token=${DATA_NODE_TOKEN}
  • Data node 2
traefikee start-data-node \
    --peeraddresses=10.10.0.1:4242 \
    --token=${DATA_NODE_TOKEN}

Check that the TraefikEE cluster contains the 2 data nodes:

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

Deploy a Configuration

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

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

The command described above allows the control node to get the backends and frontends stored in a Consul Key Value Store (reachable at the address 10.10.0.10:8500, as specified with the --consul.endpoint option).

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

Load balance between data nodes

TraefikEE does not manage load balancing between data nodes. It should be managed externally with an IP table rule for example.

File provider

The Traefik File Provider is not implemented yet in TraefikEE.

Remotely Accessing the TraefikEE Cluster with traefikeectl

The aforementioned operations require a connection to the control node, because they are executed using the traefikee command. These operations can be executed from a remote machine instead, using traefikeectl.

Why use traefikeectl?

traefikeectl is a command-line tool which makes it easy to manage a TraefikEE cluster. It uses a secure internal API within TraefikEE to execute operations. However, it's also possible to manage a TraefikEE cluster by using the traefikee command from the control node VM.

API credentials deletion

When installing your cluster, TraefikEE will generate credentials (certificates and keys) that are necessary to communicate with its API on the control node. If you do not want to use traefikeectl, for more security, you can delete these credentials from the directory specified in the option --mtlscertsoutputdir of the bootstrap command (by default ./.traefikee from the install directory on the control node).

Requirements for traefikeectl

In order to use traefikeectl to remotely access to the cluster:

  • Check if the remote machine can access to the control node API port (55055)
  • Check if the files can be moved from the control node file system to the remote machine.

Install traefikeectl

The traefikeectl tool can be installed on the remote machine by following this documentation.

Get the Credentials

In order to access your cluster remotely with traefikeectl, you need to securely move the credentials from the control node to the file system of the machine from which you want to use traefikeectl.

On the control node, the credentials have been generated in the directory specified in the option --mtlscertsoutputdir of the bootstrap command (by default ./.traefikee from the install directory on the control node).

You can get them by using, for example, a scp command:

scp <CONTROL_NODE_IP>:<CONTROL_NODE_MTLS_CERT_DIR> <LOCAL_MTLS_CERT_DIR>

Connect traefikeectl to the New Cluster

Configure traefikeectl to have access to the new cluster.

traefikeectl connect --onpremise.mtlscertsdir="<LOCAL_MTLS_CERT_DIR>" --onpremise.apiaddress="<CONTROL_NODE_IP>:55055"
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.

You can then provide the path to the certificates using the --onpremise.mtlscertsdir option. Do not forget to specify the --onpremise.apiaddress argument in order for traefikeectl to be able to communicate with the API.

One-time operation

When running traefikeectl connect, your credentials will be retrieved and it will not be possible to do it again in the future without re-installing a TraefikEE cluster. Remember to keep your credentials safe!

Validate the Connection

Check if the traefikeectl command is linked to the cluster by listing the cluster nodes:

traefikeectl list-nodes
Name                        Role             Leader
----                        ----              ------
control-node-1              Control Node      YES
data-node-1                 Data Node
data-node-2                 Data Node

You can now manage your cluster using traefikeectl commands.

What's Next?

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