diff --git a/docs/content/deprecation/features.md b/docs/content/deprecation/features.md index 50b42873b..1cf2355df 100644 --- a/docs/content/deprecation/features.md +++ b/docs/content/deprecation/features.md @@ -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. diff --git a/docs/content/migration/v2-to-v3.md b/docs/content/migration/v2-to-v3.md index b9a2fd769..dcc7505a1 100644 --- a/docs/content/migration/v2-to-v3.md +++ b/docs/content/migration/v2-to-v3.md @@ -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. diff --git a/docs/content/reference/static-configuration/cli-ref.md b/docs/content/reference/static-configuration/cli-ref.md index 8f6441ea9..8e64fd2ae 100644 --- a/docs/content/reference/static-configuration/cli-ref.md +++ b/docs/content/reference/static-configuration/cli-ref.md @@ -201,9 +201,6 @@ WriteTimeout is the maximum duration before timing out writes of the response. I `--entrypoints..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```) diff --git a/docs/content/reference/static-configuration/env-ref.md b/docs/content/reference/static-configuration/env-ref.md index 2a8302879..36dd4040c 100644 --- a/docs/content/reference/static-configuration/env-ref.md +++ b/docs/content/reference/static-configuration/env-ref.md @@ -201,9 +201,6 @@ WriteTimeout is the maximum duration before timing out writes of the response. I `TRAEFIK_ENTRYPOINTS__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```) diff --git a/docs/content/reference/static-configuration/file.toml b/docs/content/reference/static-configuration/file.toml index 5ae9a9356..6d75b4dbc 100644 --- a/docs/content/reference/static-configuration/file.toml +++ b/docs/content/reference/static-configuration/file.toml @@ -459,7 +459,6 @@ [experimental] kubernetesGateway = true - http3 = true [experimental.plugins] [experimental.plugins.Descriptor0] moduleName = "foobar" diff --git a/docs/content/reference/static-configuration/file.yaml b/docs/content/reference/static-configuration/file.yaml index 0dc2390c2..4410e29eb 100644 --- a/docs/content/reference/static-configuration/file.yaml +++ b/docs/content/reference/static-configuration/file.yaml @@ -489,7 +489,6 @@ certificatesResolvers: tailscale: {} experimental: kubernetesGateway: true - http3: true plugins: Descriptor0: moduleName: foobar diff --git a/pkg/config/static/experimental.go b/pkg/config/static/experimental.go index 936dfd534..7428f6a08 100644 --- a/pkg/config/static/experimental.go +++ b/pkg/config/static/experimental.go @@ -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"` }