Migration Guide: From v2 to v3

How to Migrate from Traefik v2 to Traefik v3.

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, and we are ensuring backward compatibility with v2 syntax in the dynamic configuration. 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
2. Migrate production instances to Traefik v3
3. Progressively migrate dynamic configuration

Step 1: Prepare Configurations and Test v3

Check the changes in static configurations and operations brought by Traefik v3. Modify your configurations accordingly.

Then, add the following snippet to the static configuration:

# static configuration
core:
  defaultRuleSyntax: v2

This snippet in the static configuration makes the v2 format 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, for example) to migrate your production instances to v3.

Warning

Ensure you have a real-time monitoring solution 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. Enable Traefik logs to get some help if any deprecated option is in use.

Check the changes in dynamic configuration.

Then, progressively switch each router to the v3 syntax.

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:

# static configuration
core:
  defaultRuleSyntax: v2

You are now fully migrated to Traefik v3 🎉