Traefik 3.0 GA Has Landed: Here's How to Migrate

This year will mark the 9th anniversary of Traefik. Back in 2015, while I was writing the first lines of code for a cloud native reverse proxy, I couldn’t imagine how big this would go. From a side project, Traefik became one of the most deployed modern gateways on earth, with more than 3 billion downloads and 750+ contributors. It is ranked in the Top 15 on DockerHub and has 47,000 GitHub stars. Insane.

Traefik 1.0 was released in 2016. Three years later, Traefik 2.0 was born. Today, after 5 years of development, the wait is finally over! We are proud to announce that Traefik 3.0 is generally available 🎉

This major release is a huge step forward in the cloud native world, adding support for the latest technologies like WASM, OpenTelemetry, Kubernetes Gateway API, and SPIFFE.

After many years of effort, the changelog is pretty wild, with more than 200 pull requests merged, each coming with new features. The list of new possibilities is so big that we want to provide a series of blog posts, each deep diving into one feature.

Today’s article will focus on the beginning, the elephant in the room 🥁🥁🥁: the migration.

Migration Under Control

A new major version is always something eagerly awaited: new design, new features, better user experience … But the counterpart is usually the migration aspect. A major version often means breaking changes, but that shouldn’t imply a painful migration experience, and with Traefik v3 it doesn’t.

With Traefik v3, we are introducing a streamlined transition process from v2. As a reminder, Traefik has 2 kinds of configurations:

the static configuration which is loaded when Traefik starts up and manages global options
the dynamic configuration can be updated while Traefik is running and contains all the routing information

Minimal breaking changes have been made on specific options on the static configuration, and we are ensuring backward compatibility with v2 syntax on 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.

Let’s deep dive into the migration path with a typical use case: you have to migrate 100 Traefik instances from v2.11 to v3.0 in Kubernetes.

Step 1: Prepare and Test

The first thing to do is to identify how your static configuration is impacted by the changes made in v3. The breaking changes are minimal and target very specific options, in 90% of use cases, this process should take a couple minutes only. As an example, Docker and Swarm are now 2 providers, HTTP/3 is no longer an experimental option, Rancher v1 has been dropped as the project is no longer being actively maintained, etc. Please refer to the static configuration section of the migration documentation, as well as the operations section, to get the full list and prepare your new v3 static configuration.

Add the following snippet to your static configuration, this will use by default the v2 syntax for your routing rules:

# static configuration
core:
  defaultRuleSyntax: v2

When you are ready to test it, start Traefik v3 with this new configuration. If you don’t get any error log, you are good to go! Otherwise, no problem, the remaining migration options are highlighted in the logs, you can simply apply them.

Once your Traefik test instances are starting and routing to your applications, you can move to the next step.

Step 2: Rolling Update

Now that you have tested your updated static configuration, it is time to progressively migrate your production instances to Traefik v3. Use the Kubernetes rolling update mechanism to incrementally replace the current Pods with new ones.

⚠️ Before triggering any change on your production, ensure you to have a working real time monitoring solution on your ingress traffic that will allow you to instantly detect any issue. Traefik provides support for many observability solutions.

While the rolling update is in progress, constantly monitor your ingress traffic looking for unexpected (and unusual) errors, and be prepared to rollback to a working state. Then, leverage debug and access logs provided by Traefik to understand and fix the issue before upgrading again. In case you're not sure, jump onto the community forum.

Once every pod is updated, congratulations, you are now on Traefik v3!

You can move to the last step.

Step 3: Progressive Ingresses Update

Now that you run Traefik v3, start migrating your ingress resources to the new format.

📍 Keep in mind that this step can be done later, as Traefik v3 is compatible with the v2 format for dynamic configuration. But of course, you can start using new features right away in new ingresses, and migrate older ingresses later.

The dynamic configuration in v3 has undergone a few changes. For example, the Router Rule Matchers have an updated syntax, the Kubernetes Ingress API Group has been changed, and the TCP LoadBalancer terminationDelay option has been removed. The full list can be found in the dynamic configuration section of the migration documentation.

Progressively, switch each router to the v3 syntax, test & update each ingress resource and check that the ingress traffic is not impacted. Once a v3 ingress resource migration is validated, you can delete the v2 ingress resource and deploy the v3 version. Repeat those steps for every ingress resource.

At the end of the process, you can safely remove the snippet added at step 1:

# static configuration
core:
  defaultRuleSyntax: v2

Et voilà!

You are now fully migrated to Traefik v3 🎉! And you did this progressively, keeping control during the whole process, with the option to rollback any change at any time.

This example with Kubernetes can be transposed to any orchestrator or environment, the process stays the same.

In the coming weeks, we will continue this series, and release deep dive articles on WASM support (and Coraza Web Application Firewall plugin), OpenTelemetry, SPIFFE/Tailscale/HTTP/3, and Kubernetes Gateway API.

Ultimately, I'd like to express immense gratitude to all contributors. Your support is incredibly valuable.

To learn more about v3, watch the recording of our recent Traefik v3 Online Meetup.

See you on GitHub!