API Quotas Configuration Template

Quota Configuration Template

The following template demonstrates how to configure quotas using Lunar’s system. The example includes a fixed window quota and concurrent limits, with an option to define nested/internal quotas for more specific use cases.

note

File names for Lunar's YAML configurations don't need to follow a specific convention (e.g., quota.yaml). As long as the file is placed in the correct folder, Lunar will automatically detect and apply it.

/etc/lunar-proxy/quotas/{fileName}.yaml

# Quota Management Example: Defining and managing quotas
quota:
  id: MyQuota # Unique identifier for the quota
  filter: # Define the filter conditions for this quota
    url: api.website.com/* # URL pattern to apply the quota
    headers: # Optional: Define header-based filtering
      - key: x-lunar-consumer-tag # Header to apply filtering on
        value: premium # Example value 1
      - key: x-lunar-consumer-tag # Header to apply filtering on
        value: basic # Example value 2
  strategy: # Quota strategy definition
    fixed_window: # Fixed window strategy for quota management
      max: 1000 # Maximum number of requests allowed within the window
      interval: 24 # Window duration, e.g., 24 hours
      interval_unit: hour # Unit of time for the interval (second/minute/hour/day/month)
      group_by_header: x-lunar-consumer-tag # Optional: Group by header value

internal_limits: # Optional: Define nested child quotas within the main quota
  - id: MyChildQuota # Unique identifier for the child quota
    parent_id: MyQuota # Links the child quota to its parent
    filter:
      url: api.website.com/specific # URL pattern specific to the child quota
    strategy:
      fixed_window: # Strategy for managing child quota with a fixed window
        max: 500 # Maximum requests allowed within the child quota
        interval: 1 # Window duration for the child quota
        interval_unit: day # Unit of time for the child quota window

  - id: PremiumQuota
    parent_id: MyQuota
    filter:
      headers:
        - key: x-lunar-consumer-tag
          value: premium
    strategy:
      allocation_percentage: 80  # Percentage allocation of the total requests

Key Components of the Quota Configuration

Field	Description	Mandatory/Optional	Example
quota.id	A unique identifier for the quota.	Mandatory	MyQuota
filter.url	The URL pattern that the quota applies to.	Mandatory	api.website.com/*
filter.headers.key	Optional header used for filtering requests.	Optional	x-lunar-consumer-tag
filter.headers.value	Value of the header to match for filtering.	Optional	'premium'
strategy.fixed_window.max	Maximum number of requests allowed within the window.	Mandatory (if used)	1000
strategy.fixed_window.interval	Time window duration for the quota.	Mandatory (if used)	24
strategy.fixed_window.interval_unit	Unit of time for the window (e.g., minute, hour, day).	Mandatory (if used)	hour
fixed_window.group_by_header	Group quota by the value of a specific header.	Optional	x-lunar-consumer-tag
internal_limits.id	Unique identifier for child quotas.	Optional	MyChildQuota
internal_limits.parent_id	Links the child quota to its parent quota.	Optional	MyQuota
internal_limits.filter.url	URL pattern that the child quota applies to.	Mandatory (if used)	api.website.com/specific
internal_limits.strategy.fixed_window.max	Maximum requests allowed within the child quota’s window.	Mandatory (if used)	500
internal_limits.strategy.fixed_window.interval	Time window duration for the child quota.	Mandatory (if used)	1
internal_limits.strategy.fixed_window.interval_unit	Unit of time for the child quota (e.g., day).	Mandatory (if used)	day
internal_limits.strategy.allocation_percentage	Percentage of total main quota allocated to a child quota.	Mandatory (if used)	80