Migration: Steps needed between the versions

v2.0 to v2.1

Kubernetes CRD

In v2.1, a new Kubernetes CRD called TraefikService was added. While updating an installation to v2.1, one should apply that CRD, and update the existing ClusterRole definition to allow Traefik to use that CRD.

To add that CRD and enhance the permissions, following definitions need to be applied to the cluster.

TraefikService

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: traefikservices.traefik.containo.us
  6. spec:
  7.   group: traefik.containo.us
  8.   version: v1alpha1
  9.   names:
  10.     kind: TraefikService
  11.     plural: traefikservices
  12.     singular: traefikservice
  13.   scope: Namespaced

ClusterRole

  1. kind: ClusterRole
  2. apiVersion: rbac.authorization.k8s.io/v1beta1
  3. metadata:
  4.   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.     resources:
  20.       - ingresses
  21.     verbs:
  22.       - get
  23.       - list
  24.       - watch
  25.   - apiGroups:
  26.       - extensions
  27.     resources:
  28.       - ingresses/status
  29.     verbs:
  30.       - update
  31.   - apiGroups:
  32.       - traefik.containo.us
  33.     resources:
  34.       - middlewares
  35.       - ingressroutes
  36.       - traefikservices
  37.       - ingressroutetcps
  38.       - tlsoptions
  39.     verbs:
  40.       - get
  41.       - list
  42.       - watch

After having both resources applied, Traefik will work properly.

v2.1 to v2.2

Headers middleware: accessControlAllowOrigin

accessControlAllowOrigin is deprecated. This field will be removed in future 2.x releases. Please configure your allowed origins in accessControlAllowOriginList instead.

Kubernetes CRD

In v2.2, new Kubernetes CRDs called TLSStore and IngressRouteUDP were added. While updating an installation to v2.2, one should apply that CRDs, and update the existing ClusterRole definition to allow Traefik to use that CRDs.

To add that CRDs and enhance the permissions, following definitions need to be applied to the cluster.

TLSStore

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: tlsstores.traefik.containo.us
  6. spec:
  7.   group: traefik.containo.us
  8.   version: v1alpha1
  9.   names:
  10.     kind: TLSStore
  11.     plural: tlsstores
  12.     singular: tlsstore
  13.   scope: Namespaced

IngressRouteUDP

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: ingressrouteudps.traefik.containo.us
  6. spec:
  7.   group: traefik.containo.us
  8.   version: v1alpha1
  9.   names:
  10.     kind: IngressRouteUDP
  11.     plural: ingressrouteudps
  12.     singular: ingressrouteudp
  13.   scope: Namespaced

ClusterRole

  1. kind: ClusterRole
  2. apiVersion: rbac.authorization.k8s.io/v1beta1
  3. metadata:
  4.   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.     resources:
  20.       - ingresses
  21.     verbs:
  22.       - get
  23.       - list
  24.       - watch
  25.   - apiGroups:
  26.       - extensions
  27.     resources:
  28.       - ingresses/status
  29.     verbs:
  30.       - update
  31.   - apiGroups:
  32.       - traefik.containo.us
  33.     resources:
  34.       - middlewares
  35.       - ingressroutes
  36.       - traefikservices
  37.       - ingressroutetcps
  38.       - ingressrouteudps
  39.       - tlsoptions
  40.       - tlsstores
  41.     verbs:
  42.       - get
  43.       - list
  44.       - watch

After having both resources applied, Traefik will work properly.

Kubernetes Ingress

To enable HTTPS, it is not sufficient anymore to only rely on a TLS section in the Ingress.

Expose an Ingress on 80 and 443

Define the default TLS configuration on the HTTPS entry point.

Ingress

  1. kind: Ingress
  2. apiVersion: networking.k8s.io/v1beta1
  3. metadata:
  4.   name: example
  6. spec:
  7.   tls:
  8.   - secretName: myTlsSecret
  10.   rules:
  11.   - host: example.com
  12.     http:
  13.       paths:
  14.       - path: "/foo"
  15.         backend:
  16.           serviceName: example-com
  17.           servicePort: 80

Entry points definition and enable Ingress provider:

File (YAML)

  1. # Static configuration
  3. entryPoints:
  4.   web:
  5.     address: :80
  6.   websecure:
  7.     address: :443
  8.     http:
  9.       tls: {}
  11. providers:
  12.   kubernetesIngress: {}

File (TOML)

  1. # Static configuration
  3. [entryPoints.web]
  4.   address = ":80"
  6. [entryPoints.websecure]
  7.   address = ":443"
  8.   [entryPoints.websecure.http]
  9.     [entryPoints.websecure.http.tls]
  11. [providers.kubernetesIngress]

CLI

  1. # Static configuration
  3. --entryPoints.web.address=:80
  4. --entryPoints.websecure.address=:443
  5. --entryPoints.websecure.http.tls=true
  6. --providers.kubernetesIngress=true

Use TLS only on one Ingress

Define the TLS restriction with annotations.

Ingress

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

Entry points definition and enable Ingress provider:

File (YAML)

  1. # Static configuration
  3. entryPoints:
  4.   web:
  5.     address: :80
  6.   websecure:
  7.     address: :443
  9. providers:
  10.   kubernetesIngress: {}

File (TOML)

  1. # Static configuration
  3. [entryPoints.web]
  4.   address = ":80"
  6. [entryPoints.websecure]
  7.   address = ":443"
  9. [providers.kubernetesIngress]

CLI

  1. # Static configuration
  3. --entryPoints.web.address=:80
  4. --entryPoints.websecure.address=:443
  5. --providers.kubernetesIngress=true

v2.2.2 to v2.2.5

InsecureSNI removal

In v2.2.2 we introduced a new flag (insecureSNI) which was available as a global option to disable domain fronting. Since v2.2.5 this global option has been removed, and you should not use it anymore.

HostSNI rule matcher removal

In v2.2.2 we introduced a new rule matcher (HostSNI) for HTTP routers which was allowing to match the Server Name Indication at the router level. Since v2.2.5 this rule has been removed for HTTP routers, and you should not use it anymore.

v2.2 to v2.3

X.509 CommonName Deprecation

The deprecated, legacy behavior of treating the CommonName field on X.509 certificates as a host name when no Subject Alternative Names are present, is now disabled by default.

It means that if one is using https with your backend servers, and a certificate with only a CommonName, Traefik will not try to match the server name indication with the CommonName anymore.

It can be temporarily re-enabled by adding the value x509ignoreCN=0 to the GODEBUG environment variable.

More information: https://golang.org/doc/go1.15#commonname

File Provider

The file parser has been changed, since v2.3 the unknown options/fields in a dynamic configuration file are treated as errors.

IngressClass

In v2.3, the support of IngressClass, which is available since Kubernetes version 1.18, has been introduced. In order to be able to use this new resource the Kubernetes RBAC must be updated.