docs: add QuotaPolicy capability guide

[missBerg]

Description

Adds comprehensive documentation for the QuotaPolicy CRD, which was fully implemented
but had no user-facing documentation. Covers service-wide quotas, per-model quotas,
CEL cost expressions, Exclusive vs Shared bucket modes, client-selector based bucket rules,
shadow mode, and duration format. Follows the structure of existing traffic capability guides.

Distinguishes QuotaPolicy (total consumption budgets) from rate limiting (request velocity)
to help adopters choose the right mechanism.

Related Issues/PRs (if applicable)

Related #1571

Special notes for reviewers (if applicable)

All field definitions and semantics sourced from api/v1alpha1/quota_policy.go GoDoc comments.
Includes complete, copy-pasteable YAML examples for every configuration option.

[dosubot]

Related Documentation

9 document(s) may need updating based on files changed in this PR:

Envoy's Space

index /ai-gateway/blob/main/site/versioned_docs/version-0.3/capabilities/index.md

View Suggested Changes

@@ -31,6 +31,7 @@
 
 - **[Model Virtualization](./traffic/model-virtualization.md)**: Abstract and virtualize AI models
 - **[Provider Fallback](./traffic/provider-fallback.md)**: Automatic failover between AI providers
+- **[Quota Policy](./traffic/quota-policy.md)**: Manage total token consumption budgets across time windows
 - **[Usage-based Rate Limiting](./traffic/usage-based-ratelimiting.md)**: Token-aware rate limiting for AI workloads
 
 ## Security

[Accept] [Decline]

index /ai-gateway/blob/main/site/versioned_docs/version-0.4/capabilities/traffic/index.md

View Suggested Changes

@@ -3,4 +3,4 @@
 title: Traffic Handling
 ---
 
-This section provides information about traffic routing related capabilities in Envoy AI Gateway.
+This section provides information about traffic routing related capabilities in Envoy AI Gateway, including quota management for controlling total token consumption budgets across time windows.

[Accept] [Decline]

index /ai-gateway/blob/main/site/docs/capabilities/index.md

View Suggested Changes

@@ -35,6 +35,7 @@
 
 - **[Model Virtualization](./traffic/model-virtualization.md)**: Abstract and virtualize AI models
 - **[Provider Fallback](./traffic/provider-fallback.md)**: Automatic failover between AI providers
+- **[Quota Policy](./traffic/quota-policy.md)**: Manage total token consumption budgets with time-based limits
 - **[Usage-based Rate Limiting](./traffic/usage-based-ratelimiting.md)**: Token-aware rate limiting for AI workloads
 
 ## Security

[Accept] [Decline]

index /ai-gateway/blob/main/site/docs/capabilities/traffic/index.md

View Suggested Changes

@@ -3,4 +3,4 @@
 title: Traffic Handling
 ---
 
-This section provides information about traffic routing related capabilities in Envoy AI Gateway.
+This section provides information about traffic routing related capabilities in Envoy AI Gateway, including quota management for controlling total token consumption budgets across time windows.

[Accept] [Decline]

index /ai-gateway/blob/main/site/versioned_docs/version-0.5/capabilities/index.md

View Suggested Changes

@@ -35,6 +35,7 @@
 
 - **[Model Virtualization](./traffic/model-virtualization.md)**: Abstract and virtualize AI models
 - **[Provider Fallback](./traffic/provider-fallback.md)**: Automatic failover between AI providers
+- **[Quota Policy](./traffic/quota-policy.md)**: Manage total token consumption budgets with caps on cumulative token spend across time windows
 - **[Usage-based Rate Limiting](./traffic/usage-based-ratelimiting.md)**: Token-aware rate limiting for AI workloads
 
 ## Security

[Accept] [Decline]

index /ai-gateway/blob/main/site/versioned_docs/version-0.3/capabilities/traffic/index.md

View Suggested Changes

@@ -3,4 +3,4 @@
 title: Traffic Handling
 ---
 
-This section provides information about traffic routing related capabilities in Envoy AI Gateway.
+This section provides information about traffic routing related capabilities in Envoy AI Gateway, including quota management for controlling total token consumption budgets across time windows.

[Accept] [Decline]

index /ai-gateway/blob/main/site/versioned_docs/version-0.5/capabilities/traffic/index.md

View Suggested Changes

@@ -3,4 +3,6 @@
 title: Traffic Handling
 ---
 
-This section provides information about traffic routing related capabilities in Envoy AI Gateway.
+This section provides information about traffic routing related capabilities in Envoy AI Gateway, including:
+
+- **Quota Policy** -- token-based quota management for controlling total consumption budgets across time windows

[Accept] [Decline]

