Traefik Enterprise Edition on Docker Enterprise Edition¶

Traefik Enteprise Edition (TraefikEE) is a production-grade, distributed, and highly-available routing solution built on top of Traefik.

TraefikEE Architecture

If you want to learn more about TraefikEE, please refer to the page "Concepts" of the documentation.

Prerequisites¶

This solution guide was tested with the following elements:

Docker Enterprise Version: 18.09.3-ee
UCP: 3.4.1
Docker running in Swarm mode OR in Kubernetes 1.11.7-docker-1
TraefikEE v1.0, with the command-line tool traefikeectl
A valid TraefikEE license stored in the environment variable $TRAEFIKEE_LICENSE_KEY

External Access¶

Address¶

TraefikEE takes advantage of the Routing Mesh with Swarm (or the Node Ports with Kubernetes).

In order to reach TraefikEE from the outside, you have to configure either:

DNS record(s) to at least one Docker EE worker node
An external load-balancer distributing requests to your Docker EE worker nodes

Ports¶

It is strongly advised to expose the IANA HTTP (80) and HTTPS (443) ports on the Docker EE worker nodes.

However, the default installation of UCP is already using the port 443 of the worker nodes, as explained in the Docker's UCP documentation

Based on your future needs, you have to choose one the following scenarios:

If you plan to to use Let's Encrypt with TraefikEE:
- Please refer to this Docker EE solutions guide: How to change UCP Controller Port?,
- Use the ports 80 and 443 for external access to TraefikEE.
If you don't need Let's Encrypt, or cannot change UCP ports:
- Consider using 2 available ports on the Docker EE worker nodes: Let's say 9080 and 9443
- Configure your external Load-Balancer to do the port fowarding 80 <-> 9080 and 443 <-> 9443

Let's Encrypt and port 443

Port 443 is mandatory if you plan to use Let's Encrypt:

Choose your Orchestrator¶

Depending on your context, you can use TraefikEE either with Swarm or with Kubernetes.

With Swarm¶

Installation on Manager Nodes¶

The TraefikEE control plane requires an access to the Swarm API. By default, it uses the docker daemon socket mounted inside the container, restraining the deployment of the control plane to the swarm managers only.

Installation is a Swarm One Line Installation, specifying the HTTP/HTTPS public ports (chosen earlier in the "Ports" section) as options:

Swarm Installation Command

traefikeectl install \
  --swarm \
  --dashboard \
  --licensekey="${TRAEFIKEE_LICENSE_KEY}" \
  --swarm.http=9080 \
  --swarm.https=9443 \
  --clustername=traefikee-swarm

traefikeectl install options

You can learn more about the command-line options used on the traefikeectl install Reference Guide

Installation on Worker Nodes¶

DockerEE also comes with the universal control plane (UCP) which securely exposes the Swarm API. TraefikEE leverages this to have its control plane executed only on workers nodes.

In order for traefikeectl to be able to install a TraefikEE cluster on DockerEE, you first need to setup your Docker environment to point to your DockerEE installation. Refer to the DockerEE documentation in order to do so.

By specifying the --swarm.ucpbundle option, traefikeectl deploys the control plane on Swarm workers only. This option must point to a zipped UCP client bundle downloaded from the UCP web interface.

Swarm Installation Command

traefikeectl install \
  --swarm \
  --dashboard \
  --licensekey="${TRAEFIKEE_LICENSE_KEY}" \
  --swarm.http=9080 \
  --swarm.https=9443 \
  --swarm.ucpbundle="./ucp-bundle.zip"
  --clustername=traefikee-swarm

UCP and deployments

When running in UCP, remember that each call to traefikeectl deploy must include the --swarm.ucpbundle option pointing to the UCP bundle secret mounted in the container (e.g.: /var/run/traefikee-ucp-bundle if the secret name is traefikee-ucp-bundle).

Configuration¶

Once the installation is finished:

You can manage the cluster with traefikeectl:

traefikeectl list-nodes --clustername=traefikee-swarm
traefikeectl logs --clustername=traefikee-swarm
...

Deploy a customized routing configuration to create the entrypoints. Please note that TraefikEE uses the 80 and 443 ports internally, hence these values for the entrypoints:

