Upgrading Traefik within the 3.7 series is a short operation, provided you prepare it: read the notes of each intermediate version, change the pinned image, check the real response of the service and keep a rollback definition ready. Patch releases of the same series do not change the configuration model, but they fix vulnerabilities and sometimes alter one precise behavior. This lesson gives the method, not a recipe to copy.
What you will learn
The lesson follows the order of a change window: gather information, change, check, then know how to undo.
- Read release notes for a series of patch releases.
- Pin an image by tag and digest.
- Prepare a rollback before touching the deployment.
- Check the active version and the real response of the service.
- Tell a corrective upgrade apart from a major migration.
Prerequisites
This lesson assumes you already publish a service with Traefik and know how to restart a container.
- Traefik's model and the difference between static and dynamic configuration: Traefik.
- Publishing containers with Compose: Traefik with Docker.
- Diagnosing an entry point, useful if the upgrade breaks a route: Troubleshoot a Traefik entry point.
Why upgrade a proxy with a method?
A reverse proxy is the point through which all the traffic passes: a failed upgrade shows on every published service. It is also the component exposed to the Internet, so the one whose vulnerabilities are fixed the fastest. Two risks therefore pull in opposite directions: not upgrading exposes you to a known vulnerability, upgrading without precautions exposes you to an outage.
The method consists in making the change small, readable and reversible. Small, because you only change the image version. Readable, because the new version is written in plain sight in the deployment file. Reversible, because the previous version stays defined and you know how to put it back.
How do you read the release notes?
Read the notes of every version between yours and the target, not only the last one. A change of behavior can appear in an intermediate version and never be mentioned again afterwards. From 3.7.6 to 3.7.15, that means nine versions to go through on the releases page of the traefik/traefik repository.
A few changes in this series show what to look for.
- 3.7.9 and 3.7.15 change how
CONNECTrequests are handled: they are rejected or deferred. A client that goes through aCONNECTtunnel must be tested. - 3.7.12 adds the file name to the errors of the file provider, which makes it easier to diagnose a badly written route.
- 3.7.13 and 3.7.14 change the behavior of the ACME DNS challenge and of the
legolibrary that carries it: check them if you use DNS-01. - Several versions point to the migration guide of the 3 series: read the section for the version concerned before going on.
How do you pin the image?
Write the version and the digest in the deployment file, never a floating tag. A tag such as v3.7 designates an image that changes as releases are published: the same file no longer produces the same proxy from one day to the next. The sha256:… digest, on the contrary, designates a single, immutable image.
services: traefik: image: traefik:v3.7.15@sha256:0f6150202bc1fed72a7bd2107460eaa510e5b8a905f3fdb5b84f2c8619c33368This file says exactly which version runs and lets any colleague replay the same operation. The digest of a version is read on the image page in the registry; copy it from that source, not from a chat message.
How do you prepare the rollback?
The rollback is prepared before the upgrade: all it takes is keeping the definition of the previous version. In a deployment repository, that is a previous commit. On a host without a repository, it is a copy of the deployment file next to the original, with the image of the version that worked.
Three points make this rollback reliable.
- Keep the complete old reference, tag and digest, not just a version number.
- Check that the old version can read the current configuration. A rollback to a version that does not understand a recent field fails.
- Rehearse the rollback once, outside an emergency: a rollback that has never been played is not a procedure, it is a hypothesis.
How do you check that the upgrade succeeded?
An upgrade has succeeded when the active version is the right one and the service answers as before, not when the container has merely started. Two checks complement each other.
The first reads the version actually active, with the traefik version command run in the container or through the read-only dashboard. The second sends a real request with curl to the published name and checks the code, the certificate and the content of the response.
docker compose exec traefik traefik versioncurl -sS -o /dev/null -w '%{http_code}\n' https://app.example.test/If the version is the right one but the response has changed, the upgrade is not the first suspect: reread the access log, then the notes of the faulty version.
What about moving from v2 to v3?
A major migration is a different exercise: the routing rule model changes, and the official migration guide provides three steps. They are: prepare the existing configuration while keeping the v2 rule syntax, migrate production progressively with a rollback plan, then migrate the routing configuration progressively.
This lesson stays within the 3 series: the upgrade from 3.7.6 to 3.7.15 does not involve these breaking changes. The migration guide serves you as context for a future major version, and its steps confirm the principle of this lesson: move in small steps, and keep the path back.
Hands-on: upgrade and prove the rollback
The lab starts from an entry point running Traefik 3.7.6 whose published service no longer answers. It asks you to read the situation, move to 3.7.15 with the pinned image, put the expected route back and keep a rollback definition. The check then runs that rollback, verifies that the old version serves the traffic, and restores the upgraded version.
Key points
An upgrade is judged on the response of the service, not on the container starting.
- Read the notes of all the intermediate versions.
- Pin the image by tag and digest, never by a floating tag.
- Prepare and rehearse the rollback before the upgrade.
- Check the active version then the real response of the service.
- A major v2 to v3 migration follows the official guide, in three progressive steps.
Knowledge check
Knowledge check
Check what you have learned with this interactive quiz
How it works
- The timer starts when you click Start
- Multiple choice, true/false and short answer questions
- You can move between questions
- Detailed results are shown at the end
Starts the quiz and the timer
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Cut over backends and measure a Traefik failure
A new full quiz with random questions
Work again only on the questions you missed