Traefik & Kubernetes

The provider then watches for incoming ingresses events, such as the example below, and derives the corresponding dynamic configuration from it, which in turn will create the resulting routers, services, handlers, etc.

Configuration Example

Configuring Kubernetes Ingress Controller

RBAC

Ingress

  2. apiVersion: networking.k8s.io/v1beta1
  3. metadata:
  4.   name: myingress
  5.   annotations:
  6.     traefik.ingress.kubernetes.io/router.entrypoints: web
  8. spec:
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - path: /bar
  14.             backend:
  15.               serviceName: whoami
  16.               servicePort: 80
  17.           - path: /foo
  18.             backend:
  19.               serviceName: whoami
  20.               servicePort: 80

Traefik

  1. apiVersion: v1
  2. kind: ServiceAccount
  3. metadata:
  4.   name: traefik-ingress-controller
  6. ---
  7. kind: Deployment
  8. apiVersion: apps/v1
  9. metadata:
  10.   name: traefik
  11.   labels:
  12.     app: traefik
  14. spec:
  15.   replicas: 1
  16.   selector:
  17.     matchLabels:
  18.       app: traefik
  19.   template:
  20.     metadata:
  21.       labels:
  22.         app: traefik
  23.     spec:
  24.       serviceAccountName: traefik-ingress-controller
  25.       containers:
  26.         - name: traefik
  27.           image: traefik:v2.4
  28.           args:
  29.             - --entrypoints.web.address=:80
  30.             - --providers.kubernetesingress
  31.           ports:
  32.             - name: web
  33.               containerPort: 80
  35. ---
  36. apiVersion: v1
  37. kind: Service
  38. metadata:
  39.   name: traefik
  40. spec:
  41.   type: LoadBalancer
  42.   selector:
  43.     app: traefik
  44.   ports:
  45.     - protocol: TCP
  46.       port: 80
  47.       name: web
  48.       targetPort: 80

Whoami

  1. kind: Deployment
  2. apiVersion: apps/v1
  3. metadata:
  4.   name: whoami
  5.   labels:
  6.     app: traefiklabs
  7.     name: whoami
  9. spec:
  10.   replicas: 2
  11.   selector:
  12.     matchLabels:
  13.       app: traefiklabs
  14.       task: whoami
  15.   template:
  16.     metadata:
  17.       labels:
  18.         app: traefiklabs
  19.         task: whoami
  20.     spec:
  21.       containers:
  22.         - name: whoami
  23.           image: traefik/whoami
  24.           ports:
  25.             - containerPort: 80
  27. ---
  28. apiVersion: v1
  29. kind: Service
  30. metadata:
  31.   name: whoami
  33. spec:
  34.   ports:
  35.     - name: http
  36.       port: 80
  37.   selector:
  38.     app: traefiklabs
  39.     task: whoami

On Ingress

traefik.ingress.kubernetes.io/router.entrypoints

See for more information.

  1. traefik.ingress.kubernetes.io/router.entrypoints: ep1,ep2

traefik.ingress.kubernetes.io/router.middlewares

See middlewares and for more information.

  1. traefik.ingress.kubernetes.io/router.middlewares: auth@file,prefix@kubernetescrd,cb@file

traefik.ingress.kubernetes.io/router.priority

See priority for more information.

  1. traefik.ingress.kubernetes.io/router.priority: "42"

traefik.ingress.kubernetes.io/router.pathmatcher

Overrides the default router rule type used for a path.
Only path-related matcher name can be specified: Path, PathPrefix.

Default PathPrefix

  1. traefik.ingress.kubernetes.io/router.pathmatcher: Path

traefik.ingress.kubernetes.io/router.tls

See for more information.

  1. traefik.ingress.kubernetes.io/router.tls: "true"

traefik.ingress.kubernetes.io/router.tls.certresolver

See certResolver for more information.

  1. traefik.ingress.kubernetes.io/router.tls.certresolver: myresolver

traefik.ingress.kubernetes.io/router.tls.domains.n.main

See for more information.

  1. traefik.ingress.kubernetes.io/router.tls.domains.0.main: example.org

traefik.ingress.kubernetes.io/router.tls.domains.n.sans

See domains for more information.

