Configuring and Validating Traefik’s Rate Limit Middleware

Why use Traefik’s Rate Limit middleware

The Rate Limit middleware protects a backend service by rejecting excess requests with HTTP 429 Too Many Requests. It implements a token‑bucket algorithm: each client (by default identified by IP address) receives a refill of tokens at a steady rate and can burst up to a configured limit. When the bucket is empty, Traefik returns 429 before forwarding the request to the service.

Worked configuration example

The following dynamic configuration (YAML) defines a middleware called ratelimit that allows an average of 10 requests per second with a burst of 20, then attaches it to a router that forwards to the whoami service.

# dynamic.yaml
http:
  middlewares:
    ratelimit:
      rateLimit:
        average: 10          # tokens refilled per second
        burst: 20            # maximum tokens in the bucket
  routers:
    whoami-router:
      rule: Host(`example.com`)
      service: whoami
      middlewares:
        - ratelimit
  services:
    whoami:
      loadBalancer:
        servers:
          - url: \"http://whoami:80\"

Save the file as dynamic.yaml and tell Traefik to watch it (e.g., via the file provider or Kubernetes IngressRoute).

How the mechanism works

When a request arrives, Traefik looks up the client’s identifier (IP address by default) in the rate‑limit store. If the store is the default in‑memory map, each Traefik instance maintains its own counter. The token bucket is decremented for each request; if the bucket would go negative, the middleware responds with 429 and does not call the service. Successful requests refill the bucket at the average rate, up to the burst capacity.

Limits and deployment considerations

• In‑memory store: Limits are per Traefik replica. In a multi‑replica deployment the effective limit becomes average × replicas, which is often higher than intended.
• External store: To share counters across replicas, configure a Redis (or Consul, etcd) store under rateLimit → storeType. Example snippet:

    ratelimit:
      rateLimit:
        average: 10
        burst: 20
        storeType: redis
        redis:
          address: \"redis:6379\"
          username: \"\"
          password: \"\"

With Redis, all Traefik instances read and write the same counters, preserving the intended global limit.

Common mistakes and how to avoid them

1. Assuming in‑memory limits work in a cluster: Test with a single replica first, then verify the behavior after scaling out. If you see higher traffic than expected, switch to an external store.
2. Setting average or burst too low: A value like average: 1 can block legitimate bursts (e.g., browser page loads with multiple assets). Start with a value based on observed peak traffic and adjust after load testing.
3. Applying the middleware to the wrong router: Limits are scoped to the router. If multiple routers point to the same service but each has its own middleware instance, each enforces its own limit. To share a limit, reference the same middleware name across routers.
4. Overlooking the client identifier: By default the middleware uses the remote IP. If Traefik runs behind another proxy that forwards the original client IP via X-Forwarded-For, set sourceCriterion: ipStrategy with depth: 1 to honor that header.

Verifying the limit in practice

After applying the configuration, generate traffic from a single client and watch for the transition to 429.

# Run from a client machine
for i in {1..30}; do
  curl -s -o /dev/null -w \"%{http_code}\n\" http://example.com/
done

You should see responses of 200 for the first bursts (up to average + burst tokens) followed by 429 once the bucket is exhausted. Check Traefik logs for lines containing middleware-ratelimit and the client IP to confirm the middleware is counting.

If you are using Redis, you can inspect the key traefik_ratelimit__ with redis-cli GET to see the current token count.

Practical checklist

• Define the middleware with realistic average and burst values.
• Choose the appropriate store (in‑memory for a single replica, Redis for HA).
• Attach the middleware to the router(s) that need protection.
• Validate with a controlled load test and watch for 429 responses.
• Review logs or Redis keys to ensure counters are behaving as expected.