traefikeectl deploy --clustername=traefikee-swarm \
    --docker.swarmmode \
    --entryPoints='Name:http Address::80' \
    --entryPoints='Name:https Address::443 TLS' \
    --defaultentrypoints=https,http

Deploy Application¶

You can start deploying applications in Docker Swarm with labels configured:

Start by creating the following Docker YAML Compose file, with public.cluster.dns.org being the public DNS to reach the cluster:

docker-whoami.yaml

version: '3.4'
networks:
  traefikee_net:
    external: true

services:
  whoami:
    image: containous/whoami
    deploy:
      mode: replicated
      replicas: 2
      labels:
        - "traefik.enable=true"
        - "traefik.frontend.rule=Path:/whoami"
        - "traefik.port=80"
    networks:
      - traefikee_net

Deploy your application with the following command:

docker stack deploy whoami --compose-file=./docker-whoami.yaml

Check the application deployment status, with 2/2 replicas ready:
```
docker service ls
```
Verify that the requests are routed by TraefikEE to the "whoami" application:
```
curl http://public.cluster.dns.org:9080
```
Cleanup the "whoami" application if everything is working as expected:
```
docker stack rm whoami
```

With Kubernetes¶

Default Storage Class¶

As specified in the Kubernetes requirements for TraefikEE, check that your DockerEE Kubernetes installation has a default storage class:

kubectl get storageclass

You should get an output similar to this one, where one of the elements is defined as (default):

NAME                 PROVISIONER    AGE
standard (default)   xxxxxxxxxx     1d

If you do not have any default storage class defined, please check the following Docker EE guides:

You might also want to check the official Kubernetes documentation:

Once you have a default storage class defined, you can go to the next step.

Installation¶

Installation is a Kubernetes Customised One Line Installation, specifying the HTTP/HTTPS ports (chosen earlier in the "Ports" section) in the YAML values file:

custom-values.yaml

ports:
  http: 9080
  https: 9443

Then execute the following installation command:

Kubernetes Installation Command

traefikeectl install \
  --kubernetes \
  --dashboard \
  --licensekey="${TRAEFIKEE_LICENSE_KEY}" \
  --kubernetes.helmvaluespath=./custom-values.yaml \
  --clustername=traefikee-kube

traefikeectl install options

You can learn more about the command-line options used on the traefikeectl install Reference Guide

Don't forget to retrieve the default dashboard generated password from the installation output.

Configuration¶

Once the installation is finished:

You can manage the cluster with traefikeectl:

traefikeectl list-nodes --clustername=traefikee-kube
traefikeectl logs --clustername=traefikee-kube
...

Deploy a customized routing configuration to create the entrypoints. Please note that TraefikEE uses the 80 and 443 port internally, hence these values for the entrypoints:

traefikeectl deploy --clustername=traefikee-kube \
    --kubernetes \
    --entryPoints='Name:http Address::80' \
    --entryPoints='Name:https Address::443 TLS' \
    --defaultentrypoints=https,http

Deploy Application¶

You can start deploying applications in Kubernetes with Ingress Rules:

Start by creating the following YAML file describing the Kubernetes Objects for an application, with public.cluster.dns.org being the public DNS to reach the cluster:

kubernetes-whoami.yaml

---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: whoami
  namespace: traefikee
spec:
  replicas: 2
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: containous/whoami
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: traefikee
  labels:
    app: whoami
spec:
  type: ClusterIP
  ports:
    - port: 80
      name: whoami
  selector:
    app: whoami
---
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: whoami
  namespace: traefikee
  labels:
    app: whoami
spec:
  rules:
    - http:
        paths:
          - path: /whoami
            backend:
              serviceName: whoami
              servicePort: 80

Deploy your application with the following command:
```
kubectl apply -f ./kubernetes-whoami.yaml
```

Check the application deployment status, expecting the 3 objects to be in staus Ready:

kubectl get deployment,svc,ingress \
    --namespace=traefikee \
    --selector=app=whoami

Verify that the requests are routed by TraefikEE to the "whoami" application:
```
curl http://public.cluster.dns.org:9080/whoami
```
Cleanup the "whoami" application if everything is working as expected:
```
kubectl delete -f ./kubernetes-whoami.yaml
```