traefik/docs/content/migration/v2-to-v3.md

109 lines
5 KiB
Markdown
Raw Normal View History

2022-10-26 15:16:05 +00:00
---
title: "Traefik V3 Migration Documentation"
description: "Migrate from Traefik Proxy v2 to v3 and update all the necessary configurations to take advantage of all the improvements. Read the technical documentation."
---
# Migration Guide: From v2 to v3
How to Migrate from Traefik v2 to Traefik v3.
{: .subtitle }
The version 3 of Traefik introduces a number of breaking changes,
which require one to update their configuration when they migrate from v2 to v3.
The goal of this page is to recapitulate all of these changes, and in particular to give examples,
feature by feature, of how the configuration looked like in v2, and how it now looks like in v3.
## IPWhiteList
In v3, we renamed the `IPWhiteList` middleware to `IPAllowList` without changing anything to the configuration.
## gRPC Metrics
2022-11-25 09:50:06 +00:00
In v3, the reported status code for gRPC requests is now the value of the `Grpc-Status` header.
## Deprecated Options Removal
- The `pilot` option has been removed from the static configuration.
- The `tracing.datadog.globaltag` option has been removed.
- The `namespace` option of Consul, Consul Catalog and Nomad providers has been removed.
2022-12-19 10:52:05 +00:00
- The `tls.caOptional` option has been removed from the ForwardAuth middleware, as well as from the HTTP, Consul, Etcd, Redis, ZooKeeper, Consul Catalog, and Docker providers.
2022-11-25 09:50:06 +00:00
- `sslRedirect`, `sslTemporaryRedirect`, `sslHost`, `sslForceHost` and `featurePolicy` options of the Headers middleware have been removed.
- The `forceSlash` option of the StripPrefix middleware has been removed.
2022-12-19 13:32:04 +00:00
- The `preferServerCipherSuites` option has been removed.
## Matchers
In v3, the `Headers` and `HeadersRegexp` matchers have been renamed to `Header` and `HeaderRegexp` respectively.
`PathPrefix` no longer uses regular expressions to match path prefixes.
`QueryRegexp` has been introduced to match query values using a regular expression.
`HeaderRegexp`, `HostRegexp`, `PathRegexp`, `QueryRegexp`, and `HostSNIRegexp` matchers now uses the [Go regexp syntax](https://golang.org/pkg/regexp/syntax/).
All matchers now take a single value (except `Header`, `HeaderRegexp`, `Query`, and `QueryRegexp` which take two)
and should be explicitly combined using logical operators to mimic previous behavior.
`Query` can take a single value to match is the query value that has no value (e.g. `/search?mobile`).
`HostHeader` has been removed, use `Host` instead.
## Content-Type Auto-Detection
In v3, the `Content-Type` header is not auto-detected anymore when it is not set by the backend.
One should use the `ContentType` middleware to enable the `Content-Type` header value auto-detection.
## HTTP/3
In v3, HTTP/3 is no longer an experimental feature.
The `experimental.http3` option has been removed from the static configuration.
## TCP ServersTransport
In v3, the support of `TCPServersTransport` has been introduced.
When using the KubernetesCRD provider, it is therefore necessary to update [RBAC](../reference/dynamic-configuration/kubernetes-crd.md#rbac) and [CRD](../reference/dynamic-configuration/kubernetes-crd.md) manifests.
### TCP LoadBalancer `terminationDelay` option
The TCP LoadBalancer `terminationDelay` option has been removed.
This option can now be configured directly on the `TCPServersTransport` level, please take a look at this [documentation](../routing/services/index.md#terminationdelay)
2022-12-19 09:42:05 +00:00
## Rancher v1
In v3, the rancher v1 provider has been removed because Rancher v1 is [no longer actively maintaned](https://rancher.com/docs/os/v1.x/en/support/) and v2 is supported as a standard Kubernetes provider.
Rancher 2.x requires Kubernetes and does not have a metadata endpoint of its own for Traefik to query.
As such, Rancher 2.x users should utilize the [Kubernetes CRD provider](../providers/kubernetes-crd.md) directly.
2022-12-19 10:52:05 +00:00
## Marathon provider
In v3, the Marathon provider has been removed.
2022-12-19 13:32:04 +00:00
## InfluxDB v1
In v3, the InfluxDB v1 metrics provider has been removed because InfluxDB v1.x maintenance [ended in 2021](https://www.influxdata.com/blog/influxdb-oss-and-enterprise-roadmap-update-from-influxdays-emea/).
2023-03-22 15:40:06 +00:00
### Kubernetes CRDs API Group `traefik.containo.us`
In v3, the Kubernetes CRDs API Group `traefik.containo.us` has been removed.
2023-03-22 15:40:06 +00:00
Please use the API Group `traefik.io` instead.
2023-05-10 13:28:05 +00:00
## Docker & Docker Swarm
In v3, the provider Docker has been split into 2 providers:
- Docker provider (without Swarm support)
- Swarm provider (Swarm support only)
### Kubernetes Ingress API Group `networking.k8s.io/v1beta1`
In v3, the Kubernetes Ingress API Group `networking.k8s.io/v1beta1` ([removed since Kubernetes v1.22](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#ingress-v122)) support has been removed.
Please use the API Group `networking.k8s.io/v1` instead.
### Traefik CRD API Version `apiextensions.k8s.io/v1beta1`
In v3, the Traefik CRD API Version `apiextensions.k8s.io/v1beta1` ([removed since Kubernetes v1.22](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#customresourcedefinition-v122)) support has been removed.
Please use the CRD definition with the API Version `apiextensions.k8s.io/v1` instead.