traefik.ingress.kubernetes.io/router.tls.options

  1. traefik.ingress.kubernetes.io/router.tls.options: foobar

On Service

traefik.ingress.kubernetes.io/service.serversscheme

Overrides the default scheme.

  1. traefik.ingress.kubernetes.io/service.serversscheme: h2c

traefik.ingress.kubernetes.io/service.passhostheader

See pass Host header for more information.

  1. traefik.ingress.kubernetes.io/service.passhostheader: "true"

traefik.ingress.kubernetes.io/service.sticky.cookie

See for more information.

  1. traefik.ingress.kubernetes.io/service.sticky.cookie: "true"

traefik.ingress.kubernetes.io/service.sticky.cookie.name

See sticky sessions for more information.

  1. traefik.ingress.kubernetes.io/service.sticky.cookie.name: foobar

traefik.ingress.kubernetes.io/service.sticky.cookie.secure

See for more information.

  1. traefik.ingress.kubernetes.io/service.sticky.cookie.secure: "true"

traefik.ingress.kubernetes.io/service.sticky.cookie.samesite

See sticky sessions for more information.

  1. traefik.ingress.kubernetes.io/service.sticky.cookie.samesite: "none"

traefik.ingress.kubernetes.io/service.sticky.cookie.httponly

See for more information.

  1. traefik.ingress.kubernetes.io/service.sticky.cookie.httponly: "true"

Path Types on Kubernetes 1.18+

If the Kubernetes cluster version is 1.18+, the new pathType property can be leveraged to define the rules matchers:

  • Exact: This path type forces the rule matcher to Path
  • Prefix: This path type forces the rule matcher to PathPrefix

Please see for more information.

Multiple Matches

In the case of multiple matches, Traefik will not ensure the priority of a Path matcher over a PathPrefix matcher, as stated in this documentation.

TLS can be enabled through the of an Entrypoint:

CLI

  1. # Static configuration
  2. --entrypoints.websecure.address=:443
  3. --entrypoints.websecure.http.tls

File (TOML)

  1. # Static configuration
  2. [entryPoints.websecure]
  3.   address = ":443"
  5.     [entryPoints.websecure.http.tls]

File (YAML)

This way, any Ingress attached to this Entrypoint will have TLS termination by default.

Configuring Kubernetes Ingress Controller with TLS on Entrypoint

  1. ---
  2. kind: ClusterRole
  3. apiVersion: rbac.authorization.k8s.io/v1beta1
  4. metadata:
  5.   name: traefik-ingress-controller
  6. rules:
  7.   - apiGroups:
  8.       - ""
  9.     resources:
  10.       - services
  11.       - endpoints
  12.       - secrets
  14.       - get
  15.       - list
  16.       - watch
  17.   - apiGroups:
  18.       - networking.k8s.io
  19.     resources:
  20.       - ingresses
  21.       - ingressclasses
  22.     verbs:
  23.       - get
  24.       - list
  25.       - watch
  26.   - apiGroups:
  27.       - extensions
  28.     resources:
  29.       - ingresses/status
  30.     verbs:
  31.       - update
  33. ---
  34. kind: ClusterRoleBinding
  35. apiVersion: rbac.authorization.k8s.io/v1beta1
  36. metadata:
  37.   name: traefik-ingress-controller
  38. roleRef:
  39.   apiGroup: rbac.authorization.k8s.io
  40.   kind: ClusterRole
  41.   name: traefik-ingress-controller
  42. subjects:
  43.   - kind: ServiceAccount
  44.     name: traefik-ingress-controller
  45.     namespace: default

Ingress

  1. kind: Ingress
  2. apiVersion: networking.k8s.io/v1beta1
  3. metadata:
  4.   name: myingress
  5.   annotations:
  6.     traefik.ingress.kubernetes.io/router.entrypoints: websecure
  8. spec:
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - path: /bar
  14.             backend:
  15.               serviceName: whoami
  16.               servicePort: 80
  17.           - path: /foo
  18.             backend:
  19.               serviceName: whoami
  20.               servicePort: 80

