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.