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

78 lines
4.3 KiB
Markdown
Raw Normal View History

2022-10-26 15:16:05 +00:00
---
title: "Traefik V3 Migration Documentation"
description: "Migrate from Traefik Proxy v2 to v3 and update all the necessary configurations to take advantage of all the improvements. Read the technical documentation."
---
# Migration Guide: From v2 to v3
How to Migrate from Traefik v2 to Traefik v3.
{: .subtitle }
2024-06-06 13:22:04 +00:00
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.
2022-10-26 15:16:05 +00:00
2024-06-06 13:22:04 +00:00
Here are the steps to progressively migrate from Traefik v2 to v3:
2022-10-26 15:16:05 +00:00
2024-06-06 13:22:04 +00:00
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)
2024-06-06 13:22:04 +00:00
## Step 1: Prepare Configurations and Test v3
2024-06-06 13:22:04 +00:00
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.
2024-06-06 13:22:04 +00:00
Then, add the following snippet to the static configuration:
2024-06-06 13:22:04 +00:00
```yaml
# static configuration
core:
defaultRuleSyntax: v2
2024-01-23 10:34:05 +00:00
```
2024-06-06 13:22:04 +00:00
This snippet in the static configuration makes the [v2 format](https://doc.traefik.io/traefik/v3.0/migration/v2-to-v3/?ref=traefik.io#configure-the-default-syntax-in-static-configuration "Link to configure default syntax in static config") the default rule matchers syntax.
2024-01-23 10:34:05 +00:00
2024-06-06 13:22:04 +00:00
Start Traefik v3 with this new configuration to test it.
2024-06-06 13:22:04 +00:00
If you dont get any error logs while testing, you are good to go!
Otherwise, follow the remaining migration options highlighted in the logs.
2022-12-19 09:42:05 +00:00
2024-06-06 13:22:04 +00:00
Once your Traefik test instances are starting and routing to your applications, proceed to the next step.
2022-12-19 10:52:05 +00:00
2024-06-06 13:22:04 +00:00
## Step 2: Migrate Production Instances to Traefik v3
2022-12-19 10:52:05 +00:00
2024-06-06 13:22:04 +00:00
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.
2022-12-19 13:32:04 +00:00
2024-06-06 13:22:04 +00:00
!!! 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.
2022-12-19 13:32:04 +00:00
2024-06-06 13:22:04 +00:00
During the progressive migration, monitor your ingress traffic for any errors. Be prepared to rollback to a working state in case of any issues.
2023-03-22 15:40:06 +00:00
2024-06-06 13:22:04 +00:00
If you encounter any issues, leverage debug and access logs provided by Traefik to understand what went wrong and how to fix it.
2023-03-22 15:40:06 +00:00
2024-06-06 13:22:04 +00:00
Once every Traefik instance is updated, you will be on Traefik v3!
2023-05-10 13:28:05 +00:00
2024-06-06 13:22:04 +00:00
## Step 3: Progressively Migrate Dynamic Configuration
2023-05-10 13:28:05 +00:00
2024-06-06 13:22:04 +00:00
!!! 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.
2023-05-10 13:28:05 +00:00
2024-06-06 13:22:04 +00:00
Check the changes in [dynamic configuration](./v2-to-v3-details.md#dynamic-configuration-changes "Link to dynamic configuration changes").
2024-06-06 13:22:04 +00:00
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").
2024-06-06 13:22:04 +00:00
Test and update each Ingress resource and ensure that ingress traffic is not impacted.
2024-06-06 13:22:04 +00:00
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.
2024-06-06 13:22:04 +00:00
Now, remove the following snippet added to the static configuration in Step 1:
2024-06-06 13:22:04 +00:00
```yaml
# static configuration
core:
defaultRuleSyntax: v2
```
2024-06-06 13:22:04 +00:00
You are now fully migrated to Traefik v3 🎉