apiVersion: v1
kind: ConfigMap
@@ -2594,170 +2594,172 @@
stringRequired
The name of the header to set.
Validation
Pattern^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
integer
HTTP status code to return.
Validation
Formatint32
Minimum200
Maximum599
Documentation References (1)
integer
HTTP status code to return.
Validation
Formatint32
Minimum200
Maximum599
Documentation References (1)
object
External authentication configuration for the policy.
This selects the external server to send requests to for authentication.
An extAuth policy can be conditionally set by nesting configuration under the conditional field.
Validation
Ruleexactly one of backendRef or url must be set unless conditional is set
Ruleexactly one of the fields in [grpc http] must be set
RuleforwardBody cannot be used with http.body
Ruleurl path is only valid with http
Rulehttp.path may not be set when url includes a path
Ruleconditional cannot be set with any other field
Documentation References (3)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (2)
stringRequired
Name is the name of the referent.
Validation
Documentation References (2)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (2)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (2)
object[]
Conditional policy execution. Set this or the top-level extAuth fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (1)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleexactly one of backendRef or url is required
Ruleexactly one of the fields in [grpc http] must be set
RuleforwardBody cannot be used with http.body
Ruleurl path is only valid with http
Rulehttp.path may not be set when url includes a path
Documentation References (1)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (1)
stringRequired
Name is the name of the referent.
Validation
Documentation References (1)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (1)
object
Caches authorization results.
WARNING: the safety of this feature depends on the cache key accurately
capturing every request property that the authorization service uses to
make a decision. For example, if the service returns different results
based on both path and authorization header, both must be included in
key; otherwise, one request may incorrectly reuse another request's
authorization result.
If any key expression fails to evaluate or produces an unsupported value,
the request is still sent to the authorization service, but its result is
not read from or written to the cache.
string[]Required
Ordered list of CEL expressions evaluated against the request
to construct the cache key.
Validation
integer
Maximum number of authorization results to keep in
the cache. If unset, this defaults to 10000.
Validation
stringRequired
Duration string, such as 5m, or a CEL expression that
returns the duration that cached authorization results may be reused, or a
timestamp when the cached authorization result expires. The expression is
evaluated after the authorization response has been applied to the request.
Validation
Min length1
Max length16384
string
Behavior when the external authorization service is
unavailable or returns an error. "FailOpen" allows the request to continue.
"FailClosed" (default) denies the request.
Validation
Documentation References (1)
object
Uses the gRPC External Authorization
[protocol](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto) should be used.
Documentation References (1)
object
Uses HTTP to connect to
the authorization server. The authorization server must return a 200
status code, otherwise the request is considered an authorization
failure.
Documentation References (1)
string[]
Headers from the authorization response that
will be copied into the request to the backend.
Validation
Documentation References (1)
string
Path to send to the authorization server. If
unset, this defaults to the original request path.
This is a CEL expression, which allows customizing the path based on the
incoming request. For example, to add a prefix, use
"/prefix/" + request.path.
Validation
Min length1
Max length16384
Documentation References (1)
object
External processing configuration for the policy.
Validation
Ruleexactly one of backendRef or url must be set unless conditional is set
Ruleurl must not include a path
Ruleconditional cannot be set with any other field
Documentation References (2)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (1)
stringRequired
Name is the name of the referent.
Validation
Documentation References (1)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (1)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (1)
object[]
Conditional policy execution. Set this or the top-level extProc fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (2)
string
CEL expression that must evaluate to true for this policy to execute.
Validation
Min length1
Max length16384
Documentation References (2)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleexactly one of backendRef or url is required
Ruleurl must not include a path
Documentation References (2)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (2)
stringRequired
Name is the name of the referent.
Validation
Documentation References (2)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (2)
string
Behavior when the external processor is unavailable or returns an error.
"FailOpen" allows the request to continue, as long as the request body has not
been sent (or started streaming) to the ext_proc. Once the request body has
started streaming to the ext_proc, the request will fail closed on error.
"FailClosed" (default) rejects the request on any failure.
Validation
object
Metadata to send to the external processor in the
metadata_context.filter_metadata field of the ProcessingRequest.
Keyed by metadata namespace, then by key within that namespace; values are
CEL expressions evaluated per request.
Validation
object
How request and response phases are sent to ext_proc.
Documentation References (1)
boolean
Allows ext_proc mode_override values from matching header responses to update
subsequent request/response processing phases for this exchange. Defaults to false.
string
How request bodies are sent to the external processor.
Defaults to FullDuplexStreamed.
Validation
EnumBuffered, BufferedPartial, FullDuplexStreamed, None
Documentation References (1)
string
Whether request headers are sent to the external processor.
Defaults to Send.
Validation
string
Whether request trailers are sent to the external processor.
Defaults to Send.
Validation
string
How response bodies are sent to the external processor.
Defaults to FullDuplexStreamed.
Validation
EnumBuffered, BufferedPartial, FullDuplexStreamed, None
Documentation References (1)
string
Whether response headers are sent to the external processor.
Defaults to Send.
Validation
string
Whether response trailers are sent to the external processor.
Defaults to Send.
Validation
object
Request attributes to send to the external processor in the request
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per request.
Validation
object
Response attributes to send to the external processor in the response
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per response.
Validation
boolean
Allows ext_proc mode_override values from matching header responses to update
subsequent request/response processing phases for this exchange. Defaults to false.
Documentation References (1)
string
Whether request headers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
string
Whether request trailers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
string
Whether response headers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
string
Whether response trailers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
object
Request and response header modification policy.
Validation
Ruleat least one of the fields in [request response] must be set
object
Header changes to apply before forwarding a request.
object[]
Add adds the given header(s) (name, value) to the request
before the action. It appends to any existing values associated
with the header name.
Input:
GET /foo HTTP/1.1
my-header: foo
Config:
add:
- name: "my-header"
value: "bar,baz"
Output:
GET /foo HTTP/1.1
my-header: foo,bar,baz
Validation
Max items16
List typemap
List map keysname
string[]
Remove the given header(s) from the HTTP request before the action. The
value of Remove is a list of HTTP header names. Note that the header
names are case-insensitive (see
https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
Input:
GET /foo HTTP/1.1
my-header1: foo
my-header2: bar
my-header3: baz
Config:
remove: ["my-header1", "my-header3"]
Output:
GET /foo HTTP/1.1
my-header2: bar
Validation
object[]
Set overwrites the request with the given header (name, value)
before the action.
Input:
GET /foo HTTP/1.1
my-header: foo
Config:
set:
- name: "my-header"
value: "bar"
Output:
GET /foo HTTP/1.1
my-header: bar
Validation
Max items16
List typemap
List map keysname
object
Header changes to apply before returning a response.
object
How to rewrite the Host header for requests.
If the HTTPRoute urlRewrite filter already specifies a host rewrite,
this setting is ignored.
stringRequired
Hostname rewrite mode.
The following may be specified:
* Auto: automatically set the Host header based on the destination.
* None: do not rewrite the Host header. The original Host header
will be passed through.
This setting defaults to Auto when connecting to hostname-based
Backend types, and None otherwise, for Service or IP-based
backends.
Validation
object
Authenticates users based on JWT tokens.
Validation
RulejwtAuthentication.mcp requires exactly one provider
RulejwtAuthentication.mcp requires mode Strict
Documentation References (13)
object
Where JWT credentials are read from.
If omitted, credentials are read from the Authorization header with the Bearer prefix.
Validation
Ruleexactly one of the fields in [header queryParameter cookie expression] must be set
object
Enables MCP OAuth metadata endpoint handling
and MCP-specific authentication behavior on top of standard JWT validation.
When set, the gateway will serve the MCP OAuth metadata discovery endpoints.
Documentation References (6)
string
Client ID to use for short-circuiting Dynamic Client Registration.
If set, the gateway will not proxy registration requests to the IDP and instead return this client ID.
Documentation References (5)
string
Identity provider to use for MCP authentication flows.
Validation
EnumAuth0, Authentik, Descope, Entra, Keycloak, Okta
Documentation References (6)
object
Metadata to use for MCP resources,
served at the MCP OAuth metadata endpoints.
Documentation References (6)
string
Validation mode for JWT authentication. Defaults to Strict.
Validation
EnumOptional, Permissive, Strict
Documentation References (12)
boolean
Keeps a successfully validated JWT in its original location. By default, the gateway removes
the JWT after validation. When the token only needs to be forwarded to the selected backend,
prefer backendAuth.passthrough so it is not exposed to other policies in the request path.
Documentation References (1)
object[]Required
No description for this field.
Validation
Documentation References (13)
string[]
Allowed audiences that are allowed
access. This corresponds to the aud claim
([RFC 7519 §4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)).
If unset, any audience is allowed.
Validation
Documentation References (9)
stringRequired
IdP that issued the JWT. This corresponds to the
iss claim ([RFC 7519 §4.1.1](https://tools.ietf.org/html/rfc7519#section-4.1.1)).
Validation
Documentation References (13)
objectRequired
JSON Web Key Set used to validate the signature of the
JWT.
Validation
Ruleexactly one of the fields in [remote inline] must be set
Documentation References (13)
string
Inline JSON Web Key Set used to validate the
signature of the JWT.
Validation
Min length2
Max length65536
Documentation References (3)
object
How to reach the JSON Web Key Set from a remote
address.
Validation
RulejwksPath is required when backendRef is set
RulejwksPath may not be set when url is set
Ruleexactly one of the fields in [backendRef url] must be set
Documentation References (10)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (10)
string
Group of the referent, for example gateway.networking.k8s.io. Empty selects the core API group
Validation
Pattern^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Max length253
Documentation References (8)
string
Kubernetes resource kind of the referent, for example Service. Defaults to Service
Validation
DefaultService
Pattern^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Min length1
Max length63
Documentation References (10)
stringRequired
Name is the name of the referent.
Validation
Documentation References (10)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (5)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (10)
string
How long a fetched jwks document is used before it is re-fetched from the IdP.
Defaults to 5m.
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Max length32
RulecacheDuration must be at least 5m.
Documentation References (3)
string
Path to the IdP jwks endpoint, relative to the root, commonly
".well-known/jwks.json".
Validation
Min length1
Max length1024
Documentation References (10)
string
The phase to apply the traffic policy to. If the phase is PreRouting,
the targetRef must be a Gateway or a Listener. PreRouting is
typically used only when a policy needs to influence the routing
decision.
Even when using PostRouting mode, the policy can target the
Gateway or Listener. This is a helper for applying the policy to all
routes under that Gateway or Listener, and follows the merging logic
described above.
Note: PreRouting and PostRouting rules do not merge together. These
are independent execution phases. That is, all PreRouting rules will
merge and execute, then all PostRouting rules will merge and execute.
If unset, this defaults to PostRouting.
Validation
EnumPostRouting, PreRouting
Documentation References (5)
object
Rate limiting configuration for the policy.
This limits the rate at which requests are processed.
Validation
Ruleat least one of the fields in [conditional global local] must be set
Ruleconditional cannot be set with any other field
Documentation References (10)
object[]
Conditional policy execution. Set this or the top-level rateLimit fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (1)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleat least one of the fields in [global local] must be set
Documentation References (1)
object
Global rate limiting policy using an external service.
Validation
Ruleurl must not include a path
Ruleexactly one of the fields in [backendRef url] must be set
object[]Required
Dimensions for rate limiting. These values are
passed to the rate limit service which applies configured limits based
on them. Each descriptor represents a single rate limit rule with one or
more entries.
Validation
string
Common Expression Language (CEL) expression that determines
the cost of the request for this descriptor. If unset, Requests costs
default to 1, and Tokens costs default to the total token count.
Tokens cost are evaluated after the request has completed. For non-streaming requests, request, llm, and
response fields are all available; for streaming requests, response is not available (however, all LLM
attributes are in llm). For Requests, cost is computed during the request phase.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
object[]Required
Individual components that make up this descriptor.
Validation
stringRequired
Common Expression Language (CEL) expression that
defines the value for the descriptor.
For example, to rate limit based on the Client IP: source.address.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
string
Common Expression Language (CEL) expression that returns a dynamic
limit override for this descriptor. The expression must evaluate to an
object containing unit and requestsPerUnit, for example
{"unit":"minute","requestsPerUnit":5}.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
string
Cost unit. If unspecified,
Requests is used.
Validation
stringRequired
Domain under which this limit should apply.
This is an arbitrary string that enables a rate limit server to distinguish between different applications.
Validation
string
Behavior when the remote rate limit service is
unavailable or returns an error. FailOpen allows the request to continue.
FailClosed (default) denies the request.
Validation
object[]
Local rate limiting policy.
Validation
Documentation References (1)
integer
Allowance of requests above the request-per-unit
that should be allowed within a short period of time.
Validation
string
CEL expression selecting the bucket the request counts against, for example jwt.sub for a
per-user limit or jwt.team for a per-team limit. Each distinct value gets its own bucket with
the limit above. Requests without a value, or whose expression cannot be evaluated, share one
bucket. When unset, all requests share one bucket. Each proxy instance keeps a bounded number
of buckets per rule and drops the least used ones.
Validation
Min length1
Max length16384
integer
Number of HTTP requests per unit of time that
are allowed. Requests exceeding this limit will fail with a 429
error.
Validation
Documentation References (1)
integer
Number of LLM tokens per unit of time that are
allowed. Requests exceeding this limit will fail with a 429 error.
Both input and output tokens are counted. However, token counts are not known until the request completes. As a
result, token-based rate limits will apply to future requests only.
Validation
stringRequired
Unit of time for the limit.
Validation
EnumHours, Minutes, Seconds
Documentation References (1)
object
Global rate limiting policy using an external service.
Validation
Ruleurl must not include a path
Ruleexactly one of the fields in [backendRef url] must be set
Documentation References (3)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (3)
string
Kubernetes resource kind of the referent, for example Service. Defaults to Service
Validation
DefaultService
Pattern^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Min length1
Max length63
Documentation References (2)
stringRequired
Name is the name of the referent.
Validation
Documentation References (3)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (2)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (3)
object[]Required
Dimensions for rate limiting. These values are
passed to the rate limit service which applies configured limits based
on them. Each descriptor represents a single rate limit rule with one or
more entries.
Validation
Documentation References (3)
object[]Required
Individual components that make up this descriptor.
Validation
Documentation References (3)
stringRequired
Common Expression Language (CEL) expression that
defines the value for the descriptor.
For example, to rate limit based on the Client IP: source.address.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
Documentation References (3)
stringRequired
Validation
Documentation References (3)
string
Common Expression Language (CEL) expression that returns a dynamic
limit override for this descriptor. The expression must evaluate to an
object containing unit and requestsPerUnit, for example
{"unit":"minute","requestsPerUnit":5}.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
Documentation References (1)
string
Cost unit. If unspecified,
Requests is used.
Validation
Documentation References (2)
stringRequired
Domain under which this limit should apply.
This is an arbitrary string that enables a rate limit server to distinguish between different applications.
Validation
Documentation References (3)
object[]
Local rate limiting policy.
Validation
Documentation References (9)
integer
Allowance of requests above the request-per-unit
that should be allowed within a short period of time.
Validation
Documentation References (4)
string
CEL expression selecting the bucket the request counts against, for example jwt.sub for a
per-user limit or jwt.team for a per-team limit. Each distinct value gets its own bucket with
the limit above. Requests without a value, or whose expression cannot be evaluated, share one
bucket. When unset, all requests share one bucket. Each proxy instance keeps a bounded number
of buckets per rule and drops the least used ones.
Validation
Min length1
Max length16384
Documentation References (3)
integer
Number of HTTP requests per unit of time that
are allowed. Requests exceeding this limit will fail with a 429
error.
Validation
Documentation References (6)
integer
Number of LLM tokens per unit of time that are
allowed. Requests exceeding this limit will fail with a 429 error.
Both input and output tokens are counted. However, token counts are not known until the request completes. As a
result, token-based rate limits will apply to future requests only.
Validation
Documentation References (4)
stringRequired
Unit of time for the limit.
Validation
EnumHours, Minutes, Seconds
Documentation References (9)
object
Documentation References (3)
integer
Attempts specifies the maximum number of times an individual request
from the gateway to a backend should be retried.
If the maximum number of retries has been attempted without a successful
response from the backend, the Gateway MUST return an error.
When this field is unspecified, the number of times to attempt to retry
a backend request is implementation-specific.
Support: Extended
Validation
Documentation References (3)
string
Minimum duration to wait between retry attempts, in Gateway API Duration format. Implementations may add jitter or use exponential backoff, and must not exceed a configured request timeout. Support: Extended
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Documentation References (3)
integer[]
Codes defines the HTTP response status codes for which a backend request
should be retried.
Support: Extended
Validation
Documentation References (3)
string
condition is a CEL expression evaluated against each response to decide
whether to retry. A response is retried when its status code is in codes or
this expression evaluates to true.
Validation
Min length1
Max length16384
string
precondition is a CEL expression evaluated against the request before any
attempt is made. When it evaluates to false, retries are disabled and only
the initial attempt is made, for example request.method == "GET".
Retrying requires buffering the request body in memory for replay, so this lets
us skip that cost when the request is known to be non-retriable (for example
streaming uploads or long-lived connections like websockets).
Validation
Min length1
Max length16384
object
Request timeouts.
It is applicable to HTTPRoute resources and ignored for other targeted
kinds.
Validation
Ruleat least one of the fields in [request responseIdle] must be set
Documentation References (2)
string
Maximum time allowed from the start of downstream request processing until response headers
are received. The response body is not included; use responseIdle to bound gaps between body frames.
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Max length32
Rulerequest must be at least 1ms
Documentation References (2)
string
Maximum time to wait for a frame from the upstream response body.
Limits how long the gateway waits for more response data from the backend.
Time spent processing the response or waiting for the client to receive it does not count.
This complements Request rather than overlapping it: Request stops applying once the response
headers arrive, so it places no bound on how long the response body may take, and it cannot
distinguish a stalled stream from a slow one.
This does not apply to responses that switch protocols, so upgraded WebSocket connections and
CONNECT tunnels are never terminated by it.
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Max length32
RuleresponseIdle must be at least 1ms
object
Mutates and transforms requests and responses
before forwarding them to the destination.
Validation
Ruleat least one of the fields in [conditional request response] must be set
Ruleconditional cannot be set with any other field
Documentation References (22)
object[]
Conditional policy execution. Set this or the top-level transformation fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (1)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleat least one of the fields in [request response] must be set
Documentation References (1)
object
Request transformation settings.
Validation
Ruleat least one of the fields in [add body metadata remove set] must be set
Documentation References (1)
object[]
Headers to add to the request and what each value
should be set to. If there is already a header with these values then
append the value as an extra entry.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (1)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (1)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (1)
object
Request transformation settings.
Validation
Ruleat least one of the fields in [add body metadata remove set] must be set
Documentation References (15)
string
HTTP body transformation.
Validation
Min length1
Max length16384
Documentation References (3)
string[]
Header names to remove from the request or
response.
Validation
Min items1
Max items16
List typeset
Documentation References (3)
object[]
Headers to set and the values to use.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (10)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (10)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (10)
object
Response transformation settings.
Validation
Ruleat least one of the fields in [add body metadata remove set] must be set
Documentation References (6)
object[]
Headers to add to the request and what each value
should be set to. If there is already a header with these values then
append the value as an extra entry.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (1)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (1)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (1)
string
HTTP body transformation.
Validation
Min length1
Max length16384
Documentation References (1)
string[]
Header names to remove from the request or
response.
Validation
Min items1
Max items16
List typeset
Documentation References (1)
object[]
Headers to set and the values to use.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (5)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (5)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (5)
object[]Required
Ancestor resources (usually Gateways) associated with the policy, with the policy's status for each. At most 16 entries; an empty list means the policy is not relevant to any ancestor
Validation
Max items16
List typeatomic
objectRequired
AncestorRef corresponds with a ParentRef in the spec that this
PolicyAncestorStatus struct describes the status of.
string
Group is the group of the referent.
When unspecified, "gateway.networking.k8s.io" is inferred.
To set the core API group (such as for a "Service" kind referent),
Group must be explicitly set to "" (empty string).
Support: Core
Validation
Defaultgateway.networking.k8s.io
Pattern^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Max length253
string
Kind is kind of the referent.
There are two kinds of parent resources with "Core" support:
* Gateway (Gateway conformance profile)
* Service (Mesh conformance profile, ClusterIP Services only)
Support for other resources is Implementation-Specific.
Validation
DefaultGateway
Pattern^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Min length1
Max length63
stringRequired
Name is the name of the referent.
Support: Core
Validation
string
Namespace of the referent. Defaults to the Route's local namespace. Cross-namespace references must be explicitly allowed, for example via ReferenceGrant. Support: Core
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
integer
Port this Route targets on the parent, interpreted per parent kind (for example a Gateway listener port or Service port). Support: Extended
Validation
Formatint32
Minimum1
Maximum65535
string
Name of a section within the target resource, for example a Gateway Listener name or Service port name. Empty references the entire resource. Support: Core
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Min length1
Max length253
object[]Required
Conditions describing the status of the policy for this ancestor
Validation
Min items1
Max items8
List typemap
List map keystype
stringRequired
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
Validation
stringRequired
message is a human readable message indicating details about the transition.
This may be an empty string.
Validation
integer
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance.
Validation
stringRequired
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty.
Validation
Pattern^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
Min length1
Max length1024
stringRequired
status of the condition, one of True, False, Unknown.
Validation
stringRequired
type of condition in CamelCase or in foo.example.com/CamelCase.
Validation
Pattern^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
Max length316
stringRequired
ControllerName is a domain/path string that indicates the name of the
controller that wrote this status. This corresponds with the
controllerName field on GatewayClass.
Example: "example.net/gateway-controller".
The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are
valid Kubernetes names
(https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
Controllers MUST populate this field when writing status. Controllers should ensure that
entries to status populated with their ControllerName are cleaned up when they are no
longer necessary.
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$
Min length1
Max length253
object
External authentication configuration for the policy.
This selects the external server to send requests to for authentication.
An extAuth policy can be conditionally set by nesting configuration under the conditional field.
Validation
Ruleexactly one of backendRef or url must be set unless conditional is set
Ruleexactly one of the fields in [grpc http] must be set
RuleforwardBody cannot be used with http.body
Ruleurl path is only valid with http
Rulehttp.path may not be set when url includes a path
Ruleconditional cannot be set with any other field
Documentation References (4)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (3)
string
Group of the referent, for example gateway.networking.k8s.io. Empty selects the core API group
Validation
Pattern^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Max length253
Documentation References (1)
string
Kubernetes resource kind of the referent, for example Service. Defaults to Service
Validation
DefaultService
Pattern^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Min length1
Max length63
Documentation References (1)
stringRequired
Name is the name of the referent.
Validation
Documentation References (3)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (2)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (2)
object[]
Conditional policy execution. Set this or the top-level extAuth fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (1)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleexactly one of backendRef or url is required
Ruleexactly one of the fields in [grpc http] must be set
RuleforwardBody cannot be used with http.body
Ruleurl path is only valid with http
Rulehttp.path may not be set when url includes a path
Documentation References (1)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (1)
stringRequired
Name is the name of the referent.
Validation
Documentation References (1)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (1)
object
Caches authorization results.
WARNING: the safety of this feature depends on the cache key accurately
capturing every request property that the authorization service uses to
make a decision. For example, if the service returns different results
based on both path and authorization header, both must be included in
key; otherwise, one request may incorrectly reuse another request's
authorization result.
If any key expression fails to evaluate or produces an unsupported value,
the request is still sent to the authorization service, but its result is
not read from or written to the cache.
string[]Required
Ordered list of CEL expressions evaluated against the request
to construct the cache key.
Validation
integer
Maximum number of authorization results to keep in
the cache. If unset, this defaults to 10000.
Validation
stringRequired
Duration string, such as 5m, or a CEL expression that
returns the duration that cached authorization results may be reused, or a
timestamp when the cached authorization result expires. The expression is
evaluated after the authorization response has been applied to the request.
Validation
Min length1
Max length16384
string
Behavior when the external authorization service is
unavailable or returns an error. "FailOpen" allows the request to continue.
"FailClosed" (default) denies the request.
Validation
Documentation References (1)
object
Uses the gRPC External Authorization
[protocol](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto) should be used.
Documentation References (1)
object
Uses HTTP to connect to
the authorization server. The authorization server must return a 200
status code, otherwise the request is considered an authorization
failure.
Documentation References (2)
string[]
Headers from the authorization response that
will be copied into the request to the backend.
Validation
Documentation References (1)
string
Path to send to the authorization server. If
unset, this defaults to the original request path.
This is a CEL expression, which allows customizing the path based on the
incoming request. For example, to add a prefix, use
"/prefix/" + request.path.
Validation
Min length1
Max length16384
Documentation References (2)
object
External processing configuration for the policy.
Validation
Ruleexactly one of backendRef or url must be set unless conditional is set
Ruleurl must not include a path
Ruleconditional cannot be set with any other field
Documentation References (2)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (1)
stringRequired
Name is the name of the referent.
Validation
Documentation References (1)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (1)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (1)
object[]
Conditional policy execution. Set this or the top-level extProc fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (2)
string
CEL expression that must evaluate to true for this policy to execute.
Validation
Min length1
Max length16384
Documentation References (2)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleexactly one of backendRef or url is required
Ruleurl must not include a path
Documentation References (2)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (2)
stringRequired
Name is the name of the referent.
Validation
Documentation References (2)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (2)
string
Behavior when the external processor is unavailable or returns an error.
"FailOpen" allows the request to continue, as long as the request body has not
been sent (or started streaming) to the ext_proc. Once the request body has
started streaming to the ext_proc, the request will fail closed on error.
"FailClosed" (default) rejects the request on any failure.
Validation
object
Metadata to send to the external processor in the
metadata_context.filter_metadata field of the ProcessingRequest.
Keyed by metadata namespace, then by key within that namespace; values are
CEL expressions evaluated per request.
Validation
object
How request and response phases are sent to ext_proc.
Documentation References (1)
boolean
Allows ext_proc mode_override values from matching header responses to update
subsequent request/response processing phases for this exchange. Defaults to false.
string
How request bodies are sent to the external processor.
Defaults to FullDuplexStreamed.
Validation
EnumBuffered, BufferedPartial, FullDuplexStreamed, None
Documentation References (1)
string
Whether request headers are sent to the external processor.
Defaults to Send.
Validation
string
Whether request trailers are sent to the external processor.
Defaults to Send.
Validation
string
How response bodies are sent to the external processor.
Defaults to FullDuplexStreamed.
Validation
EnumBuffered, BufferedPartial, FullDuplexStreamed, None
Documentation References (1)
string
Whether response headers are sent to the external processor.
Defaults to Send.
Validation
string
Whether response trailers are sent to the external processor.
Defaults to Send.
Validation
object
Request attributes to send to the external processor in the request
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per request.
Validation
object
Response attributes to send to the external processor in the response
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per response.
Validation
boolean
Allows ext_proc mode_override values from matching header responses to update
subsequent request/response processing phases for this exchange. Defaults to false.
Documentation References (1)
string
Whether request headers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
string
Whether request trailers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
string
Whether response headers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
string
Whether response trailers are sent to the external processor.
Defaults to Send.
Validation
Documentation References (1)
object
Request and response header modification policy.
Validation
Ruleat least one of the fields in [request response] must be set
object
Header changes to apply before forwarding a request.
object[]
Add adds the given header(s) (name, value) to the request
before the action. It appends to any existing values associated
with the header name.
Input:
GET /foo HTTP/1.1
my-header: foo
Config:
add:
- name: "my-header"
value: "bar,baz"
Output:
GET /foo HTTP/1.1
my-header: foo,bar,baz
Validation
Max items16
List typemap
List map keysname
string[]
Remove the given header(s) from the HTTP request before the action. The
value of Remove is a list of HTTP header names. Note that the header
names are case-insensitive (see
https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
Input:
GET /foo HTTP/1.1
my-header1: foo
my-header2: bar
my-header3: baz
Config:
remove: ["my-header1", "my-header3"]
Output:
GET /foo HTTP/1.1
my-header2: bar
Validation
object[]
Set overwrites the request with the given header (name, value)
before the action.
Input:
GET /foo HTTP/1.1
my-header: foo
Config:
set:
- name: "my-header"
value: "bar"
Output:
GET /foo HTTP/1.1
my-header: bar
Validation
Max items16
List typemap
List map keysname
object
Header changes to apply before returning a response.
object
How to rewrite the Host header for requests.
If the HTTPRoute urlRewrite filter already specifies a host rewrite,
this setting is ignored.
stringRequired
Hostname rewrite mode.
The following may be specified:
* Auto: automatically set the Host header based on the destination.
* None: do not rewrite the Host header. The original Host header
will be passed through.
This setting defaults to Auto when connecting to hostname-based
Backend types, and None otherwise, for Service or IP-based
backends.
Validation
object
Authenticates users based on JWT tokens.
Validation
RulejwtAuthentication.mcp requires exactly one provider
RulejwtAuthentication.mcp requires mode Strict
Documentation References (13)
object
Where JWT credentials are read from.
If omitted, credentials are read from the Authorization header with the Bearer prefix.
Validation
Ruleexactly one of the fields in [header queryParameter cookie expression] must be set
object
Enables MCP OAuth metadata endpoint handling
and MCP-specific authentication behavior on top of standard JWT validation.
When set, the gateway will serve the MCP OAuth metadata discovery endpoints.
Documentation References (6)
string
Client ID to use for short-circuiting Dynamic Client Registration.
If set, the gateway will not proxy registration requests to the IDP and instead return this client ID.
Documentation References (5)
string
Identity provider to use for MCP authentication flows.
Validation
EnumAuth0, Authentik, Descope, Entra, Keycloak, Okta
Documentation References (6)
object
Metadata to use for MCP resources,
served at the MCP OAuth metadata endpoints.
Documentation References (6)
string
Validation mode for JWT authentication. Defaults to Strict.
Validation
EnumOptional, Permissive, Strict
Documentation References (12)
boolean
Keeps a successfully validated JWT in its original location. By default, the gateway removes
the JWT after validation. When the token only needs to be forwarded to the selected backend,
prefer backendAuth.passthrough so it is not exposed to other policies in the request path.
Documentation References (1)
object[]Required
No description for this field.
Validation
Documentation References (13)
string[]
Allowed audiences that are allowed
access. This corresponds to the aud claim
([RFC 7519 §4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)).
If unset, any audience is allowed.
Validation
Documentation References (9)
stringRequired
IdP that issued the JWT. This corresponds to the
iss claim ([RFC 7519 §4.1.1](https://tools.ietf.org/html/rfc7519#section-4.1.1)).
Validation
Documentation References (13)
objectRequired
JSON Web Key Set used to validate the signature of the
JWT.
Validation
Ruleexactly one of the fields in [remote inline] must be set
Documentation References (13)
string
Inline JSON Web Key Set used to validate the
signature of the JWT.
Validation
Min length2
Max length65536
Documentation References (3)
object
How to reach the JSON Web Key Set from a remote
address.
Validation
RulejwksPath is required when backendRef is set
RulejwksPath may not be set when url is set
Ruleexactly one of the fields in [backendRef url] must be set
Documentation References (10)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (10)
string
Group of the referent, for example gateway.networking.k8s.io. Empty selects the core API group
Validation
Pattern^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Max length253
Documentation References (8)
string
Kubernetes resource kind of the referent, for example Service. Defaults to Service
Validation
DefaultService
Pattern^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Min length1
Max length63
Documentation References (10)
stringRequired
Name is the name of the referent.
Validation
Documentation References (10)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (5)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (10)
string
How long a fetched jwks document is used before it is re-fetched from the IdP.
Defaults to 5m.
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Max length32
RulecacheDuration must be at least 5m.
Documentation References (3)
string
Path to the IdP jwks endpoint, relative to the root, commonly
".well-known/jwks.json".
Validation
Min length1
Max length1024
Documentation References (10)
string
The phase to apply the traffic policy to. If the phase is PreRouting,
the targetRef must be a Gateway or a Listener. PreRouting is
typically used only when a policy needs to influence the routing
decision.
Even when using PostRouting mode, the policy can target the
Gateway or Listener. This is a helper for applying the policy to all
routes under that Gateway or Listener, and follows the merging logic
described above.
Note: PreRouting and PostRouting rules do not merge together. These
are independent execution phases. That is, all PreRouting rules will
merge and execute, then all PostRouting rules will merge and execute.
If unset, this defaults to PostRouting.
Validation
EnumPostRouting, PreRouting
Documentation References (5)
object
Rate limiting configuration for the policy.
This limits the rate at which requests are processed.
Validation
Ruleat least one of the fields in [conditional global local] must be set
Ruleconditional cannot be set with any other field
Documentation References (10)
object[]
Conditional policy execution. Set this or the top-level rateLimit fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (1)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleat least one of the fields in [global local] must be set
Documentation References (1)
object
Global rate limiting policy using an external service.
Validation
Ruleurl must not include a path
Ruleexactly one of the fields in [backendRef url] must be set
object[]Required
Dimensions for rate limiting. These values are
passed to the rate limit service which applies configured limits based
on them. Each descriptor represents a single rate limit rule with one or
more entries.
Validation
string
Common Expression Language (CEL) expression that determines
the cost of the request for this descriptor. If unset, Requests costs
default to 1, and Tokens costs default to the total token count.
Tokens cost are evaluated after the request has completed. For non-streaming requests, request, llm, and
response fields are all available; for streaming requests, response is not available (however, all LLM
attributes are in llm). For Requests, cost is computed during the request phase.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
object[]Required
Individual components that make up this descriptor.
Validation
stringRequired
Common Expression Language (CEL) expression that
defines the value for the descriptor.
For example, to rate limit based on the Client IP: source.address.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
string
Common Expression Language (CEL) expression that returns a dynamic
limit override for this descriptor. The expression must evaluate to an
object containing unit and requestsPerUnit, for example
{"unit":"minute","requestsPerUnit":5}.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
string
Cost unit. If unspecified,
Requests is used.
Validation
stringRequired
Domain under which this limit should apply.
This is an arbitrary string that enables a rate limit server to distinguish between different applications.
Validation
string
Behavior when the remote rate limit service is
unavailable or returns an error. FailOpen allows the request to continue.
FailClosed (default) denies the request.
Validation
object[]
Local rate limiting policy.
Validation
Documentation References (1)
integer
Allowance of requests above the request-per-unit
that should be allowed within a short period of time.
Validation
string
CEL expression selecting the bucket the request counts against, for example jwt.sub for a
per-user limit or jwt.team for a per-team limit. Each distinct value gets its own bucket with
the limit above. Requests without a value, or whose expression cannot be evaluated, share one
bucket. When unset, all requests share one bucket. Each proxy instance keeps a bounded number
of buckets per rule and drops the least used ones.
Validation
Min length1
Max length16384
integer
Number of HTTP requests per unit of time that
are allowed. Requests exceeding this limit will fail with a 429
error.
Validation
Documentation References (1)
integer
Number of LLM tokens per unit of time that are
allowed. Requests exceeding this limit will fail with a 429 error.
Both input and output tokens are counted. However, token counts are not known until the request completes. As a
result, token-based rate limits will apply to future requests only.
Validation
stringRequired
Unit of time for the limit.
Validation
EnumHours, Minutes, Seconds
Documentation References (1)
object
Global rate limiting policy using an external service.
Validation
Ruleurl must not include a path
Ruleexactly one of the fields in [backendRef url] must be set
Documentation References (3)
object
backendRef selects a backend for this policy.
Mutually exclusive with url.
Validation
RuleMust have port for Service reference
Documentation References (3)
string
Kubernetes resource kind of the referent, for example Service. Defaults to Service
Validation
DefaultService
Pattern^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Min length1
Max length63
Documentation References (2)
stringRequired
Name is the name of the referent.
Validation
Documentation References (3)
string
Namespace of the referent. Defaults to the local namespace. A cross-namespace reference requires a ReferenceGrant in the referent namespace
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
Documentation References (2)
integer
Destination port number. Required when the referent is a Kubernetes Service
Validation
Formatint32
Minimum1
Maximum65535
Documentation References (3)
object[]Required
Dimensions for rate limiting. These values are
passed to the rate limit service which applies configured limits based
on them. Each descriptor represents a single rate limit rule with one or
more entries.
Validation
Documentation References (3)
object[]Required
Individual components that make up this descriptor.
Validation
Documentation References (3)
stringRequired
Common Expression Language (CEL) expression that
defines the value for the descriptor.
For example, to rate limit based on the Client IP: source.address.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
Documentation References (3)
stringRequired
Validation
Documentation References (3)
string
Common Expression Language (CEL) expression that returns a dynamic
limit override for this descriptor. The expression must evaluate to an
object containing unit and requestsPerUnit, for example
{"unit":"minute","requestsPerUnit":5}.
See https://agentgateway.dev/docs/standalone/latest/reference/cel/ for more info.
Validation
Min length1
Max length16384
Documentation References (1)
string
Cost unit. If unspecified,
Requests is used.
Validation
Documentation References (2)
stringRequired
Domain under which this limit should apply.
This is an arbitrary string that enables a rate limit server to distinguish between different applications.
Validation
Documentation References (3)
object[]
Local rate limiting policy.
Validation
Documentation References (9)
integer
Allowance of requests above the request-per-unit
that should be allowed within a short period of time.
Validation
Documentation References (4)
string
CEL expression selecting the bucket the request counts against, for example jwt.sub for a
per-user limit or jwt.team for a per-team limit. Each distinct value gets its own bucket with
the limit above. Requests without a value, or whose expression cannot be evaluated, share one
bucket. When unset, all requests share one bucket. Each proxy instance keeps a bounded number
of buckets per rule and drops the least used ones.
Validation
Min length1
Max length16384
Documentation References (3)
integer
Number of HTTP requests per unit of time that
are allowed. Requests exceeding this limit will fail with a 429
error.
Validation
Documentation References (6)
integer
Number of LLM tokens per unit of time that are
allowed. Requests exceeding this limit will fail with a 429 error.
Both input and output tokens are counted. However, token counts are not known until the request completes. As a
result, token-based rate limits will apply to future requests only.
Validation
Documentation References (4)
stringRequired
Unit of time for the limit.
Validation
EnumHours, Minutes, Seconds
Documentation References (9)
object
Documentation References (3)
integer
Attempts specifies the maximum number of times an individual request
from the gateway to a backend should be retried.
If the maximum number of retries has been attempted without a successful
response from the backend, the Gateway MUST return an error.
When this field is unspecified, the number of times to attempt to retry
a backend request is implementation-specific.
Support: Extended
Validation
Documentation References (3)
string
Minimum duration to wait between retry attempts, in Gateway API Duration format. Implementations may add jitter or use exponential backoff, and must not exceed a configured request timeout. Support: Extended
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Documentation References (3)
integer[]
Codes defines the HTTP response status codes for which a backend request
should be retried.
Support: Extended
Validation
Documentation References (3)
string
condition is a CEL expression evaluated against each response to decide
whether to retry. A response is retried when its status code is in codes or
this expression evaluates to true.
Validation
Min length1
Max length16384
string
precondition is a CEL expression evaluated against the request before any
attempt is made. When it evaluates to false, retries are disabled and only
the initial attempt is made, for example request.method == "GET".
Retrying requires buffering the request body in memory for replay, so this lets
us skip that cost when the request is known to be non-retriable (for example
streaming uploads or long-lived connections like websockets).
Validation
Min length1
Max length16384
object
Request timeouts.
It is applicable to HTTPRoute resources and ignored for other targeted
kinds.
Validation
Ruleat least one of the fields in [request responseIdle] must be set
Documentation References (2)
string
Maximum time allowed from the start of downstream request processing until response headers
are received. The response body is not included; use responseIdle to bound gaps between body frames.
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Max length32
Rulerequest must be at least 1ms
Documentation References (2)
string
Maximum time to wait for a frame from the upstream response body.
Limits how long the gateway waits for more response data from the backend.
Time spent processing the response or waiting for the client to receive it does not count.
This complements Request rather than overlapping it: Request stops applying once the response
headers arrive, so it places no bound on how long the response body may take, and it cannot
distinguish a stalled stream from a slow one.
This does not apply to responses that switch protocols, so upgraded WebSocket connections and
CONNECT tunnels are never terminated by it.
Validation
Pattern^([0-9]{1,5}(h|m|s|ms)){1,4}$
Max length32
RuleresponseIdle must be at least 1ms
object
Mutates and transforms requests and responses
before forwarding them to the destination.
Validation
Ruleat least one of the fields in [conditional request response] must be set
Ruleconditional cannot be set with any other field
Documentation References (22)
object[]
Conditional policy execution. Set this or the top-level transformation fields.
The first matching policy will be executed.
A single policy may be provided without a condition set; if so, it must be the last policy and will be the fallback
in case no conditions are met.
Validation
Min items1
Max items16
Ruleconditional entries without condition must be last
Documentation References (1)
objectRequired
Policy to apply when the condition matches.
Validation
Ruleat least one of the fields in [request response] must be set
Documentation References (1)
object
Request transformation settings.
Validation
Ruleat least one of the fields in [add body metadata remove set] must be set
Documentation References (1)
object[]
Headers to add to the request and what each value
should be set to. If there is already a header with these values then
append the value as an extra entry.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (1)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (1)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (1)
object
Request transformation settings.
Validation
Ruleat least one of the fields in [add body metadata remove set] must be set
Documentation References (15)
string
HTTP body transformation.
Validation
Min length1
Max length16384
Documentation References (3)
string[]
Header names to remove from the request or
response.
Validation
Min items1
Max items16
List typeset
Documentation References (3)
object[]
Headers to set and the values to use.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (10)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (10)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (10)
object
Response transformation settings.
Validation
Ruleat least one of the fields in [add body metadata remove set] must be set
Documentation References (6)
object[]
Headers to add to the request and what each value
should be set to. If there is already a header with these values then
append the value as an extra entry.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (1)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (1)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (1)
string
HTTP body transformation.
Validation
Min length1
Max length16384
Documentation References (1)
string[]
Header names to remove from the request or
response.
Validation
Min items1
Max items16
List typeset
Documentation References (1)
object[]
Headers to set and the values to use.
Validation
Min items1
Max items16
List typemap
List map keysname
Documentation References (5)
stringRequired
The name of the header to add.
Validation
Pattern^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Min length1
Max length256
Rulepseudo-headers must be one of :authority, :method, :path, :scheme, or :status
Documentation References (5)
stringRequired
CEL expression that generates the output value for
the header.
Validation
Min length1
Max length16384
Documentation References (5)
object[]Required
Ancestor resources (usually Gateways) associated with the policy, with the policy's status for each. At most 16 entries; an empty list means the policy is not relevant to any ancestor
Validation
Max items16
List typeatomic
objectRequired
AncestorRef corresponds with a ParentRef in the spec that this
PolicyAncestorStatus struct describes the status of.
string
Group is the group of the referent.
When unspecified, "gateway.networking.k8s.io" is inferred.
To set the core API group (such as for a "Service" kind referent),
Group must be explicitly set to "" (empty string).
Support: Core
Validation
Defaultgateway.networking.k8s.io
Pattern^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Max length253
string
Kind is kind of the referent.
There are two kinds of parent resources with "Core" support:
* Gateway (Gateway conformance profile)
* Service (Mesh conformance profile, ClusterIP Services only)
Support for other resources is Implementation-Specific.
Validation
DefaultGateway
Pattern^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Min length1
Max length63
stringRequired
Name is the name of the referent.
Support: Core
Validation
string
Namespace of the referent. Defaults to the Route's local namespace. Cross-namespace references must be explicitly allowed, for example via ReferenceGrant. Support: Core
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Min length1
Max length63
integer
Port this Route targets on the parent, interpreted per parent kind (for example a Gateway listener port or Service port). Support: Extended
Validation
Formatint32
Minimum1
Maximum65535
string
Name of a section within the target resource, for example a Gateway Listener name or Service port name. Empty references the entire resource. Support: Core
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Min length1
Max length253
object[]Required
Conditions describing the status of the policy for this ancestor
Validation
Min items1
Max items8
List typemap
List map keystype
stringRequired
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
Validation
stringRequired
message is a human readable message indicating details about the transition.
This may be an empty string.
Validation
integer
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance.
Validation
stringRequired
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty.
Validation
Pattern^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
Min length1
Max length1024
stringRequired
status of the condition, one of True, False, Unknown.
Validation
stringRequired
type of condition in CamelCase or in foo.example.com/CamelCase.
Validation
Pattern^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
Max length316
stringRequired
ControllerName is a domain/path string that indicates the name of the
controller that wrote this status. This corresponds with the
controllerName field on GatewayClass.
Example: "example.net/gateway-controller".
The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are
valid Kubernetes names
(https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
Controllers MUST populate this field when writing status. Controllers should ensure that
entries to status populated with their ControllerName are cleaned up when they are no
longer necessary.
Validation
Pattern^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$
Min length1
Max length253
diff --git a/assets/agw-docs/pages/reference/cel/main/cel-context.html b/assets/agw-docs/pages/reference/cel/main/cel-context.html
index 497a31642..ae318645b 100644
--- a/assets/agw-docs/pages/reference/cel/main/cel-context.html
+++ b/assets/agw-docs/pages/reference/cel/main/cel-context.html
@@ -786,7 +786,7 @@
diff --git a/assets/agw-docs/pages/reference/configuration/main/config-schema.html b/assets/agw-docs/pages/reference/configuration/main/config-schema.html
index a0801c398..c3715c3c8 100644
--- a/assets/agw-docs/pages/reference/configuration/main/config-schema.html
+++ b/assets/agw-docs/pages/reference/configuration/main/config-schema.html
@@ -40957,10 +40957,10 @@
diff --git a/content/docs/kubernetes/main/documentation/operations/debug.md b/content/docs/kubernetes/main/documentation/operations/debug.md
index f7af4f058..0e78210b2 100644
--- a/content/docs/kubernetes/main/documentation/operations/debug.md
+++ b/content/docs/kubernetes/main/documentation/operations/debug.md
@@ -4,7 +4,7 @@ weight: 15
description: Debug your agentgateway environment.
---
-Inspect and troubleshoot agentgateway proxies through the admin endpoints and the [`agctl`]({{< link-hextra path="/documentation/operations/agctl" >}}) command-line tool.
+Inspect and troubleshoot agentgateway proxies through the admin endpoints and the [`agctl`]({{< link-hextra path="/documentation/operations/agctl" >}}) command-line tool. If you need help from the community or support, [collect a bug report](#bug-report) that captures the state of your setup.
## Admin endpoints
@@ -366,3 +366,44 @@ Agentgateway includes pprof endpoints to help you investigate CPU and memory iss
> [!NOTE]
> To profile an agentgateway binary that runs on your workstation instead of a proxy pod, use `--local`, such as `agctl proxy profile heap --local`. Note that profiling data is available only when agentgateway runs on Linux. Proxy pods always meet this requirement, but a local macOS or Windows build does not: the CPU profile endpoint is not registered, so `agctl proxy profile cpu` fails with a `404 Not Found` error, and `agctl proxy profile heap` writes a profile that contains no allocation samples.
+
+## Collect a bug report {#bug-report}
+
+When you open an issue or ask for help, attach a snapshot of your setup. The `agctl bug-report` command collects the agentgateway resources, logs, and metrics from your cluster into a single `.tar.gz` archive, so you do not have to gather them one by one.
+
+The archive includes the following information.
+
+* All Gateway API resources and all resources with an agentgateway category, along with the Services, ConfigMaps, Secrets, and Events in every namespace that holds one of those resources or the controller. Secret values are redacted.
+* Logs and metrics from the agentgateway proxy pods and from all pods in the controller namespace.
+
+1. Collect the bug report. By default, `agctl` captures the last 24 hours of logs, up to 5,000 lines per container, and writes `bug-report.tar.gz` to the current directory.
+
+ ```sh
+ agctl bug-report
+ ```
+
+2. Optional: Narrow or extend the report with flags. For example, limit the report to specific namespaces and the last hour of logs. Add `--config-dump` to also capture the `/config_dump` output from each proxy, which includes the routes, backends, and policies that the proxy loaded. The controller namespace is always captured, even if you do not list it with `-n`.
+
+ > [!TIP]
+ > For all flags, see the [`agctl bug-report` reference]({{< link-hextra path="/reference/agctl/agctl-bug-report/" >}}).
+
+ {{< tabs >}}
+ {{% tab name="Replace with your own" %}}
+ ```sh
+ agctl bug-report -n