Traefik Proxy v3.3 - Nectaire of the Gods
Traefik v3.3, codenamed saint-nectaire (one of the best cheeses you can find in France, made in the volcanic area Auvergne), is now generally available after two months of dedicated development and two release candidates. This release focuses on two main tracks: observability and documentation.
Observability has become essential for platform engineers to quickly detect outages and recover services in today's complex, cloud-native environments. Traefik Proxy v3.3 once again pushes the boundaries by adding state-of-the-art features with a deeper OpenTelemetry integration as well as a much more granular observability configuration. This makes Traefik Proxy one of the most flexible and powerful telemetry data providers, giving you instant and complete knowledge of all your ingress traffic.
Additionally, documentation is one of the most important (and underrated) parts of an open-source project. Itβs the main entry point π to your product. It should onboard newcomers to quickly learn and test while providing a clear and complete description of every option and use case to more advanced users.Β
Back in 2024, we started a major project to reorganize and revamp the Traefik Proxy documentation. This is quite a big journey, and we are happy to hit the first milestone today with a brand-new reference documentation.
Ready to dive into v3.3? Letβs start with OpenTelemetry.
OpenTelemetry Support for Logs and Access Logs
Since its very first release, Traefik Proxy made observability one of its core features, supporting many vendors for metrics and tracing analysis. Building upon the foundation laid in Traefik Proxy v3.0 with OpenTelemetry integration, v3.3 goes even further by adding support for logs and access logs.
This feature is tagged βexperimental,β as the official underlying library is still being finalized.
To unlock it, simply add this to your configuration:
experimental:
otlpLogs: true
Then letβs enable logs and access logs globally to the OpenTelemetry configuration:
metrics:
otlp: {}
tracing:
otlp: {}
log:
otlp: {}
accesslog:
otlp: {}
The OpenTelemetry logger exporter will send logs to the collector using HTTPS by default to https://localhost:4318/v1/logs
. You can customize the exporter by referring to the logs and access logs documentation.
Flexible and Granular Observability
Until today, you could enable observability features globally on Traefik Proxy, which means, either you had metrics (or tracing) for all your routes or none. However, there are many use cases where you donβt want to have tracing for all your applications. Or you might just need to enable these features temporarily.Β
Thatβs why we have been working on a new mechanism to have more granular control over observability. In v3.3, you now have a way to define default behaviors and you can enable or disable tracing, metrics or access logs per router.
The default router observability configuration is inherited from the attached entryPoints
and a router defining its own observability configuration will override those options.
Letβs take an example where you want to enable tracing by default for an entryPoint
:
You still need to configure the tracing globally:
tracing:
otlp: {}
Tracing is enabled by default on entryPoints
, so you shouldnβt need to change anything in your configuration:
entryPoints:
foo:
address: ':80'
This is equivalent to:
entryPoints:
foo:
address: ':80'
observability:
tracing: true
Every router attached to this entryPoint
will have tracing enabled. If you want to disable a specific router
, thatβs pretty simple:
## Dynamic file configuration
http:
routers:
my-router:
rule: "Path(`/foo`)"
service: service-foo
observability:
tracing: false
Or if you use Kubernetes Ingresses, just add this annotation to the corresponding ingress:
traefik.ingress.kubernetes.io/router.observability.tracing: false
Letβs take another example where you want to disable tracing by default for an entryPoint
:
entryPoints:
foo:
address: ':80'
observability:
tracing: false
And then if you want to enable tracing temporarily while troubleshooting a service:
## Dynamic file configuration
http:
routers:
my-router:
rule: "Path(`/foo`)"
service: service-foo
observability:
tracing: true
Or within an ingress:
traefik.ingress.kubernetes.io/router.observability.tracing: true
This simple and powerful granular control applies to tracing, metrics, and access logs.
New Reference Documentation
As mentioned before, great documentation is key for open source projects. We've been working hard to improve Traefik Proxy's docs, and we have defined new guidelines as follows:
- Organize the documentation for 3 personas: beginners, advanced ops, and/or advanced developers
- Describe high level use cases without listing every option possible in the first sections of the documentation (Getting Started, Setup, Expose, Observe, Migrate, etc)
- Move all option descriptions to a well organized Reference section
Today we're excited to launch our brand new reference documentation as a first milestone of this global revamp.
The reference documentation used to have this structure:
βββ Static Configuration
β βββ Overview
β βββ CLI
β βββ Environment Variables
β βββ File
βββ Dynamic Configuration
βββ Consul Catalog
βββ β¦
We reorganized this section to provide a much more comprehensive description of all options available:
βββ Install Configuration
β βββ Boot Environment
β βββ Configuration Discovery
β β βββ Overview
β β βββ Kubernetes
β β β βββ Kubernetes Gateway API
β β β βββ Kubernetes CRD
β β β βββ Kubernetes Ingress
β β βββ Docker
β β βββ Swarm
β β βββ Hashicorp
β β β βββ Consul Catalog
β β β βββ Consul
β β β βββ Nomad
β β βββ KV Stores
β β β βββ Consul
β β β βββ ETCD
β β β βββ Redis
β β β βββ ZooKeeper
β β βββ Others
β β βββ ECS
β β βββ File
β β βββ HTTP
β βββ Entrypoints
β βββ API & Dashboard
β βββ Observability
β β βββ Healthcheck
β β βββ Logs and Accesslogs
β β βββ Metrics
β β βββ Tracing
β βββ TLS
β βββ Certificate Resolvers
β β βββ Overview
β β βββ ACME
β β βββ Tailscale
β βββ SPIFFE
βββ Dynamic Configuration
βββ Consul Catalog
βββ β¦
We hope this will help beginners and advanced users to quickly find and learn everything they want to about Traefik Proxy. The next step? Revamp high-level sections!
Other Improvements
On top of those great new features, Traefik Proxy v3.3 brings options to control ACME (Letβs Encrypt) propagation checks (#11241 by ldez). We also added configuration dump support from the API endpoint to make troubleshooting sessions easier.
Skirtan1 made the IngressRoute kind optional (#11177) and BZValoche added Kubernetes serving endpoint status support to detect and mark servers as βfencedβ when stickiness is enabled. Regarding sticky cookies, you can now make the path configurable (#11166 by IIpragmaII).
Host headers in the HTTP provider can now be set (#11237 by nikonhub), and you can preserve the Location header in the ForwardAuth middleware (#11318 by Nelwhix).
Another great addition brought by michelheusschen allows you to only calculate basic auth hashes once for concurrent requests (#11143).
You can now send the request body to the authorization server with the ForwardAuth middleware (#11097 by kyo-ke).
Additionally, it is now possible to make Traefik abort the startup in case a plugin load fails (#11228 by bmagic) and finally, the API & Dashboard base path can now be configured.
Moving Forward
Traefik Proxy v3.3 is a significant release that focuses on observability and documentation. With the addition of logs and access logs to its existing support for metrics and traces, Traefik Proxy now provides even deeper insights into your ingress traffic. Additionally, the new granular observability configuration allows you to enable or disable tracing, metrics, or access logs on a per-router basis, giving you more control and flexibility over the data you collect. And the improvements to the documentation, including the new reference documentation, make it easier for users to learn about and use Traefik Proxy.
Overall, v3.3 is a powerful release that makes Traefik Proxy an even more valuable tool for platform engineers and developers.
We are immensely thankful to the contributors who are shaping this great project. Join the vibrant Traefik community, share your feedback, and help us shape the future of cloud-native networking.
Useful Links
- Traefik 3.3 on GitHub & on DockerHub
- Traefik Documentation, Website, & GitHub
- Our Community Forum