TLS¶

TraefikEE provides support for TLS over HTTP and TCP. It can be enabled on any router either using ACME or user-provided certificates. This section will explain how to load user-provided certificates into a cluster and how to configure routers to use them.

teectl is required

The teectl binary must be installed for cluster management.

Manage TLS Certificates¶

A TLS certificate can be added to a cluster using the following teectl command:

teectl create tls-cert \ 
    --cert="cert.pem" \
    --key="key.pem"

Once added, the certificate will be used on routers that have TLS enabled when the domain matches. TraefikEE can use a default certificate when there's no matching domain. A certificate will be served by default if the --isdefault option is given.

Certificate information can be retrieved from a cluster using the following command:

Command

teectl get tls-certs

Expected output

ID                         CN                  SANs  NOT AFTER             STORE    DEFAULT
u7vxw9esw9vuyjqokgpvza9cl  whoami.example.com        2022-01-22T15:27:25Z  default  false

Please note that each certificate is assigned a unique ID which is used to remove it from the cluster:

teectl delete tls-cert --id="u7vxw9esw9vuyjqokgpvza9cl"

Examples¶

Kubernetes¶

Setup a cluster on Kubernetes:

# Setup a cluster to manage.
teectl setup --kubernetes
# Generate manifest file and install it on the Kubernetes cluster.
teectl setup gen \
    --license="$TRAEFIKEE_LICENSE" \
    --controllers=1 \
    --proxies=2 | kubectl apply -f -

Add the certificate to the cluster:

teectl create tls-cert \ 
    --cert="cert.pem" \
    --key="key.pem"

Copy the following static configuration in a file named static.yaml. It configures TraefikEE to use the kubernetesCRD provider and adds a secure entrypoint to listen for incoming HTTP requests on the port 443.

providers:
  kubernetesCRD: {}

entryPoints:
  secure:
    address: ":443"

Once the cluster is ready, apply the static configuration:

teectl apply --file="./static.yaml"

Create a new file whoami.yaml with the following kubernetes objects:

Namespace: Create a new namespace whoami-ns where the following objects will reside.
Deployment: Deploy a single pod running the containous/whoami image.
Service: Declare a service whoami-svc to expose the whoami pods on port 80.
IngressRoute: Declare a new router which routes requests coming from the secure entrypoint (port 443, defined in the static configuration) to the whoami-svc service if the hostname is whoami.example.com. Please note that tls is enabled on this route.

---
apiVersion: v1
kind: Namespace
metadata:
  name: whoami-ns

---
kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: whoami-ns
spec:
  selector:
    matchLabels:
      app: whoami
  replicas: 1
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: containous/whoami:v1.4.0
          imagePullPolicy: Always

---
apiVersion: v1
kind: Service
metadata:
  name: whoami-svc
  namespace: whoami-ns
spec:
  type: ClusterIP
  ports:
    - port: 80
      name: whoami
  selector:
    app: whoami

---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: whoami-ingressroute
  namespace: whoami-ns
spec:
  entryPoints:
    - secure
  routes:
    - match: Host(`whoami.example.com`)
      kind: Rule
      services:
        - name: whoami-svc
          port: 80
  tls: {}

Deploy the whoami service and the ingress route:

kubectl apply -f ./whoami.yaml

The application is now deployed and accessible on https://whoami.example.com.

EXTERNAL_IP=$(kubectl -n traefikee get service/default-proxy-svc -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
openssl s_client -showcerts -servername whoami.example.com "$EXTERNAL_IP:443"

Docker Swarm¶

Setup a cluster on Docker Swarm:

# Setup a cluster to manage.
teectl setup --swarm --swarm.hosts="<the swarm hosts>"
# Setup TraefikEE controllers.
teectl setup gen \
    --license="$TRAEFIKEE_LICENSE" \
    --controllers=1 | docker stack deploy -c - traefikee
# Setup TraefikEE proxies once the controlers are ready.
teectl setup gen \
    --license="$TRAEFIKEE_LICENSE" \
    --proxies=2 | docker stack deploy -c - traefikee

Add the certificate to the cluster:

teectl create tls-cert \ 
    --cert="cert.pem" \
    --key="key.pem"

Copy the following static configuration in a file named static.yaml. It configures TraefikEE to use the docker provider with swarmMode enabled and adds a secure entrypoint to listen for incoming HTTP requests on the port 443.

providers:
  docker:
    swarmMode: true
    exposedByDefault: false

entryPoints:
  secure:
    address: ":443"

Once the cluster is ready, apply the static configuration:

teectl apply --file="./static.yaml"

Create a new file whoami.yaml to define a whoami service. Please note that tls is enabled on this whoami router.

version: '3.4'
networks:
  traefikee_traefikee-ingress:
    external: true

services:
  whoami:
    image: containous/whoami:v1.4.0
    deploy:
      mode: replicated
      replicas: 1
      labels:
        - "traefik.http.routers.whoami.entrypoints=secure"
        - "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)"
        - "traefik.http.routers.whoami.tls=true"
        - "traefik.http.services.whoami.loadbalancer.server.port=80"
    networks:
      - traefikee_traefikee-ingress

Deploy the whoami service:

docker stack deploy -c whoami.yaml traefikee

The application is now deployed and accessible on https://whoami.example.com.

openssl s_client -showcerts -servername whoami.example.com "127.0.0.1:443"