Installing Traefik Enterprise Edition On-Premise

This installation guide is for users who want to install a cluster on-premise.

Requirements

In order to start a TraefikEE cluster with 1 controller and 2 proxies, ensure that:

  • There are at least 3 Hosts/Virtual Machines
  • Network stack allows communication on required ports
  • Controller Host/VM can reach https://v3.license.containous.cloud
  • The teectl binary is installed, for cluster management

Networking

Only the hosts which run proxies have to be reachable from the internet. On Linux, root access is needed to bind to ports below 1024.

Default TraefikEE paths

The default configration paths for traefikee includes: - /var/run/traefikee - /var/lib/traefikee - /var/run/secrets Read and write access are required on then. See the teectl referece for customization options.

Please refer to the documentation for more information

Multiple instances on the same Host/VM

Running multiple controllers or proxies on the same host is not supported at the moment.

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 path is /var/lib/traefikee.

  • The state directory's contents are used to recover a cluster's state in the event of a controller 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_v2.0.5_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
shasum -a256 ./traefikee_v2.0.5_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
Get-FileHash traefikee_v2.0.5_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_v2.0.5_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
tar -zxvf -a256 ./traefikee_v2.0.5_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
Expand-Archive traefikee_v2.0.5_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 --help
traefikee    TraefikEE (Enterprise Edition) is a Cloud Native Edge Routing Platform based on Traefik,
a modern HTTP reverse proxy and load balancer made to deploy microservices with ease.
Complete documentation is available at https://docs.containo.us.

Usage: traefikee [command] [resource] [flags]

Use "traefikee [command] --help" for help on any command.

Commands:
    controller    Start a new controller
    proxy         Start a new proxy
    tokens        Get tokens from the cluster
    version       Print version

Start the Controller(s)

Start a new controller by specifying the advertise address and TraefikEE license:

traefikee controller --advertise="10.0.0.1:4242" --license="<your-license-key>"
traefikee controller --advertise="10.0.0.1:4242" --license="<your-license-key>" --discovery.static.peers="10.0.0.1:4242,10.0.0.2:4242,10.0.0.3:4242"
traefikee controller --advertise="10.0.0.1:4242" --license="<your-license-key>" --discovery.dns.domain="traefikee.mydomain" --discovery.dns.port="4242" --discovery.dns.bootstrapexpected=2
INFO[2020-01-20T15:00:35-03:00] Using static discovery to discover other controllers  node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Initializing a new node                       role=controller node=controller-0
INFO[2020-01-20T15:00:35-03:00] Discovering cluster                           node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Found peers [10.0.0.1:4242]                    node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Initial leader runs at 10.0.0.1:4242           node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Initializing a new TraefikEE cluster          node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] API started                                   role=controller node=controller-0
INFO[2020-01-20T15:00:35-03:00] Node started                                  role=controller node=controller-0
INFO[2020-01-20T15:00:36-03:00] Node is ready                                 node=controller-0 role=controller
INFO[2020-01-20T15:00:36-03:00] Running the cluster info controller           service=provider node=controller-0 role=controller
INFO[2020-01-20T15:00:36-03:00] Running the cluster license controller with frequency "24h0m0s"  node=controller-0 role=controller service=cleanup
INFO[2020-01-20T15:00:36-03:00] Running the cluster cleanup controller        role=controller node=controller-0 service=cleanup

Node Name

By default TraefikEE will use the hostname as the node. This behavior can be overridden by specifying the --name flag on the controller command.

Multi Controller with DNS

When using DNS as the discovery method it is a good practice to set the flag discovery.dns.bootstrapexpected, as this will make the controllers wait until the specified number of nodes are reachable before bootstraping the cluster.

Get the Proxy Token

Get the proxy node token generated by the controller:

traefikee tokens | grep 'TRAEFIKEE_PROXY_TOKEN' | cut -d '=' -f2
How to use the token?

All proxies require a token to start. The token can be stored in an environment variable on each host machine, by setting it over SSH for example. In the following commands, the proxy token has been stored in an environment variable named ${PROXY_NODE_TOKEN}.

Start Proxies

Start a proxy by specifying the controller discovery method, static in this example, and the join token:

traefikee proxy --jointoken.value="$PROXY_NODE_TOKEN" --discovery.static.peers="10.0.0.1:4242"
traefikee proxy --jointoken.value="$PROXY_NODE_TOKEN" --discovery.dns.domain="traefikee.mydomain"
INFO[2020-01-20T15:09:47-03:00] Applying a new static configuration           node=proxy-0 role=proxy module=server
INFO[2020-01-20T15:09:47-03:00] Using static discovery                        node=proxy-0 role=proxy peers="10.0.0.1:4242"
INFO[2020-01-20T15:09:47-03:00] Discovering controllers                       node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Found controllers [10.0.0.1:4242]             node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Waiting for the join tokens to be available   node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Looking for a reachable peer                  role=proxy node=proxy-0
INFO[2020-01-20T15:09:47-03:00] Joining cluster                               role=proxy joined-peer="10.0.0.1:4242" node=proxy-0
INFO[2020-01-20T15:09:47-03:00] Node started                                  node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Node is ready                                 node=proxy-0 role=proxy

Repeat the steps above for each proxy, then verify that the TraefikEE installation was successful:

teectl get nodes
ID                         NAME           STATUS  ROLE
mmc2qofw8hkudf8vcrs1k8cnw  controller-0   Ready   Controller (Leader)
oncgmk54uuipcj7jnt0lhwwqy  proxy-0        Ready   Proxy
u122z00fgr2cqrp78jc5em0fi  proxy-1        Ready   Proxy

Apply a Static Configuration

A TraefikEE cluster is created without any default configuration. To allow the controller to listen to a provider and proxies to manage incoming traffic, it is necessary to apply a static configuration.

Below is an example of a static configuration:

File provider

entryPoints:
  http:
    address: ":80"
  https:
    address: ":443"

providers:
  file:
    filename: dynamic_conf.yml
[entryPoints]
  [entryPoints.http]
    address = ":80"
  [entryPoints.https]
    address = ":443"

[providers]
  [providers.file]
    filename = "/etc/traefikee/dynamic_conf.toml"

Important

When running multiple controllers, make sure to replicate the configuration file on all nodes at the same path.

Apply the configuration using the following command:

teectl apply --file=config.yaml --socket=/var/run/traefikee/teectl.sock
teectl apply --file=config.toml --socket=/var/run/traefikee/teectl.sock

!!! important Remote Management with teectl Remote management is not supported with teectl when on-premise. The only way to connect to the cluster is by using the socket file on a controller host.

What's Next?

Now that the cluster is ready, we recommend reading the various operating guides to dive into all features that TraefikEE provides.