Traefik Dynamic Config Reload Atomicity Limits

Answer

Traefik v3 does not provide a documented, stronger all-or-nothing reload guarantee than v2.x. Dynamic configuration changes are non-atomic regarding request routing: in-flight requests may continue to use the pre-reload configuration while new requests are routed according to updated rules. This overlap window is not bounded or observable via standard metrics and varies based on the provider (e.g., Kubernetes, Docker, File) and the internal reload loop. The --graceful flag coordinates the shutdown of the Traefik process (SIGTERM) and does not provide isolation or atomicity for dynamic configuration reloads.

Behavioral Explanation

The following behaviors are likely based on Traefik's architecture, though not explicitly guaranteed as a bounded window in the documentation:

• Incremental Application: Traefik merges provider updates into its current in-memory state. Routers, services, and middlewares may be updated independently rather than as a single atomic transaction.
• Request Persistence: Once a request is accepted and routed, it typically follows the routing logic active at the time of acceptance. A configuration change during the request's lifecycle does not forcibly reroute the existing connection.
• Provider Latency: The time between a configuration change (e.g., a Kubernetes Ingress update) and the actual routing change depends on the provider's event notification speed and Traefik's internal processing cycle.

Recommended Migration Approach

To preserve request consistency during a migration, design for a non-deterministic overlap rather than relying on reload atomicity:

1. Stage New Resources: Add new routers, services, and backends to the configuration without removing the old ones.
2. Verify Health: Use the Traefik API (/api/http/routers) or external health checks to confirm the new path is operational.
3. Controlled Traffic Shift: Shift traffic at a boundary outside the dynamic reload loop, such as via DNS, a global load balancer, or by updating the entrypoint rules.
4. Drain and Remove: Keep old backends active until in-flight requests have naturally drained. Only remove the old routing rules after monitoring confirms no traffic is hitting the legacy endpoints.

Verification Command

To observe the overlap window in your specific environment, you can use a loop to send marked requests during a reload:

while true; do curl -I http://your-app.local; sleep 0.1; done

Compare the response headers (e.g., X-Backend-Version) to identify the duration of the split-traffic window.

Missing Diagnostic Detail

To refine this recommendation: Does your migration involve replacing/removing existing backends in the same operation as adding new ones, or is it an add-only configuration change?