Skip to main content

API Plan

Introduction​

API Plans provide a holistic approach to API governance by unifying the management of rate limits and quotas into a single, cohesive resource. While they utilize existing functionalities, API Plans reorganize these features to better embody the concept of comprehensive API governance. By defining API Plans, you can manage access levels, control usage, and ensure fair distribution of resources among your API consumers in a more structured and policy-driven manner.

This unified approach allows you to:

  • Centralize Policy Management: Consolidate rate limiting and quota enforcement into one resource, making it easier to maintain and update policies.
  • Enhance Clarity: Provide a clear representation of your API consumption policies, improving understanding for both API managers and consumers.
  • Streamline Access Control: Simplify the association between user groups and APIs through well-defined plans, leading to more efficient access management.
  • Ensure Consistency: Maintain consistent governance across all APIs by applying standardized plans, reducing the risk of misconfiguration.

Prerequisites​

For the APIPlan feature to work, you need to deploy and configure Redis in your cluster and Traefik deployment. You can do this by following these steps:

  1. Install the Redis via the Helm chart
helm install redis oci://registry-1.docker.io/bitnamicharts/redis -n traefik --wait
  1. Export your Redis instance password
export REDIS_PASSWORD=$(kubectl get secret --namespace traefik redis -o jsonpath="{.data.redis-password}" | base64 -d)
  1. Finally, upgrade your Traefik deployment to include Redis
helm upgrade traefik -n traefik --wait \
  --reuse-values \
  --set hub.redis.endpoints=redis-master.traefik.svc.cluster.local:6379 \
  --set hub.redis.password=${REDIS_PASSWORD} \
  traefik/traefik

API Plans behavior​

An APIPlan is a resource that specifies rate limits and quotas for API consumption. It is associated with an APIAccess resource, which grants access to specific APIs for certain user groups. API Plans provide a flexible way to manage API consumption policies across different user groups and APIs.

Key concepts​

  • API Plan: Defines the rate limits and quotas to be applied.
  • APIAccess: Grants access to APIs for specific user groups and associates an API Plan.
  • Groups: User groups defined in your Identity Provider (IDP).

Rate limit​

API rate limiting defines consumption limits for API consumers. It also controls the rate at which requests are allowed over a short period of time. It limits how fast requests can be made by delaying or rejecting excess requests to match the target rate. If requests exceed the allowed rate and cannot be delayed sufficiently, they are rejected with an HTTP status code 429 Too Many Requests.

Overall, It serves three main purposes:

  • Protecting infrastructure
  • Managing quotas
  • Enabling API monetization

To learn more about how API rate limiting works, check out the rate limiting section in the Distributed Rate Limit reference documentation

Quota​

Quota defines a fixed number of requests allowed over a given period of time . Once the quota limit is reached, further requests are immediately denied until the quota resets for the next period. If requests exceed the allowed rate and cannot be delayed sufficiently, they are rejected with an HTTP status code 429 Too Many Requests.

Note

In order to allow transition between two plans, the count of requests is stored on the API Access level. So, when a new API Plan is assigned to an API Access, the remaining requests are kept.

Creating an API plan​

To create an API Plan, you can use the following Custom Resource (CR):

Configuration example​

The following example defines an APIPlan named my-plan in the default namespace. It sets a rate limit of 1 request per second and a quota of 10,000 requests per month (expressed as 750 hours). This plan can be associated with APIAccess resources to enforce these limits on API consumers.

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: my-plan
  namespace: default
spec:
  title: "Standard"
  description: "**Standard Plan**"
  rateLimit:
    limit: 1
    period: 1s
  quota:
    limit: 10000
    period: 750h # 1 month

Configuration options​

FieldDescriptionRequiredDefault
titleA name for the plan. This is displayed in the consumer's API portalYes
descriptionA description of the plan, it is displayed in the consumer's API portal and it only supports markdownYes
rateLimitSpecifies the rate limit settings. This defines how many requests are allowed within a specified time period using the Token Bucket algorithm.YesN/A
rateLimit.limitThe maximum number of requests allowed within the rateLimit.period. Determines the refill rate of tokens in the Token Bucket algorithm.Yes (if rateLimit is set)
rateLimit.periodTime period for the rateLimitNoDefaults to 1s if omitted
quotaspecifies number of requests allowed in a larger time frame (e.g month)NoN/A
quota.limitMaximum number of requests in the specified time in quota.periodYes (if quota is set)
quota.periodTime period for the quota.No
Note
  • The supported duration units for periods are s (seconds), m (minutes), and h (hours). Example: "3h10m" will be interpreted as 3 hours and 10 minutes.
  • The description field supports standard markdown and GitHub Flavored Markdown

