Architecting Rate Limiting in Traefik Proxy: Local vs. Global State

Protecting an upstream API from traffic spikes without deploying a dedicated rate-limiting service requires a decision on where the request counter lives and how a client is identified. Traefik Proxy provides a built-in Rate Limiting middleware that enforces limits at the edge, but the effective throughput is determined by the deployment topology and the trust boundary of the client IP.

Requirements for Edge Rate Limiting

A production-ready edge limit must be declarative, route-specific, and observable without modifying upstream application code. It should support per-client granularity—using either a network address or a trusted header—and return an HTTP 429 (Too Many Requests) response including a Retry-After header when thresholds are exceeded.

Traefik implements this using a token-bucket algorithm. This allows for a sustained rate (average) and a temporary burst capacity to handle legitimate spikes in traffic without immediately dropping requests.

Smallest Suitable Design

The minimal implementation protects a specific host and path using a single middleware defined in the dynamic configuration. This design assumes a single Traefik instance or a scenario where per-instance limiting is acceptable.

# Dynamic configuration (YAML file provider)
http:
  middlewares:
    api-limit:
      ratelimit:
        average: 5
        burst: 10
        source: remoteAddr
  routers:
    api-router:
      rule: "Host(`api.example.com`) && PathPrefix(`/v1/`)"
      service: api-service
      middlewares:
        - api-limit
  services:
    api-service:
      loadBalancer:
        servers:
          - url: "http://10.0.0.10:8080"

In this configuration, remoteAddr is used as the bucket key. If Traefik is positioned behind an external load balancer, you must configure forwardedHeaders in the entrypoint settings to ensure the actual client IP is used rather than the load balancer's internal IP.

Trust and Data Boundaries

By default, Traefik stores rate-limit counters in local memory. This creates a distributed boundary: each replica maintains its own independent token bucket. If you deploy three replicas with an average limit of 5 requests per second (rps), the cluster effectively permits 15 rps. This "water-fall" effect means the total capacity scales linearly with the number of replicas.

Identity trust is similarly local. The source key determines how buckets are partitioned. Using remoteAddr trusts the TCP peer. If a trusted header (like an API key) is used instead, the boundary shifts to the value of that header, which can be spoofed unless a preceding authentication middleware validates the request first.

To move from local to global enforcement, Traefik can be configured to use a shared store (such as Redis). This shifts the data boundary from process memory to an external network service, ensuring that a client is limited across the entire cluster regardless of which replica handles the request.

Operational Checks

To verify that the middleware is correctly attached to the router, query the Traefik API from a management host:

# Run on admin host with API access
curl -s http://traefik-admin:8080/api/http/routers/api-router | jq '.middlewares'

Expected Result: The output array must contain api-limit. If the name is missing or misspelled, Traefik will route traffic without applying any limits.

To validate the enforcement behavior, use a loop to exceed the burst capacity from a test client:

# Run from a client that can reach the entrypoint
for i in {1..15}; do curl -i -s -o /dev/null -w '%{http_code}\n' http://api.example.com/v1/data; done

Expected Result: The first 10 requests (the burst) should return 200 OK, followed by 429 Too Many Requests. Risk: Testing with IP-based limiting may temporarily block the test machine's IP from the API.

Failure Modes

• Silent Bypass: If the middleware name in the router does not exactly match the defined middleware, Traefik loads the router but ignores the limit. There is no explicit error for a missing middleware reference in some versions.
• Identity Collapsing: If forwardedHeaders are not configured while behind a proxy, all incoming traffic is seen as a single IP. This causes all users to share one bucket, leading to accidental denial of service for all clients.
• Reload Lag: Dynamic configuration changes are applied upon reload. In-flight requests during the reload window may be processed under the previous limit settings.

Conditions That Change the Design

The transition from a simple local limit to a more complex architecture is triggered by these requirements:

• Global Quotas: If you must enforce a strict limit (e.g., a paid tier of 1,000 requests/hour) across a multi-replica cluster, a shared Redis store is required.
• User-Based Limiting: If limits must be per-user rather than per-IP, place an authentication middleware before the rate-limit middleware in the chain to extract a verified identity header.
• Upstream Protection: If the goal is to protect a failing backend from latency-induced saturation rather than just request volume, supplement the rate limiter with a circuit breaker middleware.