---
title: "Traefik Migration Documentation"
description: "Learn the steps needed to migrate to new Traefik Proxy v3 versions. Read the technical documentation."
---

# 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](https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/) (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](../routing/providers/kubernetes-ingress.md#configuration-example), [KubernetesCRD](../reference/dynamic-configuration/kubernetes-crd.md#rbac), and [KubernetesGateway](../reference/dynamic-configuration/kubernetes-gateway-rbac.yml) provider RBACs):

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

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

- the `nodes` right has to be added:

```yaml
  ...
  - 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.

??? example "An example of the experimental `kubernetesgateway` option"

    ```yaml tab="File (YAML)"
    experimental:
      kubernetesgateway: true
    ```

    ```toml tab="File (TOML)"
    [experimental]
        kubernetesgateway=true
    ```

    ```bash tab="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](../providers/kubernetes-gateway.md).

## 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](../../routing/services#mirroring-service) (PR [#11032](https://github.com/traefik/traefik/pull/11032)), on [RateLimit](../../middlewares/http/ratelimit) & [InFlightReq](../../middlewares/http/inflightreq) middlewares (PR [#9747](https://github.com/traefik/traefik/pull/9747)) and on [Compress](../../middlewares/http/compress) middleware (PR [#10943](https://github.com/traefik/traefik/pull/10943)).

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

```shell
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](https://gateway-api.sigs.k8s.io/api-types/grpcroute/).

Therefore, in the corresponding RBACs (see [KubernetesGateway](../reference/dynamic-configuration/kubernetes-gateway-rbac.yml) provider RBACs),
the `grcroutes` and `grpcroutes/status` rights have to be added.

```yaml
  ...
  - 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

!!! warning "Breaking changes"

    Because of a breaking change introduced in Kubernetes Gateway [v1.2.0-rc1](https://github.com/kubernetes-sigs/gateway-api/releases/tag/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](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/).

Therefore, in the corresponding RBACs (see [KubernetesGateway](../reference/dynamic-configuration/kubernetes-gateway-rbac.yml) provider RBACs),
the `backendtlspolicies` and `backendtlspolicies/status` rights have to be added.

```yaml
  ...
  - 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](../routing/entrypoints.md#forwarded-headers) 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.5

### Compress Middleware

In `v3.3.5`, the compress middleware `encodings` option default value is now `gzip, br, zstd`. 
This change helps the algorithm selection to favor the `gzip` algorithm over the other algorithms.

It impacts requests that do not specify their preferred algorithm,
or has no order preference, in the `Accept-Encoding` header.

## v3.3.6

### Request Path Sanitization

Since `v3.3.6`, the incoming request path is now cleaned before being used to match the router rules and sent to the backends.
Any `/../`, `/./` or duplicate slash segments in the request path is interpreted and/or collapsed.

If you want to disable this behavior, you can set the [`sanitizePath` option](../reference/install-configuration/entrypoints.md#sanitizepath) to `false` in the entryPoint HTTP configuration.
This can be useful when dealing with legacy clients that are not url-encoding data in the request path.
For example, as base64 uses the “/” character internally,
if it's not url encoded,
it can lead to unsafe routing when the `sanitizePath` option is set to `false`.

!!! warning "Security"

    Setting the `sanitizePath` option to `false` is not safe.
    Ensure every request is properly url encoded instead.

## 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](../../routing/services/#load-balancing-strategy) for more details).

CRDs can be updated with this command:

```shell
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:

CRDs can be updated with this command:

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

RBACs need to be updated with this command:

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

```yaml
---
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.

## v3.4.1

### Request Path Normalization

Since `v3.4.1`, the request path is now normalized by decoding unreserved characters in the request path,
and also uppercasing the percent-encoded characters.
This follows [RFC 3986 percent-encoding normalization](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2),
and [RFC 3986 case normalization](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1).

The normalization happens before the request path is sanitized,
and cannot be disabled.
This notably helps with encoded dots characters (which are unreserved characters) to be sanitized properly.

### Routing Path

Since `v3.4.1`, the reserved characters [(as per RFC 3986)](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) are kept encoded in the request path when matching the router rules.
Those characters, when decoded, change the meaning of the request path for routing purposes,
and Traefik now keeps them encoded to avoid any ambiguity.

### Request Path Matching Examples

| Request Path      | Router Rule            | Traefik v3.4.0 | Traefik v3.4.1 |
|-------------------|------------------------|----------------|----------------|
| `/foo%2Fbar`      | PathPrefix(`/foo/bar`) | Match          | No match       |
| `/foo/../bar`     | PathPrefix(`/foo`)     | No match       | No match       |
| `/foo/../bar`     | PathPrefix(`/bar`)     | Match          | Match          |
| `/foo/%2E%2E/bar` | PathPrefix(`/foo`)     | Match          | No match       |
| `/foo/%2E%2E/bar` | PathPrefix(`/bar`)     | No match       | Match          |