Associating an APIPlan with APIAccess​

To enforce an APIPlan, you need to associate it with an APIAccess resource. When you associate an APIPlan with an APIAccess resource the following occur:

  • Shared Quota Across APIs: The quota is shared across all APIs referenced by the APIAccess. For example, if an APIPlan sets a quota of 100 requests per month, and the APIAccess is linked to two APIs, API A and API B, the combined requests to both APIs cannot exceed 100 requests per month.

  • Independent Rate Limits per APIAccess: Rate limits are enforced per APIAccess. If a user belongs to multiple groups with different APIAccess resources, each APIAccess enforces its own rate limits independently.

  • Weight-Based and Name-Based Priority: When a user is associated with multiple APIAccess resources for the same API, the system determines which APIPlan to enforce based on the weight and the name of the APIAccess.

    • Weight: An optional integer value where a higher weight means higher priority.
    • Name Sorting: If weights are equal or not set, the APIAccess with the name that comes first alphabetically is selected.

Configuration example​

The following example defines an APIAccess resource named my-access in the default namespace. It grants access to the API named my-api to users in the group my-group. It associates the API Plan named my-plan with this access, enforcing the rate limits and quotas defined in that plan. The weight is set to 100, giving this access rule a higher priority when resolving overlaps with other APIAccess resources.

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: my-access
  namespace: default
spec:
  groups:
    - my-group
  apis:
    - name: my-api
  apiPlan:
    name: my-plan
  weight: 100
Info
  • Your APIPlan, API and APIAccess must exist in the same namespace
  • One APIAccess per Consumer: To avoid shared quotas, create separate APIAccess resources for each group. This ensures that each group's rate limits and quotas are enforced independently. See the Managing Overlapping Plans section
  • When multiple plans are applied to one user, the plan with the highest weight/priority takes precedence

Response Headers​

The following headers will be present in your API responses to help you track your quotas and rate limits:

Rate limit headers​

  • X-RateLimit-Limit: The maximum number of requests allowed in the current rate limit window.

Quota headers​

  • X-Quota-Limit: The maximum number of requests allowed in the current quota period.
  • X-Quota-Remaining: The number of requests remaining in the current quota period.
Note

Headers are only included if the quota or rate limit is set (not unlimited).

Managing overlapping plans​

When a consumer belongs to multiple groups with different APIAccess resources pointing to the same API, the system determines which plan to enforce based on the weight and the name of the APIAccess.

  • Weight: An optional integer value. Higher weight means higher priority.
  • Name Sorting: If weights are equal or not set, the APIAccess with the name that comes first alphabetically is selected.

Example​

A user belongs to both the "external" and "vip" groups. There are two APIAccess resources that grant access to a "Forecast" API with different plans and weights.

External group​

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: std-plan
  namespace: default
spec:
  title: "Standard Plan"
  rateLimit:
    limit: 1
    period: 1s

VIP group​

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: extra-plan
  namespace: default
spec:
  title: "Extra Plan"
  rateLimit:
    limit: 20
    period: 1s
  quota:
    limit: 1000
    period: 24h

Result: The system selects extra-access-vip because it has a higher weight, and the consumer receives the rate limits and quotas defined in the "Extra Plan".

Note
  • If the weights were equal or not set for both APIAccess resources, the system would select the one whose name comes first alphabetically.
  • Shared Quota Across APIs: If an APIAccess resource grants access to multiple APIs, the quota is shared across those APIs. For example, with a quota of 1000 requests per 24 hours, requests to any of the associated APIs contribute to this total.
  • No Automatic Fallback: If the quota under extra-plan is exhausted, the system does not automatically fall back to std-plan. The consumer would receive an HTTP status code 429 Too Many Requests until the quota resets.

Related content​