index /ai-gateway/blob/main/site/versioned_docs/version-0.4/capabilities/index.md

View Suggested Changes

@@ -31,6 +31,7 @@
 
 - **[Model Virtualization](./traffic/model-virtualization.md)**: Abstract and virtualize AI models
 - **[Provider Fallback](./traffic/provider-fallback.md)**: Automatic failover between AI providers
+- **[Quota Policy](./traffic/quota-policy.md)**: Manage total token consumption budgets with caps on cumulative token spend across time windows
 - **[Usage-based Rate Limiting](./traffic/usage-based-ratelimiting.md)**: Token-aware rate limiting for AI workloads
 
 ## Security

[Accept] [Decline]

usage-based-ratelimiting /ai-gateway/blob/main/site/docs/capabilities/traffic/usage-based-ratelimiting.md

View Suggested Changes

@@ -8,6 +8,17 @@
 import TabItem from '@theme/TabItem';
 
 This guide focuses on AI Gateway's specific capabilities for token-based rate limiting in LLM requests. For general rate limiting concepts and configurations, refer to [Envoy Gateway's Rate Limiting documentation](https://gateway.envoyproxy.io/docs/tasks/traffic/global-rate-limit/).
+
+:::info Choosing Between QuotaPolicy and Usage-Based Rate Limiting
+
+AI Gateway provides two complementary mechanisms for token control:
+
+- **[QuotaPolicy](./quota-policy.md)**: Manages **total consumption budgets** (e.g., "allow 100,000 tokens per hour"). Use this when you need to cap cumulative token spend across a time window to prevent cost overruns.
+
+- **Usage-Based Rate Limiting** (this page): Controls **request velocity** (e.g., "allow X requests per second"). Use this when you need to throttle the rate at which requests are processed.
+
+These capabilities can be used together to provide comprehensive cost and traffic control.
+:::
 
 ## Overview
 

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[JAORMX]

Nice work documenting QuotaPolicy — the structure follows existing capability guides well and the progressive examples are clear. A few accuracy issues against the Go types that should be addressed.

[JAORMX]

The variable list here is incomplete. Per shared_types.go, the CEL environment exposes 8 variables, not 3:

Variable	Type	Description
input_tokens	uint	Input tokens
cached_input_tokens	uint	Cached read input tokens
cache_creation_input_tokens	uint	Cache creation input tokens
output_tokens	uint	Output tokens
total_tokens	uint	Total tokens (the default cost)
reasoning_tokens	uint	Reasoning tokens
model	string	Model name from request
backend	string	Backend as "name.namespace"

total_tokens, reasoning_tokens, model, backend, and cache_creation_input_tokens are all missing.

[JAORMX]

Worth noting explicitly that serviceQuota only supports a flat limit + duration. Bucket modes, bucket rules, and client selectors are not available at the service-wide level — those are only on perModelQuotas (the Go types are ServiceQuotaDefinition vs QuotaDefinition).

Without this callout, a reader may try to add bucketRules or mode under serviceQuota and be confused when validation fails.

Suggestion — add a line like:

For bucket modes, client selectors, and per-tenant rules, use perModelQuotas instead.

[JAORMX]

This feature requires the same infrastructure as usage-based rate limiting (Redis + Envoy Gateway rate limit service). A prerequisites section should be added, similar to the one in usage-based-ratelimiting.md (lines 50-58). Something like:

:::tip Prerequisites
Quota enforcement requires the same components as usage-based rate limiting:
1. **Redis Deployment**: A Redis instance for storing quota counters.
2. **Envoy Gateway Configuration**: Envoy Gateway must be configured at installation time to enable rate limiting and point to your Redis instance. See [Envoy Gateway Installation Guide](../../getting-started/prerequisites.md#additional-features-rate-limiting-inferencepool-etc)
:::

[JAORMX]

The examples only show header-based client selectors, but the underlying RateLimitSelectCondition from Envoy Gateway also supports sourceCIDR, queryParams, path, and method matching. Worth mentioning these exist, or at minimum linking to the Envoy Gateway rate limit API reference so users know about the full set of selector options.

[JAORMX]

Nit: 100 000 uses a space as thousands separator. The YAML examples use 100000. Consider normalizing to 100,000 or 100000 for consistency.

[yanavlasov]

Thank you @missBerg . The doc covers everything. I agree with suggestions from @JAORMX

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.69%. Comparing base (345ee3e) to head (96c02f8).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1947   +/-   ##
=======================================
  Coverage   84.69%   84.69%           
=======================================
  Files         144      144           
  Lines       21248    21248           
=======================================
  Hits        17997    17997           
  Misses       2166     2166           
  Partials     1085     1085           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[missBerg]

/retest