Traefik

  1. apiVersion: v1
  2. kind: ServiceAccount
  3. metadata:
  4.   name: traefik-ingress-controller
  6. ---
  7. kind: Deployment
  8. apiVersion: apps/v1
  9. metadata:
  10.   name: traefik
  11.   labels:
  12.     app: traefik
  14. spec:
  15.   replicas: 1
  16.   selector:
  17.     matchLabels:
  18.       app: traefik
  19.   template:
  20.     metadata:
  21.       labels:
  22.         app: traefik
  23.     spec:
  24.       serviceAccountName: traefik-ingress-controller
  25.       containers:
  26.         - name: traefik
  27.           image: traefik:v2.4
  28.           args:
  29.             - --entrypoints.websecure.address=:443
  30.             - --entrypoints.websecure.http.tls
  31.             - --providers.kubernetesingress
  32.           ports:
  33.             - name: websecure
  34.               containerPort: 443
  36. ---
  37. apiVersion: v1
  38. kind: Service
  39. metadata:
  40.   name: traefik
  41. spec:
  42.   type: LoadBalancer
  43.   selector:
  44.     app: traefik
  45.   ports:
  46.     - protocol: TCP
  47.       port: 443
  48.       name: websecure
  49.       targetPort: 443

Whoami

  1. kind: Deployment
  2. apiVersion: apps/v1
  3. metadata:
  4.   name: whoami
  5.   labels:
  6.     app: traefiklabs
  7.     name: whoami
  9. spec:
  10.   replicas: 2
  11.   selector:
  12.     matchLabels:
  13.       app: traefiklabs
  14.       task: whoami
  15.   template:
  16.     metadata:
  17.       labels:
  18.         app: traefiklabs
  19.         task: whoami
  20.     spec:
  21.       containers:
  22.         - name: whoami
  23.           image: traefik/whoami
  24.           ports:
  25.             - containerPort: 80
  27. ---
  28. apiVersion: v1
  29. kind: Service
  30. metadata:
  31.   name: whoami
  33. spec:
  34.   ports:
  35.     - name: http
  36.       port: 80
  37.   selector:
  38.     app: traefiklabs
  39.     task: whoami

To enable TLS on the underlying router created from an Ingress, one should configure it through annotations:

  1. traefik.ingress.kubernetes.io/router.tls: "true"

For more options, please refer to the available annotations.

Configuring Kubernetes Ingress Controller with TLS

RBAC

  1. ---
  2. kind: ClusterRole
  3. apiVersion: rbac.authorization.k8s.io/v1beta1
  4. metadata:
  5.   name: traefik-ingress-controller
  6. rules:
  7.   - apiGroups:
  8.       - ""
  9.     resources:
  10.       - services
  11.       - endpoints
  12.       - secrets
  13.     verbs:
  14.       - get
  15.       - list
  16.       - watch
  17.   - apiGroups:
  18.       - extensions
  19.       - networking.k8s.io
  20.     resources:
  21.       - ingresses
  22.       - ingressclasses
  23.     verbs:
  25.       - watch
  26.   - apiGroups:
  27.       - extensions
  28.     resources:
  29.       - ingresses/status
  30.     verbs:
  31.       - update
  33. ---
  34. kind: ClusterRoleBinding
  35. apiVersion: rbac.authorization.k8s.io/v1beta1
  36. metadata:
  37.   name: traefik-ingress-controller
  38. roleRef:
  39.   apiGroup: rbac.authorization.k8s.io
  40.   kind: ClusterRole
  41.   name: traefik-ingress-controller
  42. subjects:
  43.   - kind: ServiceAccount
  44.     name: traefik-ingress-controller
  45.     namespace: default

Ingress

  1. kind: Ingress
  2. apiVersion: networking.k8s.io/v1beta1
  3. metadata:
  4.   name: myingress
  5.   annotations:
  6.     traefik.ingress.kubernetes.io/router.entrypoints: websecure
  7.     traefik.ingress.kubernetes.io/router.tls: true
  9. spec:
  10.   rules:
  11.     - host: example.com
  12.       http:
  13.         paths:
  14.           - path: /bar
  15.             backend:
  16.               serviceName: whoami
  17.               servicePort: 80
  18.           - path: /foo
  19.             backend:
  20.               serviceName: whoami
  21.               servicePort: 80

