API Rate Limit
Manage quotas and limit to your APIs.
Introduction
The API rate limit object defines the consumption limit for consumers of APIs.
The limits are attached to groups and applied to APIs or Collections.
- You can configure multiple rate limits, using any combination of groups and APIs.
- An API can have multiple rate limit policies.
- 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.
The token bucket algorithm defines the number of requests that can be served in a given period of time.
With a 1m period and a limit of 10 requests, Traefik Hub accepts an average of 0.16 request per second (10/60s).
In other words, every 0.16 seconds, the bucket receives a new token.
This represents the rate at which the bucket of available requests fills up.
Users spend one token for each request that gets removed from the bucket. Simultaneously, the bucket is refilled at a constant rate, given that it isn't already full.
If users spend tokens faster than buckets are refilled, requests will be rejected once the bucket is empty and until new tokens are available.
Examples:
| Limit | Period | Description |
|---|---|---|
| 10 | 1m | The bucket gets a new token every .16 seconds (10 / 60 seconds). |
| 100 | 1h | The bucket gets a new token every .02 seconds (100 / 3600 seconds). |
Multiple Rate Limits
Same Group, Same API
Within the same group, if two rate limits target the same API, the least favorable one applies.
This allows API Managers to declare a general rule for consumption, then apply exceptions for a subset of APIs.
| Group Name | API Name | Rate limit |
|---|---|---|
| Group A | API A | 5rq/s |
| Group A | API A, B, C | 10rq/s |
If a user belongs to Group A, they will get 5rq/s on API A, which is the least favorable one on API A, but will get 10rq/s on API B and C.
Different Groups, Same API
When different groups provide access to the same API, the most favorable one applies.
| Group Name | API Name | Rate limit |
|---|---|---|
| Group A5 | API A | 5rq/s |
| Group A10 | API A | 10rq/s |
If a user belongs to Group A5 and Group A10, they will get 10rq/s on API A, which is the most favorable one from their 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 belongs to group A and group B, they will get:
- 8rq/s on API A (5 from Group B, and 8 from group A. The most favorable group applies, 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 Rate Limiting
Traefik Hub supports two strategies: local and distributed rate limiting.
Local rate limiting applies rate limiting policies to a single Traefik Hub agent.
If you scale an API using two Traefik Hub agents, each agent will use its own bucket (spending / refilling tokens).
Distributed rate limiting shares the bucket among multiple Traefik Hub agents.
If you scale an API using two Traefik Hub agents, one policy and thus one bucket configuration will be used across all Traefik Hub agents.
Local is the default strategy for rate limiting because it doesn't require extra configuration.
When configuring a distributed rate limiting strategy, Traefik Hub requires that you configure a Redis as a storage location.
Rate Limiting Configuration Options
| Field | Description | Required |
|---|---|---|
limit | The number of tokens in a bucket. | Yes |
period | The time period (speed) at which the tokens are added into the bucket. Time period can be seconds, minutes or hours (s/m/h). Default value is one second.second. | No |
anyGroups | anyGroups will apply to every group and any user, whether they belong to a group or not. | No |
groups | Name of the group(s) which will be rate limited. See the user management reference for more information. | No |
apis.name | Select APIs based on names. You can combine it with apiSelector.matchLabels and apiSelector.matchExpressions. See Labels and Selectors. | No |
apis.namespace | Name of the Kubernetes Namespace used by the API(s) defined in apis.name. This is required for apis.name. | No |
apiSelector.matchLabels | Select APIs based on label matching: Equality-Based Requirements. | No |
apiSelector.matchExpressions | Select APIs based on advanced labels expressions: Set-Based Requirements. | No |
You must configure either anyGroups or groups for rate limiting.
Without setting one of them, rate limiting will not be applied.
Managing API Rate Limiting Using CRDs
- Local Strategy
- Distributed Strategy
- Many Groups
- All Groups
apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
name: my-rate-limit
spec:
# Rate limit configuration, this config allows 100 requests/minute.
limit: 100 # 100 requests
period: 1m # One minute
groups:
- support
apiSelector:
matchLabels:
module: crm
apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
name: my-rate-limit
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
apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
name: my-rate-limit
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
apiVersion: hub.traefik.io/v1alpha1
kind: APIRateLimit
metadata:
name: my-rate-limit
spec:
# Rate limit configuration, this config allows 100 requests in one minute.
limit: 100 # 100 requests
period: 1m # One minute
anyGroups: true
apiSelector:
matchExpressions:
- key: area
operator: In
values:
- flights
- tickets
- employee