From ba0f7364f192948f65e430f6b846fbb67a60aaeb Mon Sep 17 00:00:00 2001 From: Sheddy Date: Thu, 24 Jul 2025 17:06:04 +0100 Subject: [PATCH] Update Migration Docs --- docs/content/deprecation/releases.md | 2 +- .../{migration => migrate}/v1-to-v2.md | 0 .../v2-to-v3-details.md | 0 docs/content/migrate/v2-to-v3.md | 161 +++++++ docs/content/{migration => migrate}/v2.md | 0 docs/content/migrate/v3.md | 422 ++++++++++++++++++ docs/content/migration/v2-to-v3.md | 77 ---- .../http/router/rules-and-priority.md | 2 +- docs/content/routing/routers/index.md | 4 +- docs/mkdocs.yml | 14 +- 10 files changed, 594 insertions(+), 88 deletions(-) rename docs/content/{migration => migrate}/v1-to-v2.md (100%) rename docs/content/{migration => migrate}/v2-to-v3-details.md (100%) create mode 100644 docs/content/migrate/v2-to-v3.md rename docs/content/{migration => migrate}/v2.md (100%) create mode 100644 docs/content/migrate/v3.md delete mode 100644 docs/content/migration/v2-to-v3.md diff --git a/docs/content/deprecation/releases.md b/docs/content/deprecation/releases.md index 0c25265bd..d8f4d8d3c 100644 --- a/docs/content/deprecation/releases.md +++ b/docs/content/deprecation/releases.md @@ -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." diff --git a/docs/content/migration/v1-to-v2.md b/docs/content/migrate/v1-to-v2.md similarity index 100% rename from docs/content/migration/v1-to-v2.md rename to docs/content/migrate/v1-to-v2.md diff --git a/docs/content/migration/v2-to-v3-details.md b/docs/content/migrate/v2-to-v3-details.md similarity index 100% rename from docs/content/migration/v2-to-v3-details.md rename to docs/content/migrate/v2-to-v3-details.md diff --git a/docs/content/migrate/v2-to-v3.md b/docs/content/migrate/v2-to-v3.md new file mode 100644 index 000000000..00fcfe8c2 --- /dev/null +++ b/docs/content/migrate/v2-to-v3.md @@ -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!} diff --git a/docs/content/migration/v2.md b/docs/content/migrate/v2.md similarity index 100% rename from docs/content/migration/v2.md rename to docs/content/migrate/v2.md diff --git a/docs/content/migrate/v3.md b/docs/content/migrate/v3.md new file mode 100644 index 000000000..bfef9d330 --- /dev/null +++ b/docs/content/migrate/v3.md @@ -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 | diff --git a/docs/content/migration/v2-to-v3.md b/docs/content/migration/v2-to-v3.md deleted file mode 100644 index 2b88ce294..000000000 --- a/docs/content/migration/v2-to-v3.md +++ /dev/null @@ -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 🎉 diff --git a/docs/content/reference/routing-configuration/http/router/rules-and-priority.md b/docs/content/reference/routing-configuration/http/router/rules-and-priority.md index ad095da07..4677254bf 100644 --- a/docs/content/reference/routing-configuration/http/router/rules-and-priority.md +++ b/docs/content/reference/routing-configuration/http/router/rules-and-priority.md @@ -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 diff --git a/docs/content/routing/routers/index.md b/docs/content/routing/routers/index.md index ef61d56b1..06cd3f05b 100644 --- a/docs/content/routing/routers/index.md +++ b/docs/content/routing/routers/index.md @@ -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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 5a808b382..1ce56c515 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -87,6 +87,13 @@ nav: - 'Logs & Access Logs': 'observe/logs-and-access-logs.md' - 'Metrics': 'observe/metrics.md' - 'Tracing': 'observe/tracing.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' @@ -192,13 +199,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'