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.
  • Managed Subscription: Grants access to APIs for applications and associates an API Plan.
  • APICatalogItem: Defines which APIs are visible to users on the Developer Portal.
  • 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 API Plan with ManagedSubscription & APICatalogItem​

To enforce an API Plan, you need to associate it with both ManagedSubscription and APICatalogItem resources.

  • APICatalogItem: Controls the visibility of APIs or API Bundles on the Developer Portal for specific user groups and associates the available API Plans.
  • ManagedSubscription: Grants consumption access to applications, specifying which applications can consume which APIs or API Bundles under specific API Plans.

When you associate an API Plan with these resources, the following occur:

  • Shared Quota Across APIs: The quota is shared across all APIs referenced by a single ManagedSubscription. For example, if an APIPlan sets a quota of 100 requests per month, and the ManagedSubscription 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 ManagedSubscription: Rate limits are enforced per ManagedSubscription. If an application is included in multiple ManagedSubscription resources with different API Plans on the same APIs, the system determines which plan to enforce based on the weight and the name of the ManagedSubscription.

    info

    See the Managing overlapping plans section for more information

Configuration example​

The following example defines:

  • An APICatalogItem named my-api-catalog in the default namespace, making my-api visible to users in the group my-group, and associating it with the my-plan API Plan.
  • A ManagedSubscription named my-subscription in the default namespace, granting consumption access to the application with appId: "my-app-id", associating it with my-api and the my-plan API Plan. The weight is set to 100, giving this subscription a higher priority when resolving overlaps with other ManagedSubscription resources.
apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: my-api-catalog
  namespace: default
spec:
  groups:
    - my-group
  apis:
    - name: my-api
  apiPlan:
    name: my-plan
Info
  • Your APIPlan, API, APICatalogItem, and ManagedSubscription resources must exist in the same namespace.
  • Application-Level Access: Unlike APIAccess, which used user groups, ManagedSubscription operates at the application level. You must explicitly list the applications (appIds) that are granted access.
  • One ManagedSubscription per Application Group: To avoid shared quotas, create separate ManagedSubscription resources for each application or group of applications that should share quotas.
  • When multiple plans are applied to one application, 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 an application is associated with multiple ManagedSubscription resources pointing to the same API, the system determines which plan to enforce based on the weight and the name of the ManagedSubscription.

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

Example​

An application (appId: "forecast-app") is included in both the external and vip Managed Subscriptions. There are two ManagedSubscription resources that grant access to the “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: vip-plan
  namespace: default
spec:
  title: "VIP Plan"
  rateLimit:
    limit: 20
    period: 1s
  quota:
    limit: 1000
    period: 24h

Result: The system selects vip-subscription because it has a higher weight, and the application receives the rate limits and quotas defined in the “VIP Plan”.

Note
  • If the weights were equal or not set for both ManagedSubscription resources, the system would select the one whose name comes first alphabetically.
  • Shared Quota Across APIs: If a ManagedSubscription 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 application would receive an HTTP status code 429 Too Many Requests until the quota resets.

Related content​