API Rate Limit

Rate limit your APIs for protection, quotas, and monetization.

---

Introduction

API rate limiting defines consumption limits for API consumers. It serves three main purposes: protecting infrastructure, managing quotas, and enabling API monetization.

By using the APIRateLimit object, you can apply rate limits to user groups for specific APIs. This helps to prevent API abuse, control traffic, and ensure a stable and predictable user experience.

Good to know

• You can configure multiple rate limits, using any combination of groups and APIs.
• An API can have multiple rate limit policies.

info

• When an API, for the same group, has two rate limits applied, the least privileged prevails (allowing restrictions on selected APIs).
• When a user has access to the same API through different groups, the most privileged group prevails for that user / API.

Rate Limiting Behavior

Limits over Time

Traefik Hub uses the Token Bucket algorithm, where the bucket represents the pool of available requests. Each request consumes one token from the bucket. Tokens are continuously refilled at a constant rate, ensuring a predefined limit on the number of requests that can be served in a given period of time.

For example, with a 1m period and a limit of 10 requests, Traefik Hub allows an average of 0.16 request per second (10/60s). This means that a new token is added to the bucket approximately every 0.16 seconds.

If users exhaust tokens faster than the bucket is refilled, the bucket becomes empty, and further requests will be rejected until new tokens become available.

Examples:

Limit	Period	Description
10	1m	The bucket receives a new token approximately every 0.16 seconds (10 / 60 seconds).
100	1h	The bucket receives a new token approximately every 0.02 seconds (100 / 3600 seconds).

Multiple Rate Limits

Same Group, Same API

If two rate limits are configured for the same API and a given group,, the least favorable one takes precedence. This flexibility allows API Managers to establish a general consumption rule while also defining exceptions for specific APIs.

Group Name	API Name	Rate limit
Group A	API A	5rq/s
Group A	API A, B, C	10rq/s

If a user is a member of Group A, they will be subject to a rate limit of 5rq/s on API A, which is the least favorable one for API A. However, they will have a rate limit of 10rq/s on APIs B and C.

Multiple Groups, Same API

When multiple user groups grant access to the same API, the rate limit from the most favorable group takes precedence.

Group Name	API Name	Rate limit
Group A5	API A	5rq/s
Group A10	API A	10rq/s

Users who belong to both Group A5 and Group A10 will be rate limited to 10rq/s on API A, which is the most favorable one among their assigned groups.

Combining Groups and APIs

The priority rules described above apply.

Group Name	API Name	Rate limit
Group A	API A	8rq/s
Group A	API A, B	10rq/s
Group B	API A, API C	5rq/s

If a user is part of both group A and group B, the following rate limits apply:

• 8rq/s on API A (5 from Group B, and 8 from Group A. The rate limit of the most favorable group is applied, but within the group, the least favorable applies)
• 10rq/s on API B (from Group B)
• 5rq/s on API C (from Group B)

Local & Distributed Strategies

Traefik Hub supports two strategies for rate limiting: local and distributed.

• Local strategy: applies rate limiting policies to a single Traefik Hub agent. If you run multiple agents, each instance manages its own bucket for spending and refilling tokens. Local is the default rate limiting strategy and does not require additional configuration.

• Distributed strategy: shares rate limiting policies across all Traefik Hub agents. This ensures consistency across all instances by using a single bucket. When configuring a distributed rate limiting strategy, Traefik Hub requires that you configure a Redis as a storage location.

tip

Use the appropriate rate limiting strategy based on your scalability and consistency requirements.

Managing API Rate Limiting Using CRDs

The mechanism for selecting user groups and APIs is the same as APIAccesses.

Local Strategy

Using the Local strategy (default)

apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
  name: my-rate-limit
  namespace: apps
spec:
  # Rate limit configuration, this config allows 100 requests/minute.
  limit: 100 # 100 requests
  period: 1m # One minute
  groups:
    - support
  apiSelector:
    matchLabels:
      module: crm

Distributed Strategy

Distributed Rate limit allowing 100 requests/minute.

apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
  name: my-rate-limit
  namespace: apps
spec:
  # Rate limit configuration, this config allows 100 requests/minute.
  limit: 100 # 100 requests
  period: 1m # One minute
  strategy: distributed
  groups:
    - support
  apiSelector:
    matchLabels:
      module: crm

Many Groups

Defining Rate Limiting to Multiple Groups

apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
  name: my-rate-limit
  namespace: apps
spec:
  # Rate limit configuration, this config allows 100 requests in one minute.
  limit: 100 # 100 requests
  period: 1m # One minute
  groups:
    - support
    - travel-agents
  apiSelector:
    matchExpressions:
      - key: area
        operator: In
        values:
          - flights
          - tickets
          - employee

Everyone

Using everyone to apply the rate limit to every authenticated users

apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
  name: my-rate-limit
  namespace: apps
spec:
  # Rate limit configuration, this config allows 100 requests in one minute.
  limit: 100 # 100 requests
  period: 1m # One minute
  everyone: true
  apiSelector:
    matchExpressions:
      - key: area
        operator: In
        values:
          - flights
          - tickets
          - employee

warning

You must configure either everyone or groups for rate limiting. Without setting one of them, rate limiting will not be applied.