mirror of
https://github.com/traefik/traefik.git
synced 2025-08-06 06:37:09 +02:00
Merge branch v3.4 into v3.5
This commit is contained in:
romain
commit
a274f52924
@ -33,7 +33,7 @@ Below is a non-exhaustive list of versions and their maintenance status:
|
||||
|
||||
This page is maintained and updated periodically to reflect our roadmap and any decisions affecting the end of support for Traefik Proxy.
|
||||
|
||||
Please refer to our migration guides for specific instructions on upgrading between versions, an example is the [v2 to v3 migration guide](../migration/v2-to-v3.md).
|
||||
Please refer to our migration guides for specific instructions on upgrading between versions, an example is the [v2 to v3 migration guide](../migrate/v2-to-v3.md).
|
||||
|
||||
!!! important "All target dates for end of support or feature removal announcements may be subject to change."
|
||||
|
||||
|
||||
161
docs/content/migrate/v2-to-v3.md
Normal file
161
docs/content/migrate/v2-to-v3.md
Normal file
@ -0,0 +1,161 @@
|
||||
---
|
||||
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 }
|
||||
|
||||
!!! success "Streamlined Migration Process"
|
||||
Traefik v3 introduces minimal breaking changes and maintains backward compatibility with v2 syntax in dynamic configuration, offering a gradual migration path.
|
||||
|
||||
With Traefik v3, we are introducing a streamlined transition process from v2. Minimal breaking changes have been made to specific options in the [static configuration](./v2-to-v3-details.md#static-configuration-changes "Link to static configuration changes"), and we are ensuring backward compatibility with v2 syntax in the [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes"). This will offer a gradual path for adopting the v3 syntax, allowing users to progressively migrate their Kubernetes ingress resources, Docker labels, etc., to the new format.
|
||||
|
||||
## Migration Overview
|
||||
|
||||
The migration process consists of three progressive steps designed to minimize risk and ensure a smooth transition:
|
||||
|
||||
!!! abstract "Migration Steps"
|
||||
**Step 1:** [Prepare configurations and test v3](#step-1-prepare-configurations-and-test-v3)
|
||||
**Step 2:** [Migrate production instances to Traefik v3](#step-2-migrate-production-instances-to-traefik-v3)
|
||||
**Step 3:** [Progressively migrate dynamic configuration](#step-3-progressively-migrate-dynamic-configuration)
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Prepare Configurations and Test v3
|
||||
|
||||
!!! info "Preparation Phase"
|
||||
This step focuses on updating static configurations and enabling backward compatibility for a safe testing environment.
|
||||
|
||||
### Configuration Updates
|
||||
|
||||
**Review and Update Static Configuration**
|
||||
|
||||
Check the changes in [static configurations](./v2-to-v3-details.md#static-configuration-changes "Link to static configuration changes") and [operations](./v2-to-v3-details.md#operations-changes "Link to operations changes") brought by Traefik v3. Modify your configurations accordingly.
|
||||
|
||||
**Enable v2 Compatibility Mode**
|
||||
|
||||
Add the following configuration to maintain v2 syntax compatibility:
|
||||
|
||||
```yaml
|
||||
# static configuration
|
||||
core:
|
||||
defaultRuleSyntax: v2
|
||||
```
|
||||
|
||||
!!! note "Backward Compatibility"
|
||||
This snippet in the static configuration makes the [v2 format](../migrate/v2-to-v3-details.md#configure-the-default-syntax-in-static-configuration "Link to configure default syntax in static config") the default rule matchers syntax.
|
||||
|
||||
### Testing Phase
|
||||
|
||||
**Start Your Test Environment**
|
||||
|
||||
1. Start Traefik v3 with the updated configuration
|
||||
2. Monitor the startup logs for any errors
|
||||
3. Test routing to your applications
|
||||
|
||||
**Validation Checklist**
|
||||
|
||||
- ✅ Traefik starts without error logs
|
||||
- ✅ All routes are functioning correctly
|
||||
- ✅ Applications are accessible through Traefik
|
||||
|
||||
!!! success "Ready for Next Step"
|
||||
If you don't get any error logs while testing, you are good to go! Otherwise, follow the remaining migration options highlighted in the logs.
|
||||
|
||||
Once your Traefik test instances are starting and routing to your applications, proceed to the next step.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Migrate Production Instances to Traefik v3
|
||||
|
||||
!!! warning "Production Migration"
|
||||
This is the critical step where you migrate your production environment. Proper monitoring and rollback preparation are essential.
|
||||
|
||||
### Migration Strategy
|
||||
|
||||
**Progressive Deployment**
|
||||
|
||||
We strongly advise you to follow a progressive migration strategy ([Kubernetes rolling update mechanism](https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/ "Link to the Kubernetes rolling update documentation"), for example) to migrate your production instances to v3.
|
||||
|
||||
**Required Preparations**
|
||||
|
||||
!!! danger "Critical Requirements"
|
||||
- ✅ **Real-time monitoring solution** for ingress traffic ([monitoring guide](https://traefik.io/blog/capture-traefik-metrics-for-apps-on-kubernetes-with-prometheus/ "Link to the blog on capturing Traefik metrics with Prometheus"))
|
||||
- ✅ **Rollback plan** ready for immediate execution
|
||||
- ✅ **Team availability** during migration window
|
||||
|
||||
### Migration Execution
|
||||
|
||||
**During Migration:**
|
||||
|
||||
1. **Monitor continuously:** Watch ingress traffic for any errors or anomalies
|
||||
2. **Be prepared to rollback:** Have your rollback procedure ready to execute immediately
|
||||
3. **Use debug logs:** Leverage debug and access logs to understand any issues that arise
|
||||
|
||||
**Validation Steps:**
|
||||
|
||||
- Monitor response times and error rates
|
||||
- Verify all critical application paths are working
|
||||
- Check that SSL/TLS termination is functioning correctly
|
||||
- Validate middleware behavior
|
||||
|
||||
!!! success "Migration Complete"
|
||||
Once every Traefik instance is updated, you will be on Traefik v3!
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Progressively Migrate Dynamic Configuration
|
||||
|
||||
!!! info "Optional Immediate Step"
|
||||
This step can be done later in the process, as Traefik v3 is compatible with the v2 format for [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes"). Enable Traefik logs to get some help if any deprecated option is in use.
|
||||
|
||||
### Migration Process
|
||||
|
||||
**Review Dynamic Configuration Changes**
|
||||
|
||||
Check the changes in [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes") to understand what updates are needed.
|
||||
|
||||
**Progressive Router Migration**
|
||||
|
||||
1. **Select a router** to migrate first (start with non-critical services)
|
||||
2. **[Switch to v3 syntax](./v2-to-v3-details.md#configure-the-syntax-per-router "Link to configuring the syntax per router")** for that specific router
|
||||
3. **Test thoroughly** to ensure ingress traffic is not impacted
|
||||
4. **Deploy and validate** the updated resource
|
||||
5. **Remove the old v2 resource** once validation is complete
|
||||
6. **Repeat** for each remaining router
|
||||
|
||||
### Migration Best Practices
|
||||
|
||||
!!! tip "Migration Strategy"
|
||||
- Start with development or staging environments
|
||||
- Migrate one service at a time
|
||||
- Test each migration thoroughly before proceeding
|
||||
- Keep detailed logs of what was changed
|
||||
|
||||
### Final Configuration Cleanup
|
||||
|
||||
Once all Ingress resources are migrated to v3 syntax, remove the compatibility configuration:
|
||||
|
||||
```yaml
|
||||
# Remove this from static configuration
|
||||
core:
|
||||
defaultRuleSyntax: v2 # ← Delete this entire section
|
||||
```
|
||||
|
||||
!!! success "🎉 Migration Complete!"
|
||||
You are now fully migrated to Traefik v3 and can take advantage of all the new features and improvements!
|
||||
|
||||
### Post-Migration Verification
|
||||
|
||||
**Final Checklist:**
|
||||
|
||||
- ✅ All routers use v3 syntax
|
||||
- ✅ v2 compatibility mode disabled
|
||||
- ✅ No deprecated warnings in logs
|
||||
- ✅ All applications functioning correctly
|
||||
- ✅ Performance metrics stable
|
||||
|
||||
{!traefik-for-business-applications.md!}
|
||||
422
docs/content/migrate/v3.md
Normal file
422
docs/content/migrate/v3.md
Normal file
@ -0,0 +1,422 @@
|
||||
---
|
||||
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
|
||||
|
||||
This guide provides detailed migration steps for upgrading between different Traefik v3 versions. Each section covers breaking changes, deprecations, and configuration updates required for a smooth transition.
|
||||
|
||||
---
|
||||
|
||||
## v3.0 to v3.1
|
||||
|
||||
### Kubernetes Provider RBACs
|
||||
|
||||
Starting with v3.1, Traefik's Kubernetes Providers use the [EndpointSlices API](https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/) (requires Kubernetes >=v1.21) for service endpoint discovery. This change also introduces NodePort load-balancing capabilities.
|
||||
|
||||
The following RBAC updates are required for all Kubernetes providers:
|
||||
|
||||
- Remove endpoints permissions and add endpointslices:
|
||||
|
||||
```yaml
|
||||
# Remove this section from your RBAC
|
||||
# - apiGroups: [""]
|
||||
# resources: ["endpoints"]
|
||||
# verbs: ["get", "list", "watch"]
|
||||
|
||||
# Add this section instead
|
||||
- apiGroups:
|
||||
- discovery.k8s.io
|
||||
resources:
|
||||
- endpointslices
|
||||
verbs:
|
||||
- list
|
||||
- watch
|
||||
```
|
||||
|
||||
- Add nodes permissions for NodePort support:
|
||||
|
||||
```yaml
|
||||
- apiGroups:
|
||||
- ""
|
||||
resources:
|
||||
- nodes
|
||||
verbs:
|
||||
- get
|
||||
- list
|
||||
- watch
|
||||
```
|
||||
|
||||
!!! note "Affected Providers"
|
||||
These changes apply to:
|
||||
|
||||
- [KubernetesIngress](../routing/providers/kubernetes-ingress.md#configuration-example) provider
|
||||
- [KubernetesCRD](../reference/dynamic-configuration/kubernetes-crd.md#rbac) provider
|
||||
- [KubernetesGateway](../reference/dynamic-configuration/kubernetes-gateway-rbac.yml) provider
|
||||
|
||||
#### Gateway API: KubernetesGateway Provider
|
||||
|
||||
The KubernetesGateway Provider is no longer experimental in v3.1 and can be enabled without the `experimental.kubernetesgateway` option.
|
||||
|
||||
**Deprecated Configuration:**
|
||||
|
||||
??? example "Experimental kubernetesgateway option (deprecated)"
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
experimental:
|
||||
kubernetesgateway: true
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[experimental]
|
||||
kubernetesgateway=true
|
||||
```
|
||||
|
||||
```bash tab="CLI"
|
||||
--experimental.kubernetesgateway=true
|
||||
```
|
||||
|
||||
**Migration Steps:**
|
||||
|
||||
1. Remove the `kubernetesgateway` option from the experimental section
|
||||
2. Configure the provider using the [KubernetesGateway Provider documentation](../providers/kubernetes-gateway.md)
|
||||
|
||||
---
|
||||
|
||||
## v3.1.0 to v3.1.1
|
||||
|
||||
### IngressClass Lookup
|
||||
|
||||
The `disableIngressClassLookup` option has been deprecated and will be removed in the next major version.
|
||||
|
||||
**Migration Required:**
|
||||
|
||||
- **Old:** `disableIngressClassLookup`
|
||||
- **New:** `disableClusterScopeResources`
|
||||
|
||||
The new option provides broader control over cluster scope resources discovery, including both IngressClass and Nodes resources.
|
||||
|
||||
---
|
||||
|
||||
## v3.1 to v3.2
|
||||
|
||||
### Kubernetes CRD Provider
|
||||
|
||||
New optional fields have been added to several CRDs. These updates are backward compatible and only add new functionality.
|
||||
|
||||
**Apply the latest CRDs:**
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.3/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml
|
||||
```
|
||||
|
||||
**Updated Resources:**
|
||||
|
||||
- [TraefikService](../../routing/services#mirroring-service) ([PR #11032](https://github.com/traefik/traefik/pull/11032))
|
||||
- [RateLimit](../../middlewares/http/ratelimit) & [InFlightReq](../../middlewares/http/inflightreq) middlewares ([PR #9747](https://github.com/traefik/traefik/pull/9747))
|
||||
- [Compress](../../middlewares/http/compress) middleware ([PR #10943](https://github.com/traefik/traefik/pull/10943))
|
||||
|
||||
### 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/) resources.
|
||||
|
||||
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.
|
||||
|
||||
**Required RBAC Updates:**
|
||||
|
||||
```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
|
||||
|
||||
Due to breaking changes 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 features are enabled.
|
||||
|
||||
**New Feature: BackendTLSPolicy Support**
|
||||
|
||||
The provider now supports [BackendTLSPolicy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/) resources.
|
||||
|
||||
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.
|
||||
|
||||
**Required RBAC Updates:**
|
||||
|
||||
```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 Header Changes
|
||||
|
||||
In v3.2.1, the `X-Forwarded-Prefix` header is now handled like other `X-Forwarded-*` headers - Traefik removes it when sent from untrusted sources.
|
||||
|
||||
This change improves security by preventing header spoofing from untrusted clients. Refer to the [Forwarded headers documentation](../routing/entrypoints.md#forwarded-headers) for configuration details.
|
||||
|
||||
---
|
||||
|
||||
## v3.2.2
|
||||
|
||||
### Swarm Provider Label Updates
|
||||
|
||||
In v3.2.2, Swarm-specific labels have been deprecated and will be removed in a future version.
|
||||
|
||||
**Migration Required:**
|
||||
|
||||
| Deprecated Label | New Label |
|
||||
|------------------|-----------|
|
||||
| `traefik.docker.network` | `traefik.swarm.network` |
|
||||
| `traefik.docker.lbswarm` | `traefik.swarm.lbswarm` |
|
||||
|
||||
---
|
||||
|
||||
## v3.2 to v3.3
|
||||
|
||||
### ACME DNS Certificate Resolver
|
||||
|
||||
In v3.3, DNS challenge configuration options have been reorganized for better clarity.
|
||||
|
||||
**Migration Required:**
|
||||
|
||||
| Deprecated Option | New Option |
|
||||
|-------------------|------------|
|
||||
| `acme.dnsChallenge.delaybeforecheck` | `acme.dnsChallenge.propagation.delayBeforeChecks` |
|
||||
| `acme.dnsChallenge.disablepropagationcheck` | `acme.dnsChallenge.propagation.disableChecks` |
|
||||
|
||||
### Tracing Global Attributes
|
||||
|
||||
In v3.3, the tracing configuration has been clarified to better reflect its purpose.
|
||||
|
||||
**Migration Required:**
|
||||
|
||||
- **Old:** `tracing.globalAttributes`
|
||||
- **New:** `tracing.resourceAttributes`
|
||||
|
||||
The old option name was misleading as it specifically adds resource attributes for the collector, not global span attributes.
|
||||
|
||||
---
|
||||
|
||||
## v3.3.4
|
||||
|
||||
### OpenTelemetry Request Duration Metric
|
||||
|
||||
In v3.3.4, the OpenTelemetry Request Duration metric unit has been standardized to match other providers and naming conventions.
|
||||
|
||||
**Change Details:**
|
||||
|
||||
- **Metric:** `traefik_(entrypoint|router|service)_request_duration_seconds`
|
||||
- **Old Unit:** Milliseconds
|
||||
- **New Unit:** Seconds
|
||||
|
||||
This change ensures consistency across all metrics providers and follows standard naming conventions.
|
||||
|
||||
---
|
||||
|
||||
## v3.3.5
|
||||
|
||||
### Compress Middleware Default Encodings
|
||||
|
||||
In v3.3.5, the default compression algorithms have been reordered to favor gzip compression.
|
||||
|
||||
**New Default:** `gzip, br, zstd`
|
||||
|
||||
This change affects requests that either:
|
||||
|
||||
- Don't specify preferred algorithms in the `Accept-Encoding` header
|
||||
- Have no order preference in their `Accept-Encoding` header
|
||||
|
||||
The reordering helps ensure better compatibility with older clients that may not support newer compression algorithms.
|
||||
|
||||
---
|
||||
|
||||
## v3.3.6
|
||||
|
||||
### Request Path Sanitization
|
||||
|
||||
Starting with v3.3.6, incoming request paths are now automatically cleaned before processing for security and consistency.
|
||||
|
||||
**What's Changed:**
|
||||
|
||||
The following path segments are now interpreted and collapsed:
|
||||
|
||||
- `/../` (parent directory references)
|
||||
- `/./` (current directory references)
|
||||
- Duplicate slash segments (`//`)
|
||||
|
||||
**Disabling Sanitization:**
|
||||
|
||||
```yaml
|
||||
# EntryPoint HTTP configuration
|
||||
entryPoints:
|
||||
web:
|
||||
address: ":80"
|
||||
http:
|
||||
sanitizePath: false # Not recommended
|
||||
```
|
||||
|
||||
!!! danger "Security Warning"
|
||||
Setting `sanitizePath: false` is not safe. This option should only be used with legacy clients that don't properly URL-encode data. Always ensure requests are properly URL-encoded instead of disabling this security feature.
|
||||
|
||||
**Example Risk:**
|
||||
Base64 data containing "/" characters can lead to unsafe routing when path sanitization is disabled and the data isn't URL-encoded.
|
||||
|
||||
---
|
||||
|
||||
## v3.3 to v3.4
|
||||
|
||||
### Kubernetes CRD Provider
|
||||
|
||||
#### Load-Balancing Strategy Updates
|
||||
|
||||
Starting with v3.4, HTTP service definitions now support additional load-balancing strategies for better traffic distribution.
|
||||
|
||||
**Apply Updated CRDs:**
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml
|
||||
```
|
||||
|
||||
**New Strategy Values:**
|
||||
|
||||
- `wrr` (Weighted Round Robin)
|
||||
- `p2c` (Power of Two Choices)
|
||||
|
||||
!!! warning "Deprecation"
|
||||
The `RoundRobin` strategy is deprecated but still supported (equivalent to `wrr`). It will be removed in the next major release.
|
||||
|
||||
Refer to the [HTTP Services Load Balancing documentation](../../routing/services/#load-balancing-strategy) for detailed information.
|
||||
|
||||
#### ServersTransport CA Certificate Configuration
|
||||
|
||||
A new `rootCAs` option has been added to the `ServersTransport` and `ServersTransportTCP` CRDs. It supports both ConfigMaps and Secrets for CA certificates and replaces the `rootCAsSecrets` option.
|
||||
|
||||
**Apply Updates:**
|
||||
|
||||
```shell
|
||||
# Update CRDs
|
||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml
|
||||
|
||||
# Update RBACs
|
||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml
|
||||
```
|
||||
|
||||
**New Configuration Format:**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
!!! warning "Deprecation"
|
||||
The `rootCAsSecrets` option (Secrets only) is still supported but deprecated. It will be removed in the next major release.
|
||||
|
||||
### Rule Syntax Configuration
|
||||
|
||||
In v3.4, rule syntax configuration options will be removed in the next major version.
|
||||
|
||||
**Deprecated Options:**
|
||||
|
||||
- `core.defaultRuleSyntax` (static configuration)
|
||||
- `ruleSyntax` (router option)
|
||||
|
||||
These options were transitional helpers for migrating from v2 to v3 syntax. Please ensure all router rules use v3 syntax before the next major release.
|
||||
|
||||
---
|
||||
|
||||
## v3.4.1
|
||||
|
||||
### Request Path Normalization
|
||||
|
||||
Starting with v3.4.1, request paths are now normalized according to RFC 3986 standards for better consistency and security.
|
||||
|
||||
**Normalization Process:**
|
||||
|
||||
1. **Unreserved Character Decoding:** Characters like `%2E` (.) are decoded to their literal form
|
||||
2. **Case Normalization:** Percent-encoded characters are uppercased (`%2e` becomes `%2E`)
|
||||
|
||||
This follows [RFC 3986 percent-encoding normalization](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2) and [case normalization](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1) standards.
|
||||
|
||||
**Processing Order:**
|
||||
|
||||
1. Path normalization (cannot be disabled)
|
||||
2. Path sanitization (if enabled)
|
||||
|
||||
### Reserved Character Handling in Routing
|
||||
|
||||
Starting with v3.4.1, reserved characters (per [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2)) remain encoded during router rule matching to prevent routing ambiguity.
|
||||
|
||||
**Why This Matters:**
|
||||
Reserved characters change the meaning of request paths when decoded. Keeping them encoded during routing prevents security vulnerabilities and ensures predictable routing behavior.
|
||||
|
||||
### Request Path Matching Examples
|
||||
|
||||
The following table illustrates how path matching behavior has changed:
|
||||
|
||||
| Request Path | Router Rule | Traefik v3.4.0 | Traefik v3.4.1 | Explanation |
|
||||
|-------------------|------------------------|----------------|----------------|-------------|
|
||||
| `/foo%2Fbar` | ```PathPrefix(`/foo/bar`)``` | Match | No match | `%2F` (/) stays encoded, preventing false matches |
|
||||
| `/foo/../bar` | ```PathPrefix(`/foo`)``` | No match | No match | Path traversal is sanitized away |
|
||||
| `/foo/../bar` | ```PathPrefix(`/bar`)``` | Match | Match | Resolves to `/bar` after sanitization |
|
||||
| `/foo/%2E%2E/bar` | ```PathPrefix(`/foo`)``` | Match | No match | Encoded dots normalized then sanitized |
|
||||
| `/foo/%2E%2E/bar` | ```PathPrefix(`/bar`)``` | No match | Match | Resolves to `/bar` after normalization + sanitization |
|
||||
@ -1,77 +0,0 @@
|
||||
---
|
||||
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 }
|
||||
|
||||
With Traefik v3, we are introducing a streamlined transition process from v2. Minimal breaking changes have been made to specific options in the [static configuration](./v2-to-v3-details.md#static-configuration-changes "Link to static configuration changes"), and we are ensuring backward compatibility with v2 syntax in the [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes"). This will offer a gradual path for adopting the v3 syntax, allowing users to progressively migrate their Kubernetes ingress resources, Docker labels, etc., to the new format.
|
||||
|
||||
Here are the steps to progressively migrate from Traefik v2 to v3:
|
||||
|
||||
1. [Prepare configurations and test v3](#step-1-prepare-configurations-and-test-v3)
|
||||
1. [Migrate production instances to Traefik v3](#step-2-migrate-production-instances-to-traefik-v3)
|
||||
1. [Progressively migrate dynamic configuration](#step-3-progressively-migrate-dynamic-configuration)
|
||||
|
||||
## Step 1: Prepare Configurations and Test v3
|
||||
|
||||
Check the changes in [static configurations](./v2-to-v3-details.md#static-configuration-changes "Link to static configuration changes") and [operations](./v2-to-v3-details.md#operations-changes "Link to operations changes") brought by Traefik v3.
|
||||
Modify your configurations accordingly.
|
||||
|
||||
Then, add the following snippet to the static configuration:
|
||||
|
||||
```yaml
|
||||
# static configuration
|
||||
core:
|
||||
defaultRuleSyntax: v2
|
||||
```
|
||||
|
||||
This snippet in the static configuration makes the [v2 format](../migration/v2-to-v3-details.md#configure-the-default-syntax-in-static-configuration "Link to configure default syntax in static config") the default rule matchers syntax.
|
||||
|
||||
Start Traefik v3 with this new configuration to test it.
|
||||
|
||||
If you don’t get any error logs while testing, you are good to go!
|
||||
Otherwise, follow the remaining migration options highlighted in the logs.
|
||||
|
||||
Once your Traefik test instances are starting and routing to your applications, proceed to the next step.
|
||||
|
||||
## Step 2: Migrate Production Instances to Traefik v3
|
||||
|
||||
We strongly advise you to follow a progressive migration strategy ([Kubernetes rolling update mechanism](https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/ "Link to the Kubernetes rolling update documentation"), for example) to migrate your production instances to v3.
|
||||
|
||||
!!! Warning
|
||||
Ensure you have a [real-time monitoring solution](https://traefik.io/blog/capture-traefik-metrics-for-apps-on-kubernetes-with-prometheus/ "Link to the blog on capturing Traefik metrics with Prometheus") for your ingress traffic to detect issues instantly.
|
||||
|
||||
During the progressive migration, monitor your ingress traffic for any errors. Be prepared to rollback to a working state in case of any issues.
|
||||
|
||||
If you encounter any issues, leverage debug and access logs provided by Traefik to understand what went wrong and how to fix it.
|
||||
|
||||
Once every Traefik instance is updated, you will be on Traefik v3!
|
||||
|
||||
## Step 3: Progressively Migrate Dynamic Configuration
|
||||
|
||||
!!! info
|
||||
This step can be done later in the process, as Traefik v3 is compatible with the v2 format for [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes").
|
||||
Enable Traefik logs to get some help if any deprecated option is in use.
|
||||
|
||||
Check the changes in [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes").
|
||||
|
||||
Then, progressively [switch each router to the v3 syntax](./v2-to-v3-details.md#configure-the-syntax-per-router "Link to configuring the syntax per router").
|
||||
|
||||
Test and update each Ingress resource and ensure that ingress traffic is not impacted.
|
||||
|
||||
Once a v3 Ingress resource migration is validated, deploy the resource and delete the v2 Ingress resource.
|
||||
Repeat it until all Ingress resources are migrated.
|
||||
|
||||
Now, remove the following snippet added to the static configuration in Step 1:
|
||||
|
||||
```yaml
|
||||
# static configuration
|
||||
core:
|
||||
defaultRuleSyntax: v2
|
||||
```
|
||||
|
||||
You are now fully migrated to Traefik v3 🎉
|
||||
@ -117,7 +117,7 @@ It only matches the request client IP and does not use the `X-Forwarded-For` hea
|
||||
RuleSyntax option is deprecated and will be removed in the next major version.
|
||||
Please do not use this field and rewrite the router rules to use the v3 syntax.
|
||||
|
||||
In Traefik v3 a new rule syntax has been introduced ([migration guide](../../../../migration/v3.md)). the `ruleSyntax` option allows to configure the rule syntax to be used for parsing the rule on a per-router basis. This allows to have heterogeneous router configurations and ease migration.
|
||||
In Traefik v3 a new rule syntax has been introduced ([migration guide](../../../../migrate/v3.md)). the `ruleSyntax` option allows to configure the rule syntax to be used for parsing the rule on a per-router basis. This allows to have heterogeneous router configurations and ease migration.
|
||||
|
||||
The default value of the `ruleSyntax` option is inherited from the `defaultRuleSyntax` option in the install configuration (formerly known as static configuration). By default, the `defaultRuleSyntax` static option is v3, meaning that the default rule syntax is also v3
|
||||
|
||||
|
||||
@ -527,7 +527,7 @@ A value of `0` for the priority is ignored: `priority = 0` means that the defaul
|
||||
|
||||
_Optional, Default=""_
|
||||
|
||||
In Traefik v3 a new rule syntax has been introduced ([migration guide](../../migration/v2-to-v3.md#router-rule-matchers)).
|
||||
In Traefik v3 a new rule syntax has been introduced ([migration guide](../../migrate/v2-to-v3.md#router-rule-matchers)).
|
||||
`ruleSyntax` option allows to configure the rule syntax to be used for parsing the rule on a per-router basis.
|
||||
This allows to have heterogeneous router configurations and ease migration.
|
||||
|
||||
@ -1351,7 +1351,7 @@ A value of `0` for the priority is ignored: `priority = 0` means that the defaul
|
||||
|
||||
_Optional, Default=""_
|
||||
|
||||
In Traefik v3 a new rule syntax has been introduced ([migration guide](../../migration/v2-to-v3.md#router-rule-matchers)).
|
||||
In Traefik v3 a new rule syntax has been introduced ([migration guide](../../migrate/v2-to-v3.md#router-rule-matchers)).
|
||||
`ruleSyntax` option allows to configure the rule syntax to be used for parsing the rule on a per-router basis.
|
||||
This allows to have heterogeneous router configurations and ease migration.
|
||||
|
||||
|
||||
@ -91,6 +91,13 @@ nav:
|
||||
- 'Metrics': 'observe/metrics.md'
|
||||
- 'Tracing': 'observe/tracing.md'
|
||||
- 'Extend': 'extend/extend-traefik.md'
|
||||
- 'Migrate':
|
||||
- 'Traefik v3': 'migrate/v3.md'
|
||||
- 'Traefik v2 to v3':
|
||||
- 'Migration guide': 'migrate/v2-to-v3.md'
|
||||
- 'Configuration changes for v3': 'migrate/v2-to-v3-details.md'
|
||||
- 'Traefik v2': 'migrate/v2.md'
|
||||
- 'Traefik v1 to v2': 'migrate/v1-to-v2.md'
|
||||
- 'Configuration Discovery':
|
||||
- 'Overview': 'providers/overview.md'
|
||||
- 'Docker': 'providers/docker.md'
|
||||
@ -199,13 +206,6 @@ nav:
|
||||
- 'TLS Challenge': 'user-guides/docker-compose/acme-tls/index.md'
|
||||
- 'HTTP Challenge': 'user-guides/docker-compose/acme-http/index.md'
|
||||
- 'DNS Challenge': 'user-guides/docker-compose/acme-dns/index.md'
|
||||
- 'Migration':
|
||||
- 'Traefik v3 minor migrations': 'migration/v3.md'
|
||||
- 'Traefik v2 to v3':
|
||||
- 'Migration guide': 'migration/v2-to-v3.md'
|
||||
- 'Configuration changes for v3': 'migration/v2-to-v3-details.md'
|
||||
- 'Traefik v2 minor migrations': 'migration/v2.md'
|
||||
- 'Traefik v1 to v2': 'migration/v1-to-v2.md'
|
||||
- 'Contributing':
|
||||
- 'Thank You!': 'contributing/thank-you.md'
|
||||
- 'Submitting Issues': 'contributing/submitting-issues.md'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user