Traefik

  1. apiVersion: v1
  2. kind: ServiceAccount
  3. metadata:
  4.   name: traefik-ingress-controller
  6. ---
  7. kind: Deployment
  8. apiVersion: apps/v1
  9. metadata:
  10.   name: traefik
  11.   labels:
  12.     app: traefik
  14. spec:
  15.   replicas: 1
  16.   selector:
  17.     matchLabels:
  18.       app: traefik
  19.   template:
  20.     metadata:
  21.       labels:
  22.         app: traefik
  23.     spec:
  24.       serviceAccountName: traefik-ingress-controller
  25.       containers:
  26.         - name: traefik
  27.           image: traefik:v2.4
  28.           args:
  29.             - --entrypoints.websecure.address=:443
  30.             - --providers.kubernetesingress
  31.           ports:
  32.             - name: websecure
  33.               containerPort: 443
  35. ---
  36. apiVersion: v1
  37. kind: Service
  38. metadata:
  39.   name: traefik
  40. spec:
  41.   type: LoadBalancer
  42.   selector:
  43.     app: traefik
  44.   ports:
  45.     - protocol: TCP
  46.       port: 443
  47.       name: websecure
  48.       targetPort: 443

Whoami

  1. kind: Deployment
  2. apiVersion: apps/v1
  3. metadata:
  4.   name: whoami
  5.   labels:
  6.     app: traefiklabs
  7.     name: whoami
  9. spec:
  10.   replicas: 2
  11.   selector:
  12.     matchLabels:
  13.       app: traefiklabs
  14.       task: whoami
  15.   template:
  16.     metadata:
  17.       labels:
  18.         app: traefiklabs
  19.         task: whoami
  20.     spec:
  21.       containers:
  22.         - name: whoami
  23.           image: traefik/whoami
  24.           ports:
  25.             - containerPort: 80
  27. ---
  28. apiVersion: v1
  29. kind: Service
  30. metadata:
  31.   name: whoami
  33. spec:
  34.   ports:
  35.     - name: http
  36.       port: 80
  37.   selector:
  38.     app: traefiklabs
  39.     task: whoami

Using a secret

Ingress

  1. kind: Ingress
  2. apiVersion: networking.k8s.io/v1beta1
  3. metadata:
  4.   name: foo
  5.   namespace: production
  7. spec:
  8.   rules:
  9.   - host: example.net
  10.     http:
  11.       paths:
  12.       - path: /bar
  13.         backend:
  14.           serviceName: service1
  15.           servicePort: 80
  16.   # Only selects which certificate(s) should be loaded from the secret, in order to terminate TLS.
  17.   # Doesn't enable TLS for that ingress (hence for the underlying router).
  18.   # Please see the TLS annotations on ingress made for that purpose.
  19.   tls:
  20.   - secretName: supersecret

Secret

TLS certificates can be managed in Secrets objects.

Info

Only TLS certificates provided by users can be stored in Kubernetes Secrets. certificates cannot be managed in Kubernetes Secrets yet.

Traefik automatically requests endpoint information based on the service provided in the ingress spec. Although Traefik will connect directly to the endpoints (pods), it still checks the service port to see if TLS communication is required.

There are 3 ways to configure Traefik to use https to communicate with pods:

  1. If the service port defined in the ingress spec is 443 (note that you can still use targetPort to use a different port on your pod).
  2. If the service port defined in the ingress spec has a name that starts with https (such as https-api, https-web or just https).
  3. If the ingress spec includes the annotation traefik.ingress.kubernetes.io/service.serversscheme: https.

If either of those configuration options exist, then the backend communication protocol is assumed to be TLS, and will connect via TLS automatically.

Info

Please note that by enabling TLS communication between traefik and your pods, you will have to have trusted certificates that have the proper trust chain and IP subject name. If this is not an option, you may need to skip TLS certificate verification. See the insecureSkipVerify setting for more details.

Global Default Backend Ingresses

Ingresses can be created that look like the following:

  1. apiVersion: networking.k8s.io/v1beta1
  2. kind: Ingress
  3. metadata:
  4.  name: cheese
  6. spec:
  7.  backend:
  8.    serviceName: stilton
  9.    servicePort: 80

This ingress follows the Global Default Backend property of ingresses. This will allow users to create a “default router” that will match all unmatched requests.

Info

To do this, use the annotation (as seen in Annotations on Ingress) on your ingresses accordingly.