Migration: Steps needed between the versions¶

v3.0 to v3.1¶

Kubernetes Provider RBACs¶

Starting with v3.1, the Kubernetes Providers now use the EndpointSlices API (Kubernetes >=v1.21) to discover service endpoint addresses. It also brings NodePort load-balancing which requires Nodes resources lookup.

Therefore, in the corresponding RBACs (see KubernetesIngress, KubernetesCRD, and KubernetesGateway provider RBACs):

the endpoints right has to be removed and the following endpointslices right has to be added:

  ... 
  - apiGroups:
      - discovery.k8s.io
    resources:
      - endpointslices
    verbs:
      - list
      - watch
  ...

the nodes right has to be added:

  ...
  - apiGroups:
      - ""
    resources:
      - nodes
    verbs:
      - get
      - list
      - watch
  ...

Gateway API: KubernetesGateway Provider¶

In v3.1, the KubernetesGateway Provider is no longer an experimental feature. It can be enabled without the associated experimental.kubernetesgateway option, which is now deprecated.

An example of the experimental kubernetesgateway option

File (YAML)

experimental:
  kubernetesgateway: true

File (TOML)

[experimental]
    kubernetesgateway=true

CLI

--experimental.kubernetesgateway=true

Remediation¶

The kubernetesgateway option should be removed from the experimental section of the static configuration. To configure kubernetesgateway, please check out the KubernetesGateway Provider documentation.

v3.1.0 to v3.1.1¶

IngressClass Lookup¶

The Kubernetes Ingress provider option disableIngressClassLookup has been deprecated in v3.1.1, and will be removed in the next major version. Please use the disableClusterScopeResources option instead to avoid cluster scope resources discovery (IngressClass, Nodes).

v3.1 to v3.2¶

Kubernetes CRD Provider¶

Starting with v3.2, the CRDs has been updated on TraefikService (PR #11032), on RateLimit & InFlightReq middlewares (PR #9747) and on Compress middleware (PR #10943).

This update adds only new optional fields. CRDs can be updated with this command:

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.3/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

Kubernetes Gateway Provider Standard Channel¶

Starting with v3.2, the Kubernetes Gateway Provider now supports GRPCRoute.

Therefore, in the corresponding RBACs (see KubernetesGateway provider RBACs), the grcroutes and grpcroutes/status rights have to be added.

  ...
  - apiGroups:
      - gateway.networking.k8s.io
    resources:
      - grpcroutes
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - gateway.networking.k8s.io
    resources:
      - grpcroutes/status
    verbs:
      - update
  ...

Kubernetes Gateway Provider Experimental Channel¶

Breaking changes

Because of a breaking change introduced in Kubernetes Gateway v1.2.0-rc1, Traefik v3.3 only supports Kubernetes Gateway v1.2.x when experimental channel features are enabled.

Starting with v3.2, the Kubernetes Gateway Provider now supports BackendTLSPolicy.

Therefore, in the corresponding RBACs (see KubernetesGateway provider RBACs), the backendtlspolicies and backendtlspolicies/status rights have to be added.

  ...
  - apiGroups:
      - ""
    resources:
      - configmaps
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - gateway.networking.k8s.io
    resources:
      - backendtlspolicies
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - gateway.networking.k8s.io
    resources:
      - backendtlspolicies/status
    verbs:
      - update
  ...

v3.2.1¶

X-Forwarded-Prefix¶

In v3.2.1, the X-Forwarded-Prefix header is now handled like the other X-Forwarded-* headers: Traefik removes it when it's sent from an untrusted source. Please refer to the Forwarded headers documentation for more details.

v3.2.2¶

Swarm Provider¶

In v3.2.2, the traefik.docker.network and traefik.docker.lbswarm labels have been deprecated, please use the traefik.swarm.network and traefik.swarm.lbswarm labels instead.

v3.2 to v3.3¶

ACME DNS Certificate Resolver¶

In v3.3, the acme.dnsChallenge.delaybeforecheck and acme.dnsChallenge.disablepropagationcheck options of the ACME certificate resolver are deprecated, please use respectively acme.dnsChallenge.propagation.delayBeforeChecks and acme.dnsChallenge.propagation.disableChecks options instead.

Tracing Global Attributes¶

In v3.3, the tracing.globalAttributes option has been deprecated, please use the tracing.resourceAttributes option instead. The tracing.globalAttributes option is misleading as its name does not reflect the operation of adding resource attributes to be sent to the collector, and will be removed in the next major version.

v3.3.4¶

OpenTelemetry Request Duration metric¶

In v3.3.4, the OpenTelemetry Request Duration metric (named traefik_(entrypoint|router|service)_request_duration_seconds) unit has been changed from milliseconds to seconds. To be consistent with the naming and other metrics providers, the metric now reports the duration in seconds.

v3.3 to v3.4¶

Kubernetes CRD Provider¶

Load-Balancing¶

In v3.4, the HTTP service definition has been updated. The strategy field now supports two new values: wrr and p2c (please refer to the HTTP Services Load Balancing documentation for more details).

CRDs can be updated with this command:

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

Please note that the RoundRobin strategy value is now deprecated, but still supported and equivalent to wrr, and will be removed in the next major release.

ServersTransport CA Certificate¶

In v3.4, a new rootCAs option has been added to the ServersTransport and ServersTransportTCP CRDs. It allows the configuration of CA certificates from both ConfigMaps and Secrets, and replaces the rootCAsSecrets option, as shown below:

---
apiVersion: traefik.io/v1alpha1
kind: ServersTransport
metadata:
  name: foo
  namespace: bar
spec:
  rootCAs:
    - configMap: ca-config-map
    - secret: ca-secret

---      
apiVersion: traefik.io/v1alpha1
kind: ServersTransportTCP
metadata:
  name: foo
  namespace: bar
spec:
  rootCAs:
    - configMap: ca-config-map
    - secret: ca-secret

The rootCAsSecrets option, which allows only Secrets references, is still supported, but is now deprecated, and will be removed in the next major release.

Rule Syntax¶

In v3.4.0, the core.defaultRuleSyntax static configuration option and the ruleSyntax router option have been deprecated, and will be removed in the next major version.

This core.defaultRuleSyntax option was used to switch between the v2 and v3 syntax for the router's rules, and to help with the migration from v2 to v3.

The ruleSyntax router's option was used to override the default rule syntax for a specific router.

In preparation for the next major release, please remove any use of these two options and use the v3 syntax for writing the router's rules.