Improve migration guide
Co-authored-by: Baptiste Mayelle <baptiste.mayelle@traefik.io>
This commit is contained in:
Romain
GitHub
parent
a69c1ba3b7
commit
45bb00be04
7 changed files with 348 additions and 66 deletions
|
|
@ -4,20 +4,23 @@ This page is maintained and updated periodically to reflect our roadmap and any
|
|||
|
||||
| Feature | Deprecated | End of Support | Removal |
|
||||
|----------------------------------------------------------------------------------------------------------------------|------------|----------------|---------|
|
||||
| [Kubernetes CRDs API Version `traefik.io/v1alpha1`](#kubernetes-crds-api-version-traefikiov1alpha1) | 3.0 | N/A | 4.0 |
|
||||
| [Kubernetes CRD Provider API Version `traefik.io/v1alpha1`](#kubernetes-crd-provider-api-version-traefikiov1alpha1) | 3.0 | N/A | 4.0 |
|
||||
| [Kubernetes Ingress API Version `networking.k8s.io/v1beta1`](#kubernetes-ingress-api-version-networkingk8siov1beta1) | N/A | N/A | 3.0 |
|
||||
| [CRD API Version `apiextensions.k8s.io/v1beta1`](#kubernetes-ingress-api-version-networkingk8siov1beta1) | N/A | N/A | 3.0 |
|
||||
|
||||
## Impact
|
||||
|
||||
### Kubernetes CRDs API Version `traefik.io/v1alpha1`
|
||||
### Kubernetes CRD Provider API Version `traefik.io/v1alpha1`
|
||||
|
||||
The Kubernetes CRD provider API Version `traefik.io/v1alpha1` will subsequently be deprecated in Traefik v3. The next version will be `traefik.io/v1`.
|
||||
The Kubernetes CRD provider API Version `traefik.io/v1alpha1` is deprecated in Traefik v3.
|
||||
Please use the API Group `traefik.io/v1` instead.
|
||||
|
||||
### Kubernetes Ingress API Version `networking.k8s.io/v1beta1`
|
||||
|
||||
The Kubernetes Ingress API Version `networking.k8s.io/v1beta1` is removed in v3. Please use the API Group `networking.k8s.io/v1` instead.
|
||||
The Kubernetes Ingress API Version `networking.k8s.io/v1beta1` support is removed in v3.
|
||||
Please use the API Group `networking.k8s.io/v1` instead.
|
||||
|
||||
### Traefik CRD API Version `apiextensions.k8s.io/v1beta1`
|
||||
### Traefik CRD Definitions API Version `apiextensions.k8s.io/v1beta1`
|
||||
|
||||
The Traefik CRD API Version `apiextensions.k8s.io/v1beta1` is removed in v3. Please use the API Group `apiextensions.k8s.io/v1` instead.
|
||||
The Traefik CRD definitions API Version `apiextensions.k8s.io/v1beta1` support is removed in v3.
|
||||
Please use the API Group `apiextensions.k8s.io/v1` instead.
|
||||
|
|
|
|||
|
|
@ -10,28 +10,335 @@ How to Migrate from Traefik v2 to Traefik v3.
|
|||
|
||||
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.
|
||||
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
|
||||
## Static configuration
|
||||
|
||||
### Docker & Docker Swarm
|
||||
|
||||
In v3, the provider Docker has been split into 2 providers:
|
||||
|
||||
- Docker provider (without Swarm support)
|
||||
- Swarm provider (Swarm support only)
|
||||
|
||||
??? example "An example usage of v2 Docker provider with Swarm"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
docker:
|
||||
swarmMode: true
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.docker]
|
||||
swarmMode=true
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.docker.swarmMode=true
|
||||
```
|
||||
|
||||
This configuration is now unsupported and would prevent Traefik to start.
|
||||
|
||||
#### Remediation
|
||||
|
||||
In v3, the `swarmMode` should not be used with the Docker provider, and, to use Swarm, the Swarm provider should be used instead.
|
||||
|
||||
??? example "An example usage of the Swarm provider"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
swarm:
|
||||
endpoint: "tcp://127.0.0.1:2377"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.swarm]
|
||||
endpoint="tcp://127.0.0.1:2377"
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.swarm.endpoint=tcp://127.0.0.1:2377
|
||||
```
|
||||
|
||||
### HTTP3 Experimental Configuration
|
||||
|
||||
In v3, HTTP/3 is no longer an experimental feature.
|
||||
It can be enabled on entry points without the associated `experimental.http3` option, which is now removed.
|
||||
It is now unsupported and would prevent Traefik to start.
|
||||
|
||||
??? example "An example usage of v2 Experimental `http3` option"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
experimental:
|
||||
http3: true
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[experimental]
|
||||
http3=true
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--experimental.http3=true
|
||||
```
|
||||
|
||||
#### Remediation
|
||||
|
||||
The `http3` option should be removed from the static configuration experimental section.
|
||||
|
||||
### Consul provider
|
||||
|
||||
The Consul provider `namespace` option was deprecated in v2 and is now removed in v3.
|
||||
It is now unsupported and would prevent Traefik to start.
|
||||
|
||||
??? example "An example usage of v2 Consul `namespace` option"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
consul:
|
||||
namespace: foobar
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[consul]
|
||||
namespace=foobar
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--consul.namespace=foobar
|
||||
```
|
||||
|
||||
#### Remediation
|
||||
|
||||
In v3, the `namespaces` option should be used instead of the `namespace` option.
|
||||
|
||||
??? example "An example usage of Consul `namespaces` option"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
consul:
|
||||
namespaces:
|
||||
- foobar
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[consul]
|
||||
namespaces=["foobar"]
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--consul.namespaces=foobar
|
||||
```
|
||||
|
||||
### ConsulCatalog provider
|
||||
|
||||
The ConsulCatalog provider `namespace` option was deprecated in v2 and is now removed in v3.
|
||||
It is now unsupported and would prevent Traefik to start.
|
||||
|
||||
??? example "An example usage of v2 ConsulCatalog `namespace` option"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
consulCatalog:
|
||||
namespace: foobar
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[consulCatalog]
|
||||
namespace=foobar
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--consulCatalog.namespace=foobar
|
||||
```
|
||||
|
||||
#### Remediation
|
||||
|
||||
In v3, the `namespaces` option should be used instead of the `namespace` option.
|
||||
|
||||
??? example "An example usage of ConsulCatalog `namespaces` option"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
consulCatalog:
|
||||
namespaces:
|
||||
- foobar
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[consulCatalog]
|
||||
namespaces=["foobar"]
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--consulCatalog.namespaces=foobar
|
||||
```
|
||||
|
||||
### Nomad provider
|
||||
|
||||
The Nomad provider `namespace` option was deprecated in v2 and is now removed in v3.
|
||||
It is now unsupported and would prevent Traefik to start.
|
||||
|
||||
??? example "An example usage of v2 Nomad `namespace` option"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
nomad:
|
||||
namespace: foobar
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[nomad]
|
||||
namespace=foobar
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--nomad.namespace=foobar
|
||||
```
|
||||
|
||||
#### Remediation
|
||||
|
||||
In v3, the `namespaces` option should be used instead of the `namespace` option.
|
||||
|
||||
??? example "An example usage of Nomad `namespaces` option"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
nomad:
|
||||
namespaces:
|
||||
- foobar
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[nomad]
|
||||
namespaces=["foobar"]
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--nomad.namespaces=foobar
|
||||
```
|
||||
|
||||
### Rancher v1 Provider
|
||||
|
||||
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 Rancher v2 is supported as a standard Kubernetes provider.
|
||||
|
||||
??? example "An example of Traefik v2 Rancher v1 configuration"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
rancher: {}
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.rancher]
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.rancher=true
|
||||
```
|
||||
|
||||
This configuration is now unsupported and would prevent Traefik to start.
|
||||
|
||||
#### Remediation
|
||||
|
||||
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.
|
||||
|
||||
Also, all Rancher provider related configuration should be removed from the static configuration.
|
||||
|
||||
### Marathon provider
|
||||
|
||||
Marathon maintenance [ended on October 31, 2021](https://github.com/mesosphere/marathon/blob/master/README.md).
|
||||
In v3, the Marathon provider has been removed.
|
||||
|
||||
??? example "An example of v2 Marathon provider configuration"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
providers:
|
||||
marathon: {}
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[providers.marathon]
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--providers.marathon=true
|
||||
```
|
||||
|
||||
This configuration is now unsupported and would prevent Traefik to start.
|
||||
|
||||
#### Remediation
|
||||
|
||||
All Marathon provider related configuration should be removed from the static configuration.
|
||||
|
||||
### InfluxDB v1
|
||||
|
||||
InfluxDB v1.x maintenance [ended in 2021](https://www.influxdata.com/blog/influxdb-oss-and-enterprise-roadmap-update-from-influxdays-emea/).
|
||||
In v3, the InfluxDB v1 metrics provider has been removed.
|
||||
|
||||
??? example "An example of Traefik v2 InfluxDB v1 metrics configuration"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
metrics:
|
||||
influxDB: {}
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[metrics.influxDB]
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--metrics.influxDB=true
|
||||
```
|
||||
|
||||
This configuration is now unsupported and would prevent Traefik to start.
|
||||
|
||||
#### Remediation
|
||||
|
||||
All InfluxDB v1 metrics provider related configuration should be removed from the static configuration.
|
||||
|
||||
### Pilot
|
||||
|
||||
Traefik Pilot is no longer available since October 4th, 2022.
|
||||
|
||||
??? example "An example of v2 Pilot configuration"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
pilot:
|
||||
token: foobar
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[pilot]
|
||||
token=foobar
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--pilot.token=foobar
|
||||
```
|
||||
|
||||
In v2, Pilot configuration was deprecated and ineffective,
|
||||
it is now unsupported and would prevent Traefik to start.
|
||||
|
||||
#### Remediation
|
||||
|
||||
All Pilot related configuration should be removed from the static configuration.
|
||||
|
||||
## Dynamic configuration
|
||||
|
||||
### IPWhiteList
|
||||
|
||||
In v3, we renamed the `IPWhiteList` middleware to `IPAllowList` without changing anything to the configuration.
|
||||
|
||||
## gRPC Metrics
|
||||
### Deprecated Options Removal
|
||||
|
||||
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.
|
||||
- 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.
|
||||
- `sslRedirect`, `sslTemporaryRedirect`, `sslHost`, `sslForceHost` and `featurePolicy` options of the Headers middleware have been removed.
|
||||
- The `forceSlash` option of the StripPrefix middleware has been removed.
|
||||
- The `preferServerCipherSuites` option has been removed.
|
||||
|
||||
## Matchers
|
||||
### Matchers
|
||||
|
||||
In v3, the `Headers` and `HeadersRegexp` matchers have been renamed to `Header` and `HeaderRegexp` respectively.
|
||||
|
||||
|
|
@ -48,61 +355,42 @@ and should be explicitly combined using logical operators to mimic previous beha
|
|||
|
||||
`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)
|
||||
|
||||
## 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.
|
||||
|
||||
## Marathon provider
|
||||
|
||||
In v3, the Marathon provider has been removed.
|
||||
|
||||
## 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/).
|
||||
|
||||
## Kubernetes CRDs API Group `traefik.containo.us`
|
||||
### Kubernetes CRDs API Group `traefik.containo.us`
|
||||
|
||||
In v3, the Kubernetes CRDs API Group `traefik.containo.us` has been removed.
|
||||
Please use the API Group `traefik.io` instead.
|
||||
|
||||
## 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`
|
||||
### 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`
|
||||
### 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.
|
||||
|
||||
## Operations
|
||||
|
||||
### Traefik RBAC Update
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Observability
|
||||
|
||||
#### gRPC Metrics
|
||||
|
||||
In v3, the reported status code for gRPC requests is now the value of the `Grpc-Status` header.
|
||||
|
|
|
|||
|
|
@ -201,9 +201,6 @@ WriteTimeout is the maximum duration before timing out writes of the response. I
|
|||
`--entrypoints.<name>.udp.timeout`:
|
||||
Timeout defines how long to wait on an idle session before releasing the related resources. (Default: ```3```)
|
||||
|
||||
`--experimental.http3`:
|
||||
Enable HTTP3. (Default: ```false```)
|
||||
|
||||
`--experimental.kubernetesgateway`:
|
||||
Allow the Kubernetes gateway api provider usage. (Default: ```false```)
|
||||
|
||||
|
|
|
|||
|
|
@ -201,9 +201,6 @@ WriteTimeout is the maximum duration before timing out writes of the response. I
|
|||
`TRAEFIK_ENTRYPOINTS_<NAME>_UDP_TIMEOUT`:
|
||||
Timeout defines how long to wait on an idle session before releasing the related resources. (Default: ```3```)
|
||||
|
||||
`TRAEFIK_EXPERIMENTAL_HTTP3`:
|
||||
Enable HTTP3. (Default: ```false```)
|
||||
|
||||
`TRAEFIK_EXPERIMENTAL_KUBERNETESGATEWAY`:
|
||||
Allow the Kubernetes gateway api provider usage. (Default: ```false```)
|
||||
|
||||
|
|
|
|||
|
|
@ -459,7 +459,6 @@
|
|||
|
||||
[experimental]
|
||||
kubernetesGateway = true
|
||||
http3 = true
|
||||
[experimental.plugins]
|
||||
[experimental.plugins.Descriptor0]
|
||||
moduleName = "foobar"
|
||||
|
|
|
|||
|
|
@ -489,7 +489,6 @@ certificatesResolvers:
|
|||
tailscale: {}
|
||||
experimental:
|
||||
kubernetesGateway: true
|
||||
http3: true
|
||||
plugins:
|
||||
Descriptor0:
|
||||
moduleName: foobar
|
||||
|
|
|
|||
|
|
@ -8,5 +8,4 @@ type Experimental struct {
|
|||
LocalPlugins map[string]plugins.LocalDescriptor `description:"Local plugins configuration." json:"localPlugins,omitempty" toml:"localPlugins,omitempty" yaml:"localPlugins,omitempty" export:"true"`
|
||||
|
||||
KubernetesGateway bool `description:"Allow the Kubernetes gateway api provider usage." json:"kubernetesGateway,omitempty" toml:"kubernetesGateway,omitempty" yaml:"kubernetesGateway,omitempty" export:"true"`
|
||||
HTTP3 bool `description:"Enable HTTP3." json:"http3,omitempty" toml:"http3,omitempty" yaml:"http3,omitempty" export:"true"`
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue