For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Apply local and global rate limits to HTTP traffic to protect your backend services from overload.

Apply local and global rate limits to HTTP traffic to protect your backend services from overload.

About

Rate limiting in agentgateway protects your services from being overwhelmed by excessive traffic. A runaway automation script, a misconfigured retry loop, or a deliberate flood can exhaust your upstream’s capacity in seconds. Rate limiting gives you precise control over how much traffic reaches any route or the entire gateway — without any changes to the backend.

Rate limiting in agentgateway is expressed through AgentgatewayPolicy resources. A policy attaches to a Gateway or HTTPRoute target, and defines limits in the spec.traffic.rateLimit field. Gateway-level policies act as a hard ceiling on total traffic, while route-level policies provide finer-grained control.

Additionally, you can set up local or global rate limiting, depending on whether you want limits shared across Gateway instances.

For AI-specific use cases, see:

• Rate limiting for LLMs
• Rate limiting for MCP

Gateway-level global DoS protection

Target your Gateway resource to apply a limit across all routes. This acts as a hard ceiling on total gateway throughput regardless of which route is hit.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: gateway-rate-limit
  namespace: agentgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: agentgateway-proxy
  traffic:
    rateLimit:
      local:
      - requests: 5000
        unit: Minutes
        burst: 1000
EOF

Route-level rate limit

Route-level policies take precedence over gateway-level ones for their specific traffic.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: httpbin-rate-limit
  namespace: httpbin
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
  traffic:
    rateLimit:
      local:
      - requests: 3
        unit: Seconds
        burst: 3
EOF

Inheritance

Policies apply at the attachment point with a clear precedence order:

Gateway → Listener → Route → Route Rule → Backend

More specific policies win. A route-level limit overrides a gateway-level limit for traffic on that route.

With both policies in place, traffic to www.example.com is subject to the route limit (3 req/s), while all other routes are bounded only by the gateway limit (5000 req/min).

Response headers

When rate limiting is enabled, the following headers are added to responses. These headers help clients understand their current rate limit status and adapt their behavior accordingly.

Note: The x-envoy-ratelimited header is only present when using global rate limiting with an Envoy-compatible rate limit service. It is added by the rate limit service itself, not by agentgateway. As such, this header does not appear with local rate limiting.

Before you begin

1. Follow the Get started guide to install agentgateway.

2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

3. Get the external address of the gateway and save it in an environment variable.

   Cloud Provider LoadBalancerPort-forward for local testing

   Tip

   Kind cluster? Kind does not support LoadBalancer services by default. To use this option with a Kind cluster, install and run cloud-provider-kind.

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS  

   kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 8080:80

Local rate limiting

Local rate limiting runs entirely inside the agentgateway proxy — no external service needed. The following steps show how to apply request-based limits to your HTTP traffic.

1. Apply a rate limit to the httpbin HTTPRoute.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: httpbin-rate-limit
     namespace: httpbin
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: httpbin
     traffic:
       rateLimit:
         local:
         - requests: 3
           unit: Seconds
           burst: 3
   EOF
   Review the following table to understand this configuration.

   Field	Required	Description
   requests	Yes	Number of requests allowed per unit.
   unit	Yes	Seconds, Minutes, or Hours.
   burst	No	Extra requests allowed above the base rate in a short burst. The burst field implements a token bucket on top of the base rate. With requests: 3, burst: 3, you get up to 6 requests in one burst (3 base + 3 burst capacity), then the bucket refills at 3 per second. This absorbs short traffic spikes without rejecting requests. This setting only works with requests, not with token rate limits.
   key	No	CEL expression that selects the bucket a request counts against, such as the jwt.sub claim for a limit per user. Each distinct value gets its own bucket with the limits above. When unset, all requests on the target share one bucket. For more information, see Claim-level rate limits.

2. Verify that the policy is attached.

   kubectl get AgentgatewayPolicy httpbin-rate-limit -n httpbin \
     -o jsonpath='{.status.ancestors[0].conditions}' | jq .

   A healthy policy reports both Accepted and Attached as True:

   [
     {
       "type": "Accepted",
       "status": "True",
       "message": "Policy accepted"
     },
     {
       "type": "Attached",
       "status": "True",
       "message": "Attached to all targets"
     }
   ]

   If Attached is False, the policy’s targetRef points to a resource that doesn’t exist. Check the message field for the exact resource name that’s missing.

3. Fire 10 rapid requests to test the rate limit.

   Cloud Provider LoadBalancerPort-forward for local testing

   for i in $(seq 1 10); do
     STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
       http://$INGRESS_GW_ADDRESS:80/headers -H "host: www.example.com")
     echo "Request $i: HTTP $STATUS"
   done

   for i in $(seq 1 10); do
     STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
       localhost:8080/headers -H "host: www.example.com")
     echo "Request $i: HTTP $STATUS"
   done

   Example output:

   Request 1: HTTP 200
   Request 2: HTTP 200
   Request 3: HTTP 200
   Request 4: HTTP 200
   Request 5: HTTP 200
   Request 6: HTTP 200
   Request 7: HTTP 429
   Request 8: HTTP 429
   Request 9: HTTP 429
   Request 10: HTTP 429

   The first 6 succeed (3 base + 3 burst), then requests are rejected until the bucket refills. Inspect a 429 response to see the rate limit headers:

   HTTP/1.1 429 Too Many Requests
   x-ratelimit-limit: 6
   x-ratelimit-remaining: 0
   x-ratelimit-reset: 0
   content-type: text/plain
   content-length: 19
   
   rate limit exceeded

4. After 1 second the bucket refills and requests succeed again.

   sleep 1 && curl -o /dev/null -w "%{http_code}\n" \
     localhost:8080/headers -H "host: www.example.com"
   # 200

Claim-level rate limits

Create claim-level rate limits with CEL expressions.

The limit that you applied in the previous section is shared by every request on the route, so one busy client can exhaust it for everyone else. To limit each caller separately, set the key field to a CEL expression. Each distinct value that the expression returns gets its own token bucket with the limits of that rule. The expression typically reads a claim in a JWT, such as jwt.sub for a limit per user, jwt.team for a limit per team, or jwt.sub + "/" + request.path for a limit per user per path. This way, you can enforce claim-level limits without an external rate limit service.

In production, key the limit on a value that the client cannot choose, which means a claim from a JWT authentication policy that targets the same route.

    rateLimit:
      local:
      - requests: 2
        unit: Minutes
        key: jwt.sub

The following steps key the limit on a request header instead, so that you can see the behavior without an identity provider.

1. Update the httpbin-rate-limit policy from the previous section to key the limit on a user header. The rest of the policy is unchanged, so the route keeps one policy rather than gaining a second one.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: httpbin-rate-limit
     namespace: httpbin
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: httpbin
     traffic:
       rateLimit:
         local:
         - requests: 2
           unit: Minutes
           key: 'request.headers["x-user"]'
   EOF

2. Send three requests as one user. The first two succeed, and the third is rejected.

   Cloud Provider LoadBalancerPort-forward for local testing

   for i in $(seq 1 3); do
     curl -s -o /dev/null -w "alice request $i: HTTP %{http_code}\n" \
       http://$INGRESS_GW_ADDRESS:80/headers -H "host: www.example.com" -H "x-user: alice"
   done

   for i in $(seq 1 3); do
     curl -s -o /dev/null -w "alice request $i: HTTP %{http_code}\n" \
       localhost:8080/headers -H "host: www.example.com" -H "x-user: alice"
   done

   Example output:

   alice request 1: HTTP 200
   alice request 2: HTTP 200
   alice request 3: HTTP 429

3. Send requests as a second user. These requests succeed, because each user has an independent bucket.

   Cloud Provider LoadBalancerPort-forward for local testing

   for i in $(seq 1 3); do
     curl -s -o /dev/null -w "bob request $i: HTTP %{http_code}\n" \
       http://$INGRESS_GW_ADDRESS:80/headers -H "host: www.example.com" -H "x-user: bob"
   done

   for i in $(seq 1 3); do
     curl -s -o /dev/null -w "bob request $i: HTTP %{http_code}\n" \
       localhost:8080/headers -H "host: www.example.com" -H "x-user: bob"
   done

   Example output:

   bob request 1: HTTP 200
   bob request 2: HTTP 200
   bob request 3: HTTP 429

Review the following behavior before you rely on a claim-level limit.

• Requests without a value: Requests whose key is empty, or whose expression cannot be evaluated, such as a request with no x-user header in this example, all share one bucket. An empty key does not exempt a request from the limit. To apply a limit to only some requests, use conditional policies instead.
• How many buckets are kept, and where they live: Each rule keeps up to 65,536 buckets and drops the least used ones, which for that key is the same as never having been seen. Buckets are held in memory by a single proxy replica, so each replica enforces the limit separately. For a limit that is shared across replicas, use global rate limiting.
• Invalid expressions: If the expression does not compile, the policy is accepted with the PartiallyValid reason, and the rest of the policy still applies. Check the policy status for the message local rate limit key is not a valid CEL expression.

For the variables that you can read in a key, see Variables and functions.

Global rate limiting

Local rate limiting runs independently on each proxy replica. If you run multiple agentgateway replicas and need a shared quota across the fleet, use global rate limiting backed by an external service such as Envoy’s rate limit service.

For detailed instructions on setting up global rate limiting with descriptors and an external rate limit service, see the Global rate limiting guide.

Conditional execution

To apply different rate limits based on the request, use the conditional field on your rateLimit policy. For example, you can apply stricter limits on writes than on reads. For details, see Conditional policies.

Cleanup

kubectl delete AgentgatewayPolicy httpbin-rate-limit -n httpbin

Apply more than one local limit

The local field takes a list, so one policy can carry several limits. Every entry in the list is enforced, and a request is rejected with a 429 response as soon as any one of them is exhausted.

Use more than one entry to combine a short window that absorbs a burst with a long window that caps sustained volume.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: httpbin-rate-limit
  namespace: httpbin
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
  traffic:
    rateLimit:
      local:
      # Short window: smooth out bursts
      - requests: 10
        unit: Seconds
        burst: 5
      # Long window: cap sustained volume
      - requests: 100
        unit: Minutes
EOF

In this example, a client can send 10 requests per second, and no more than 100 requests per minute. A client that sends 10 requests per second continuously is rejected once it reaches 100 requests in the minute, even though it never exceeds the per-second limit.

Each entry is independent, and each keeps its own counter. Local rate limits run per proxy replica, so the effective limit across a deployment is the configured limit multiplied by the replica count. To share counters across replicas, use global rate limiting instead.