Installing Traefik Enterprise Edition On-Premise¶
This installation guide is for users who want to install a cluster on-premise.
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
teectlbinary is installed, for cluster management
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
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
HTTPS_PROXY environment variables defined.
State Directory Management¶
By default, the
statedir path is
- 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.
traefikee on each virtual machine, by using one of the following links:
traefikeefor Linux (Intel) 64 Bits
traefikeefor Linux (ARM) v6
traefikeefor Linux (ARM) v7
traefikeefor macOS (Intel) 64 Bits
traefikeefor Windows (Intel) 64 Bits
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.2.1_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt shasum -a256 ./traefikee_v2.2.1_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt Get-FileHash traefikee_v2.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_v2.2.1_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt tar -zxvf -a256 ./traefikee_v2.2.1_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt Expand-Archive traefikee_v2.2.1_windows_amd64.zip
traefikee binary to your
PATH or add its location to your environment (
%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 (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
To start the installation, teectl must first be configured:
teectl setup --onpremise.hosts="<ip1>,<ip2>,<ip3>"
The host IPs that will be used for controllers should also be set in the
This command creates a new
teectl configuration under
~/.config/traefikee/default.yaml and generates a
bundle.zip which carries a set of needed assets for the installation.
bundle.zip needs to be copied onto each controller host.
To further configure the
teectl setup, please refer to the reference documentation.
Connecting to a Controller Locally
It is possible to connect to a cluster by using the socket (default
/var/run/traefikee/teectl.sock) using the
socket option on
teectl must be used on the same host as a controller for this to work.
teectl get nodes --socket=/var/run/traefikee/teectl.sock
In this case, no
bundle.zip is needed to start the Controller and the above step can be skipped.
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>" --api.bundle="<path-to>/bundle.zip"
traefikee controller --advertise="10.0.0.1:4242" --license="<your-license-key>" --api.bundle="<path-to>/bundle.zip" --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>" --api.bundle="<path-to>/bundle.zip" --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
By default TraefikEE will use the hostname as the node. This behavior can be overridden by specifying the
--name flag on the
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
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:
entryPoints: web: address: ":80" websecure: address: ":443" providers: file: filename: dynamic_conf.yml
[entryPoints] [entryPoints.web] address = ":80" [entryPoints.websecure] address = ":443" [providers] [providers.file] filename = "/etc/traefikee/dynamic_conf.toml"
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
teectl apply --file=config.toml
Now that the cluster is ready, we recommend reading the various operating guides to dive into all features that TraefikEE provides.