Skip to content

api-main.md

Latest commit

 

History

History
4265 lines (2240 loc) · 204 KB

api-main.md

File metadata and controls

4265 lines (2240 loc) · 204 KB
Raw

agentgateway.dev/v1alpha1

Resource Types

A2ABackend

A2A backend endpoint.

Appears in:

Field Description Default Validation
host ShortString Hostname or IP address of the A2A backend. MaxLength: 256
MinLength: 1
Required: {}
port integer Port number of the A2A backend. Maximum: 65535
Minimum: 1
Required: {}

AIBackend

AI backend configuration.

Validation:

  • ExactlyOneOf: [provider groups]

Appears in:

Field Description Default Validation
provider LLMProvider Configuration for how to reach the configured LLM
provider.		 ExactlyOneOf: [openai azureopenai azure anthropic gemini vertexai bedrock custom]
Optional: {}
groups PriorityGroup array Groups in priority order, where each group
defines a set of LLM providers. The priority determines the priority of
the backend endpoints chosen.
Note: provider names must be unique across all providers in all priority
groups. Backend policies may target a specific provider by name using
targetRefs[].sectionName.
Example configuration with two priority groups:
groups:
- providers:
- azureopenai:
deploymentName: gpt-4o-mini
apiVersion: 2024-02-15-preview
endpoint: ai-gateway.openai.azure.com
- providers:
- azureopenai:
deploymentName: gpt-4o-mini-2
apiVersion: 2024-02-15-preview
endpoint: ai-gateway-2.openai.azure.com
policies:
auth:
secretRef:
name: azure-secret		 MaxItems: 8
MinItems: 1
Optional: {}

AIPromptEnrichment

Enriches requests sent to the LLM provider by appending and prepending system prompts.

Prompt enrichment allows you to add additional context to the prompt before sending it to the model. Unlike RAG or other dynamic context methods, prompt enrichment is static and is applied to every request.

Note: Some providers, including Anthropic, do not support SYSTEM role messages, and instead have a dedicated system field in the input JSON. In this case, use the defaults setting to set the system field.

The following example prepends a system prompt of Answer all questions in French. and appends Describe the painting as if you were a famous art critic from the 17th century. to each request that is sent to the openai HTTPRoute.

name: openai-opt
namespace: agentgateway-system

spec:

targetRefs:
- group: gateway.networking.k8s.io
  kind: HTTPRoute
  name: openai
ai:
    promptEnrichment:
      prepend:
      - role: SYSTEM
        content: "Answer all questions in French."
      append:
      - role: USER
        content: "Describe the painting as if you were a famous art critic from the 17th century."

Appears in:

Field Description Default Validation
prepend Message array Messages to prepend to the prompt sent by the client. Optional: {}
append Message array Messages to append to the prompt sent by the client. Optional: {}

AIPromptGuard

Prompt guards that block unwanted requests to the LLM provider and mask sensitive data. Prompt guards can be used to reject requests based on the content of the prompt, as well as mask responses based on the content of the response.

This example rejects any request prompts that contain the string "credit card", and masks any credit card numbers in the response.

promptGuard:
	request:
	- response:
	    message: "Rejected due to inappropriate content"
	  regex:
	    action: REJECT
	    matches:
	    - pattern: "credit card"
	      name: "CC"
	response:
	- regex:
	    builtins:
	    - CREDIT_CARD
	    action: MASK

Appears in:

Field Description Default Validation
streaming PromptGuardStreamingMode Apply prompt guards to streaming responses and realtime websocket messages.
Defaults to disabled to preserve streaming throughput unless explicitly enabled.		 Optional: {}
request PromptguardRequest array Prompt guards to apply to requests sent by the client. ExactlyOneOf: [regex webhook openAIModeration bedrockGuardrails googleModelArmor]
MaxItems: 8
MinItems: 1
Optional: {}
response PromptguardResponse array Prompt guards to apply to responses returned by the LLM provider. ExactlyOneOf: [regex webhook bedrockGuardrails googleModelArmor]
MaxItems: 8
MinItems: 1
Optional: {}

APIKeyAuthentication

Validation:

  • ExactlyOneOf: [secretRef secretSelector configMapSelector]

Appears in:

Field Description Default Validation
mode APIKeyAuthenticationMode Validation mode for API key authentication. Strict Optional: {}
secretRef LocalSecretObjectRef Credential source, defaulting to a Kubernetes
Secret, storing a set of API keys. If many keys are needed,
secretSelector or configMapSelector can be used instead.
Note that ConfigMap-backed API keys only support keyHash.
Each entry in the credential data represents one API key. The key is an
arbitrary identifier. The value can either be:
* A string representing the API key.
* A JSON object with key or keyHash, plus optional metadata.
key contains the API key. keyHash contains a hashed API key in
sha256:<hex> format. metadata contains arbitrary JSON metadata
associated with the key, which may be used by other policies. For
example, you may write an authorization policy allowing
apiKey.group == 'sales'.
Example:
apiVersion: v1
kind: Secret
metadata:
name: api-key
stringData:
client1: |
{
"key": "k-123",
"metadata": {
"group": "sales",
"created_at": "2024-10-01T12:00:00Z"
}
}
client2: "k-456"
client3: |
{
"keyHash": "sha256:efa299afb8c12a36e47a790cbbf929caa06d13285950410463fb759af17d0dad",
"metadata": {
"group": "engineering"
}
}		 Optional: {}
secretSelector SecretSelector Selects multiple Kubernetes Secret resources
containing API keys. It is Secret-only; use secretRef for other
credential kinds. If the same key is defined in multiple secrets, the
behavior is undefined.
Each entry in the Secret data represents one API key. The key is an
arbitrary identifier. The value can either be:
* A string representing the API key.
* A JSON object with key or keyHash, plus optional metadata.
key contains the API key. keyHash contains a hashed API key in
sha256:<hex> format. metadata contains arbitrary JSON metadata
associated with the key, which may be used by other policies. For
example, you may write an authorization policy allowing
apiKey.group == 'sales'.
Example:
apiVersion: v1
kind: Secret
metadata:
name: api-key
stringData:
client1: |
{
"key": "k-123",
"metadata": {
"group": "sales",
"created_at": "2024-10-01T12:00:00Z"
}
}
client2: "k-456"		 Optional: {}
configMapSelector ConfigMapSelector Selects multiple Kubernetes ConfigMap resources
containing API keys. It is ConfigMap-only; use secretRef or
secretSelector for Secret-backed credentials. If the same key is
defined in multiple ConfigMaps, the behavior is undefined.
Because ConfigMaps are not confidential, every entry sourced from a
ConfigMap must use keyHash; a raw key value is rejected.
Each entry in the ConfigMap data represents one API key. The key is
an arbitrary identifier. The value must be a JSON object with
keyHash, plus optional metadata. keyHash contains a hashed API
key in sha256:<hex> format. metadata contains arbitrary JSON
metadata associated with the key, which may be used by other
policies. For example, you may write an authorization policy allowing
apiKey.group == 'sales'.
Example:
apiVersion: v1
kind: ConfigMap
metadata:
name: api-key
data:
client1: |
{
"keyHash": "sha256:efa299afb8c12a36e47a790cbbf929caa06d13285950410463fb759af17d0dad",
"metadata": {
"group": "sales"
}
}		 Optional: {}
location AuthorizationExtractionLocation Where API keys are read from.
If omitted, credentials are read from the Authorization header with the Bearer prefix.		 ExactlyOneOf: [header queryParameter cookie expression]
Optional: {}

APIKeyAuthenticationMode

Underlying type: string

Appears in:

Field Description
Strict A valid API Key must be present.
This is the default option.
Optional If an API Key exists, validate it.
Warning: this allows requests without an API Key!
Permissive Requests are never rejected for missing or invalid API keys.
Warning: this allows requests without a valid API key!

AWSGuardrailConfig

Appears in:

Field Description Default Validation
identifier ShortString Identifier of the Guardrail policy to use for the backend. MaxLength: 256
MinLength: 1
Required: {}
version ShortString Version of the Guardrail policy to use for the backend. MaxLength: 256
MinLength: 1
Required: {}

AccessLog

Per-request access log settings.

Appears in:

Field Description Default Validation
filter CELExpression CEL expression used to filter logs. A log
will only be emitted if the expression evaluates to true.		 MaxLength: 16384
MinLength: 1
Optional: {}
attributes LogTracingAttributes Customizations to the key-value pairs that are
logged.		 Optional: {}
otlp OtlpAccessLog OTLP access log export to an
OpenTelemetry-compatible backend.		 Optional: {}

Action

Underlying type: string

Action to take if a regex pattern is matched in a request or response. This setting applies only to request matches. PromptguardResponse matches are always masked by default.

Appears in:

Field Description
Mask Mask the matched data in the request.
Reject Reject the request if the regex matches content in the request.

AgentExtAuthGRPC

Appears in:

Field Description Default Validation
contextExtensions object (keys:string, values:string) Additional arbitrary key-value pairs to
send to the authorization server in the context_extensions field.		 MaxProperties: 64
Optional: {}
requestMetadata object (keys:string, values:CELExpression) Metadata to send to the authorization
server. This maps to the metadata_context.filter_metadata field of the
request, and allows dynamic CEL expressions. If unset, by default the
envoy.filters.http.jwt_authn key is set if the JWT policy is used as
well, for compatibility.		 MaxProperties: 64
Optional: {}

AgentExtAuthHTTP

Appears in:

Field Description Default Validation
path CELExpression 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.		 MaxLength: 16384
MinLength: 1
Optional: {}
redirect CELExpression Optional expression that determines a path to
redirect to on authorization failure. This is useful to redirect to a
sign-in page.		 MaxLength: 16384
MinLength: 1
Optional: {}
body CELExpression Body is a CEL expression that produces the HTTP authorization request body.
Strings and bytes are used directly; other values are JSON-encoded.		 MaxLength: 16384
MinLength: 1
Optional: {}
allowedRequestHeaders ShortString array Additional headers from the client request that
will be sent to the authorization server.
If unset, the following headers are sent by default: Authorization.		 MaxItems: 64
MaxLength: 256
MinLength: 1
Optional: {}
addRequestHeaders object (keys:string, values:CELExpression) Additional headers to add to the
request to the authorization server. While allowedRequestHeaders just
passes the original headers through, addRequestHeaders allows defining
custom headers based on CEL expressions.		 MaxProperties: 64
Optional: {}
allowedResponseHeaders ShortString array Headers from the authorization response that
will be copied into the request to the backend.		 MaxItems: 64
MaxLength: 256
MinLength: 1
Optional: {}
responseMetadata object (keys:string, values:CELExpression) Metadata fields to construct
from the authorization response. These will be included under the
extauthz variable in future CEL expressions. Setting this is useful
for things like logging usernames, without needing to include them as
headers to the backend, as allowedResponseHeaders would.		 MaxProperties: 64
Optional: {}

AgentgatewayBackend

Field Description Default Validation
apiVersion string agentgateway.dev/v1alpha1
kind string AgentgatewayBackend
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		 Optional: {}
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		 Optional: {}
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec AgentgatewayBackendSpec Desired backend configuration. ExactlyOneOf: [ai static dynamicForwardProxy mcp aws a2a]
Required: {}
status AgentgatewayBackendStatus Current backend status. Optional: {}

AgentgatewayBackendSpec

Validation:

  • ExactlyOneOf: [ai static dynamicForwardProxy mcp aws a2a]

Appears in:

Field Description Default Validation
static StaticBackend Static hostname, IP address, or Unix Domain Socket backend. Optional: {}
a2a A2ABackend A2A backend. Optional: {}
ai AIBackend LLM backend. ExactlyOneOf: [provider groups]
Optional: {}
mcp MCPBackend MCP backend. Optional: {}
dynamicForwardProxy DynamicForwardProxyBackend Dynamically sends requests to the destination based on the incoming
request HTTP host header, or TLS SNI for TLS traffic.
Warning: this backend type can send requests to arbitrary destinations. Proper
access controls must be put in place when using this backend type.		 Optional: {}
aws AwsBackend AWS service backend, such as AgentCore. ExactlyOneOf: [agentCore]
Optional: {}
policies BackendFull Policies for communicating with this backend. Policies may also be set
with AgentgatewayPolicy. Backend policies take precedence over policy
resources when they set the same field.		 Optional: {}

AgentgatewayBackendStatus

Current backend status.

Appears in:

Field Description Default Validation
conditions Condition array Current condition state for the backend. MaxItems: 8
Optional: {}

AgentgatewayParameters

Configures dynamic provisioning for the agentgateway data plane. Labels and annotations that apply to all resources may be specified at a higher level; see https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#gatewayinfrastructure

Field Description Default Validation
apiVersion string agentgateway.dev/v1alpha1
kind string AgentgatewayParameters
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		 Optional: {}
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		 Optional: {}
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec AgentgatewayParametersSpec Desired data plane provisioning settings. Required: {}
status AgentgatewayParametersStatus Current status for these provisioning settings. Optional: {}

AgentgatewayParametersConfigs

Appears in:

Field Description Default Validation
workload AgentgatewayParametersWorkload workload selects the Kubernetes workload kind for the managed Gateway
data plane. If unset, Deployment is used.		 Optional: {}
logging AgentgatewayParametersLogging Logging configuration. By default, all logs are set to
info level.		 Optional: {}
rawConfig JSON Raw agentgateway configuration to merge into the generated config file.
This is merged with
configuration derived from typed fields like logging.format, and those
typed fields will take precedence.
Example:
rawConfig:
binds:
- port: 3000
listeners:
- routes:
- policies:
cors:
allowOrigins:
- "*"
allowHeaders:
- mcp-protocol-version
- content-type
- cache-control
backends:
- mcp:
targets:
- name: everything
stdio:
cmd: npx
args: ["@modelcontextprotocol/server-everything"]		 Type: object
Optional: {}
image Image The agentgateway container image. See
https://kubernetes.io/docs/concepts/containers/images
for details.
Default values, which may be overridden individually:
registry: cr.agentgateway.dev
repository: agentgateway
tag:
pullPolicy: <omitted, relying on Kubernetes defaults which depend on the tag>		 Optional: {}
env EnvVar array Container environment variables. These override any existing
values. If you want to delete an environment variable entirely, use
$patch: delete with an overlay instead. Note that
variable
expansion
does apply, but is highly discouraged -- to set dependent environment
variables, you can use $(VAR_NAME), but it's highly discouraged.
$$(VAR_NAME) avoids expansion and results in a literal
$(VAR_NAME).
If SESSION_KEY is specified, it takes precedence over the
controller-managed per-Gateway session key Secret.		 Optional: {}
resources ResourceRequirements Compute resources required by this container. See
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
for details.		 Optional: {}
shutdown ShutdownSpec Shutdown delay configuration. How graceful planned or unplanned data
plane changes happen is in tension with how quickly rollouts of the data
plane complete. How long a data plane pod must wait for shutdown to be
perfectly graceful depends on how you have configured your Gateway
resources.		 Optional: {}
istio IstioSpec Istio integration settings. If enabled, agentgateway can natively connect to Istio-enabled pods with mTLS. Optional: {}
modelCatalog ModelCatalogSpec Model cost catalog sources. Only effective when set on a Gateway-level
AgentgatewayParameters (via Gateway.spec.infrastructure.parametersRef);
ignored on GatewayClass-level parameters because ConfigMap references
are resolved from the Gateway's deployment namespace.		 Optional: {}

AgentgatewayParametersLogging

Appears in:

Field Description Default Validation
level string Logging level in standard RUST_LOG syntax, for example info (the
default), or a comma-separated per-module setting such as
rmcp=warn,hickory_server::server::server_future=off,typespec_client_core::http::policies::logging=warn.		 Optional: {}
format AgentgatewayParametersLoggingFormat Logging output format. Optional: {}

AgentgatewayParametersLoggingFormat

Underlying type: string

The default logging format is text.

Appears in:

Field Description
json
text

AgentgatewayParametersOverlays

Appears in:

Field Description Default Validation
deployment KubernetesResourceOverlay Overrides for the generated
Deployment resource.		 Optional: {}
daemonSet KubernetesResourceOverlay Overrides for the generated
DaemonSet resource.		 Optional: {}
service KubernetesResourceOverlay Overrides for the generated Service
resource.		 Optional: {}
serviceAccount KubernetesResourceOverlay Overrides for the generated
ServiceAccount resource.		 Optional: {}
podDisruptionBudget KubernetesResourceOverlay Creates a PodDisruptionBudget for the
agentgateway proxy. If absent, no PDB is created. If present, a PDB is
created with its selector automatically configured to target the selected
generated workload. The metadata and spec fields from this overlay are
applied to the generated PDB.		 Optional: {}
horizontalPodAutoscaler KubernetesResourceOverlay Creates a HorizontalPodAutoscaler
for Deployment-backed agentgateway proxies. If absent, no HPA is created.
If present, an HPA is created with its scaleTargetRef automatically
configured to target the generated Deployment. The metadata and spec
fields from this overlay are applied to the generated HPA.		 Optional: {}

AgentgatewayParametersSpec

Appears in:

Field Description Default Validation
workload AgentgatewayParametersWorkload workload selects the Kubernetes workload kind for the managed Gateway
data plane. If unset, Deployment is used.		 Optional: {}
logging AgentgatewayParametersLogging Logging configuration. By default, all logs are set to
info level.		 Optional: {}
rawConfig JSON Raw agentgateway configuration to merge into the generated config file.
This is merged with
configuration derived from typed fields like logging.format, and those
typed fields will take precedence.
Example:
rawConfig:
binds:
- port: 3000
listeners:
- routes:
- policies:
cors:
allowOrigins:
- "*"
allowHeaders:
- mcp-protocol-version
- content-type
- cache-control
backends:
- mcp:
targets:
- name: everything
stdio:
cmd: npx
args: ["@modelcontextprotocol/server-everything"]		 Type: object
Optional: {}
image Image The agentgateway container image. See
https://kubernetes.io/docs/concepts/containers/images
for details.
Default values, which may be overridden individually:
registry: cr.agentgateway.dev
repository: agentgateway
tag:
pullPolicy: <omitted, relying on Kubernetes defaults which depend on the tag>		 Optional: {}
env EnvVar array Container environment variables. These override any existing
values. If you want to delete an environment variable entirely, use
$patch: delete with an overlay instead. Note that
variable
expansion
does apply, but is highly discouraged -- to set dependent environment
variables, you can use $(VAR_NAME), but it's highly discouraged.
$$(VAR_NAME) avoids expansion and results in a literal
$(VAR_NAME).
If SESSION_KEY is specified, it takes precedence over the
controller-managed per-Gateway session key Secret.		 Optional: {}
resources ResourceRequirements Compute resources required by this container. See
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
for details.		 Optional: {}
shutdown ShutdownSpec Shutdown delay configuration. How graceful planned or unplanned data
plane changes happen is in tension with how quickly rollouts of the data
plane complete. How long a data plane pod must wait for shutdown to be
perfectly graceful depends on how you have configured your Gateway
resources.		 Optional: {}
istio IstioSpec Istio integration settings. If enabled, agentgateway can natively connect to Istio-enabled pods with mTLS. Optional: {}
modelCatalog ModelCatalogSpec Model cost catalog sources. Only effective when set on a Gateway-level
AgentgatewayParameters (via Gateway.spec.infrastructure.parametersRef);
ignored on GatewayClass-level parameters because ConfigMap references
are resolved from the Gateway's deployment namespace.		 Optional: {}
deployment KubernetesResourceOverlay Overrides for the generated
Deployment resource.		 Optional: {}
daemonSet KubernetesResourceOverlay Overrides for the generated
DaemonSet resource.		 Optional: {}
service KubernetesResourceOverlay Overrides for the generated Service
resource.		 Optional: {}
serviceAccount KubernetesResourceOverlay Overrides for the generated
ServiceAccount resource.		 Optional: {}
podDisruptionBudget KubernetesResourceOverlay Creates a PodDisruptionBudget for the
agentgateway proxy. If absent, no PDB is created. If present, a PDB is
created with its selector automatically configured to target the selected
generated workload. The metadata and spec fields from this overlay are
applied to the generated PDB.		 Optional: {}
horizontalPodAutoscaler KubernetesResourceOverlay Creates a HorizontalPodAutoscaler
for Deployment-backed agentgateway proxies. If absent, no HPA is created.
If present, an HPA is created with its scaleTargetRef automatically
configured to target the generated Deployment. The metadata and spec
fields from this overlay are applied to the generated HPA.		 Optional: {}

AgentgatewayParametersStatus

Current status for these provisioning settings.

Appears in:

AgentgatewayParametersWorkload

AgentgatewayParametersWorkload selects the Kubernetes workload kind used for a managed Gateway data plane.

Appears in:

Field Description Default Validation
kind AgentgatewayParametersWorkloadKind Kind selects the Kubernetes workload kind. When unset, Deployment is used. Optional: {}

AgentgatewayParametersWorkloadKind

Underlying type: string

AgentgatewayParametersWorkloadKind selects the Kubernetes workload kind used for a managed Gateway data plane.

Appears in:

Field Description
Deployment AgentgatewayParametersWorkloadDeployment uses a Deployment for the managed
Gateway data plane.
DaemonSet AgentgatewayParametersWorkloadDaemonSet uses a DaemonSet for the managed
Gateway data plane.

AgentgatewayPolicy

Field Description Default Validation
apiVersion string agentgateway.dev/v1alpha1
kind string AgentgatewayPolicy
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		 Optional: {}
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		 Optional: {}
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec AgentgatewayPolicySpec Desired policy configuration. ExactlyOneOf: [targetRefs targetSelectors]
Required: {}
status PolicyStatus Current policy status. Optional: {}

AgentgatewayPolicySpec

Validation:

  • ExactlyOneOf: [targetRefs targetSelectors]

Appears in:

Field Description Default Validation
targetRefs LocalPolicyTargetReferenceWithSectionName array Target resources to attach the
policy to.		 AtMostOneOf: [sectionName port]
MaxItems: 16
MinItems: 1
Optional: {}
targetSelectors LocalPolicyTargetSelectorWithSectionName array Target selectors used to select resources to attach the policy to. AtMostOneOf: [sectionName port]
MaxItems: 16
MinItems: 1
Optional: {}
strategy PolicyStrategy Policy merge and conflict resolution strategy.
Strategy settings apply to the policy object as a whole. Individual strategy fields may
only be valid for specific policy kinds; for example, inheritance is only valid when this
policy contains traffic settings.		 Optional: {}
frontend Frontend Settings for how to handle incoming traffic.
A frontend policy can only target a Gateway. Listener and
ListenerSet are not valid targets.
When multiple policies are selected for a given request, they are merged on a field-level basis, but not a deep
merge. For example, policy A sets tcp and tls, and policy B sets
tls; the effective policy would be tcp from policy A, and tls from
policy B.		 Optional: {}
traffic Traffic Settings for how to process traffic.
A traffic policy can target a Gateway (optionally, with a
sectionName indicating the listener), ListenerSet, or Route
(optionally, with a sectionName indicating the route rule).
When multiple policies are selected for a given request, they are merged on a field-level basis, but not a deep
merge. Precedence is given to more precise policies: Gateway <
Listener < Route < Route Rule. For example, policy A sets
timeouts and retries, and policy B sets retries; the effective
policy would be timeouts from policy A, and retries from policy B.		 Optional: {}
backend BackendFull Settings for how to connect to destination backends.
A backend policy can target a Gateway (optionally, with a
sectionName indicating the listener), ListenerSet, Route
(optionally, with a sectionName indicating the route rule), or a
Service or Backend (optionally, with a sectionName indicating the
port for Service, or sub-backend for Backend).
Note that a backend policy applies when connecting to a specific destination backend. Targeting a higher level
resource, like Gateway, is just a way to easily apply a policy to a
group of backends.
When multiple policies are selected for a given request, they are merged on a field-level basis, but not a deep
merge. Precedence is given to more precise policies: Gateway <
Listener < Route < Route Rule < Backend or Service. For
example, if a Gateway policy sets tcp and tls, and a Backend
policy sets tls, the effective policy would be tcp from the
Gateway, and tls from the Backend.		 Optional: {}

AnthropicConfig

Settings for the Anthropic LLM provider.

Appears in:

Field Description Default Validation
model ShortString Model name override, such as gpt-4o-mini.
If unset, the model name is taken from the request.		 MaxLength: 256
MinLength: 1
Optional: {}

AttributeAdd

Appears in:

Field Description Default Validation
name ShortString MaxLength: 256
MinLength: 1
Required: {}
expression CELExpression MaxLength: 16384
MinLength: 1
Required: {}

Authorization

Configures CEL-based authorization.

Appears in:

Field Description Default Validation
policy AuthorizationPolicy The authorization rule to evaluate.
* Allow: any matching allow rule allows the request.
* Require: every require rule must match for the request to be allowed.
* Deny: any matching deny rule denies the request.
A CEL expression that fails to evaluate does not match. Prefer Require
for deny-by-default behavior.
If at least one Allow rule is configured, requests are denied unless at
least one allow rule matches.		 Required: {}
action AuthorizationPolicyAction The effect of this rule when it matches.
If unspecified, defaults to Allow.
Require rules are cumulative: all require rules must match.		 Allow Optional: {}

AuthorizationCookieLocation

Appears in:

Field Description Default Validation
name string MaxLength: 256
MinLength: 1
Required: {}

AuthorizationExtractionLocation

Validation:

  • ExactlyOneOf: [header queryParameter cookie expression]

Appears in:

Field Description Default Validation
header AuthorizationHeaderLocation Optional: {}
queryParameter AuthorizationQueryParameterLocation Optional: {}
cookie AuthorizationCookieLocation Optional: {}
expression CELExpression CEL expression that extracts the credential from the request. MaxLength: 16384
MinLength: 1
Optional: {}

AuthorizationHeaderLocation

Appears in:

Field Description Default Validation
name HTTPHeaderName MaxLength: 256
MinLength: 1
Pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Required: {}
prefix string MaxLength: 256
MinLength: 1
Optional: {}

AuthorizationLocation

Validation:

  • ExactlyOneOf: [header queryParameter cookie]

Appears in:

Field Description Default Validation
header AuthorizationHeaderLocation Optional: {}
queryParameter AuthorizationQueryParameterLocation Optional: {}
cookie AuthorizationCookieLocation Optional: {}

AuthorizationLocationFields

Appears in:

Field Description Default Validation
header AuthorizationHeaderLocation Optional: {}
queryParameter AuthorizationQueryParameterLocation Optional: {}
cookie AuthorizationCookieLocation Optional: {}

AuthorizationPolicy

Defines CEL expressions for a single authorization rule.

Appears in:

Field Description Default Validation
matchExpressions CELExpression array CEL expressions that must all evaluate to true for the rule to match. MaxItems: 256
MaxLength: 16384
MinItems: 1
MinLength: 1
Required: {}

AuthorizationPolicyAction

Underlying type: string

AuthorizationPolicyAction defines the action to take when the RBACPolicies matches.

Appears in:

Field Description
Allow AuthorizationPolicyActionAllow defines the action to take when the
RBACPolicies matches.
Deny AuthorizationPolicyActionDeny denies the action to take when the
RBACPolicies matches.
Require AuthorizationPolicyActionRequire requires the action to take when the RBACPolicies matches.

AuthorizationQueryParameterLocation

Appears in:

Field Description Default Validation
name string MaxLength: 256
MinLength: 1
Required: {}

AwsAgentCoreBackend

Configures Amazon Bedrock AgentCore.

Appears in:

Field Description Default Validation
agentRuntimeArn string ARN of the AgentCore runtime. Required: {}
qualifier string Alias or version qualifier. Optional: {}

AwsAssumeRole

AWS STS AssumeRole settings for backend authentication.

Validation:

  • AtMostOneOf: [sessionName sessionNameExpression]

Appears in:

Field Description Default Validation
roleArn string AWS IAM role ARN to assume. MinLength: 1
Pattern: ^arn:aws[a-z-]*:iam::[0-9]\{12\}:role/.+$
Required: {}
sessionName string SessionName is a custom session name (RoleSessionName) for CloudTrail and
Cost & Usage Report attribution. If unset, AWS generates a random name.		 Pattern: ^[\w+=,.@-]\{2,64\}$
Optional: {}
sessionNameExpression CELExpression SessionNameExpression is a CEL expression evaluated against each request
to produce the session name (RoleSessionName), for example jwt.sub or
request.headers["x-team"]. If the expression does not produce a valid
session name at request time, the request is rejected.		 MaxLength: 16384
MinLength: 1
Optional: {}
tags AwsSessionTag array Tags are session tags passed to STS AssumeRole. Once activated as cost
allocation tags, they appear in the AWS Cost & Usage Report for cost
attribution. STS allows at most 50 session tags per role session.		 MaxItems: 50
Optional: {}

AwsAuth

AWS authentication settings for the backend.

Appears in:

Field Description Default Validation
secretRef LocalSecretObjectRef Credential source, defaulting to a Kubernetes
Secret, containing the AWS credentials. When using the default Secret
resolver, the Secret must have keys accessKey, secretKey, and
optionally sessionToken.		 Optional: {}
assumeRole AwsAssumeRole AWS STS AssumeRole settings to use before signing backend requests.
Ambient AWS credentials are used as the source credentials for STS.		 AtMostOneOf: [sessionName sessionNameExpression]
Optional: {}
serviceName ShortString AWS SigV4 signing service name, for example
bedrock, bedrock-agentcore, or execute-api). If unset, typed AWS
backends may provide this automatically.		 MaxLength: 256
MinLength: 1
Optional: {}

AwsBackend

Configures an AWS service backend.

Validation:

  • ExactlyOneOf: [agentCore]

Appears in:

Field Description Default Validation
agentCore AwsAgentCoreBackend Amazon Bedrock AgentCore backend settings. Optional: {}

AwsSessionTag

AwsSessionTag is an AWS STS session tag passed to AssumeRole for cost attribution. Exactly one of value and expression must be set.

Appears in:

Field Description Default Validation
key string Key is the tag key. MaxLength: 128
MinLength: 1
Required: {}
value string Value is a static tag value. MaxLength: 256
Optional: {}
expression CELExpression Expression is a CEL expression evaluated against each request to produce
the tag value, for example jwt.sub or request.headers["x-app"]. If the
expression does not produce a valid tag value at request time, the request
is rejected.		 MaxLength: 16384
MinLength: 1
Optional: {}

AzureAuth

AzureAuth configures authentication to Azure services. At most one explicit credential source may be set. When none is set, authentication is implicit: the method is automatically detected from the environment, which resolves to Workload Identity when running on Kubernetes.

Validation:

  • AtMostOneOf: [secretRef managedIdentity workloadIdentity]

Appears in:

Field Description Default Validation
secretRef LocalSecretObjectRef Credential source, defaulting to a Kubernetes
Secret, containing the Azure credentials. When using the default Secret
resolver, the Secret must have keys clientID, tenantID, and
clientSecret.		 Optional: {}
managedIdentity AzureManagedIdentity Managed identity authentication settings. Optional: {}
workloadIdentity AzureWorkloadIdentity Workload identity authentication settings. Uses the federated token
projected into the data plane pod (via the AZURE_FEDERATED_TOKEN_FILE,
AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_AUTHORITY_HOST
environment variables) to authenticate. This is the recommended method
when running on Azure Kubernetes Service (AKS) with Workload Identity
enabled.		 Optional: {}

AzureConfig

Settings for Azure AI backends, supporting both Azure OpenAI and Azure AI Foundry.

Appears in:

Field Description Default Validation
resourceName ShortString The Azure resource name used to construct the endpoint host.
For OpenAI: {resourceName}.openai.azure.com
For Foundry: {resourceName}.services.ai.azure.com
Note: when the Azure portal "Foundry legacy" template was used, the
generated resource name may end in "-resource" (e.g. "myproject-resource");
that suffix is part of the resource name as the user configured it, not
part of the hostname suffix agentgateway should append.		 MaxLength: 256
MinLength: 1
Required: {}
resourceType AzureResourceType The type of Azure endpoint. Determines the host suffix. Required: {}
model ShortString Model name override, such as gpt-4o-mini.
If unset, the model name is taken from the request.		 MaxLength: 256
MinLength: 1
Optional: {}
apiVersion TinyString The version of the Azure OpenAI API to use.
If unset, defaults to v1.		 MaxLength: 64
MinLength: 1
Optional: {}
projectName ShortString The Foundry project name, required when resourceType is Foundry.
Used to construct paths: /api/projects/{projectName}/openai/v1/...		 MaxLength: 256
MinLength: 1
Optional: {}

AzureManagedIdentity

Appears in:

Field Description Default Validation
clientId string Required: {}
objectId string Required: {}
resourceId string Required: {}

AzureOpenAIConfig

Settings for the Azure OpenAI LLM provider.

Appears in:

Field Description Default Validation
endpoint ShortString The endpoint for the Azure OpenAI API to use, such as my-endpoint.openai.azure.com.
If the scheme is included, it is stripped.		 MaxLength: 256
MinLength: 1
Required: {}
deploymentName ShortString The name of the Azure OpenAI model deployment to use.
For more information, see the Azure OpenAI model docs.
This is required if apiVersion is not v1. For v1, the model can be
set in the request.		 MaxLength: 256
MinLength: 1
Optional: {}
apiVersion TinyString The version of the Azure OpenAI API to use.
For more information, see the Azure OpenAI API version reference.
If unset, defaults to v1.		 MaxLength: 64
MinLength: 1
Optional: {}

AzureResourceType

Underlying type: string

Type of Azure endpoint.

Appears in:

Field Description
OpenAI AzureResourceTypeOpenAI uses the Azure OpenAI endpoint: {resourceName}.openai.azure.com
Foundry AzureResourceTypeFoundry uses the Azure AI Foundry endpoint: {resourceName}.services.ai.azure.com

AzureWorkloadIdentity

AzureWorkloadIdentity configures Azure Workload Identity authentication.

Appears in:

BackendAI

Appears in:

Field Description Default Validation
prompt AIPromptEnrichment Enriches requests sent to the LLM provider by appending and prepending system prompts. This can be configured only for
LLM providers that use the CHAT or CHAT_STREAMING API route type.		 Optional: {}
promptGuard AIPromptGuard Guardrails for LLM requests and responses. Optional: {}
defaults FieldDefault array Defaults to merge with user input fields. If the field is already set, the field in the request is used. MaxItems: 64
MinItems: 1
Optional: {}
overrides FieldDefault array Overrides to merge with user input fields. If the field is already set, the field is overwritten. MaxItems: 64
MinItems: 1
Optional: {}
transformations FieldTransformation array CEL transformations to compute and set fields in the request body.
The expression result overwrites any existing value for that field.
This has a higher priority than overrides if both are set for the same
key.		 MaxItems: 64
MinItems: 1
Optional: {}
modelAliases object (keys:string, values:string) Maps friendly model names to actual provider model names.
Example: \{"fast": "gpt-3.5-turbo", "smart": "gpt-4-turbo"\}.
Note: This field is only applicable when using the agentgateway data plane.		 MaxProperties: 64
Optional: {}
promptCaching PromptCachingConfig Automatic prompt caching for supported
providers, currently AWS Bedrock.
Reduces API costs by caching static content like system prompts and tool definitions.
Only applicable for Bedrock Claude 3+ and Nova models.		 Optional: {}
routes object (keys:string, values:RouteType) Rules for identifying the type of traffic to handle.
The keys are URL path suffixes matched using ends-with comparison, for
example "/v1/chat/completions".
The special * wildcard matches any path.
If not specified, all traffic defaults to completions type.		 Optional: {}

BackendAuth

Validation:

  • ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange]

Appears in:

Field Description Default Validation
key string Inline key to use as the value of the
Authorization header. This option is the least secure; usage of a
Secret is preferred.		 MaxLength: 2048
Optional: {}
secretRef LocalSecretKeyRef Credential source, defaulting to a Kubernetes
Secret, storing the key to use as the authorization value. When using
the default Secret resolver, this must be stored in the Authorization
key by default; override via secretRef.key. A Bearer prefix on the
stored value is stripped only when reading the default Authorization
key.		 Optional: {}
passthrough BackendAuthPassthrough Passes through an existing token that has been sent by the
client and validated. Other policies, like JWT and API key
authentication, will strip the original client credentials. Passthrough backend authentication
causes the original token to be added back into the request. If there are no client authentication policies on the
request, the original token would be unchanged, so this would have no effect.		 Optional: {}
aws AwsAuth Explicit AWS authentication method for the backend.
When omitted, default AWS SDK credential discovery is used.		 Optional: {}
azure AzureAuth Azure authentication method for the backend. AtMostOneOf: [secretRef managedIdentity workloadIdentity]
Optional: {}
gcp GcpAuth Google authentication method for the backend.
When omitted, default Google credential discovery is used.		 Optional: {}
oauthTokenExchange OAuthTokenExchange OAuth 2.0 token exchange (RFC 8693) / jwt-bearer (RFC 7523) authentication. Optional: {}
location AuthorizationLocation Where backend credentials are inserted.
If omitted, credentials are written to the Authorization header with the Bearer prefix.
This applies to key, secretRef, and passthrough.		 ExactlyOneOf: [header queryParameter cookie]
Optional: {}

BackendAuthPassthrough

Appears in:

BackendEviction

Settings for evicting unhealthy backends.

Appears in:

Field Description Default Validation
duration Duration Base time a backend should be evicted after being marked unhealthy.
Subsequent evictions use multiplicative backoff (duration * times_evicted).
If all endpoints are evicted, the load balancer falls back to returning evicted endpoints
rather than failing entirely.
If unset, defaults to 3s.		 3s Optional: {}
restoreHealth integer Health score from 0 to 100 assigned to a backend when it returns from eviction.
For gradual recovery, set below 100; for full recovery immediately, set 100.
If unset, the backend resumes with the health it had when evicted.		 Maximum: 100
Minimum: 0
Optional: {}
consecutiveFailures integer Number of consecutive unhealthy responses required before the backend is evicted.
For example, a value of 5 means the backend must receive 5 unhealthy responses in a row before being evicted.
When both consecutiveFailures and healthThreshold are set, the backend is evicted when either condition is met.
When neither is set, a single unhealthy response can trigger eviction.		 Minimum: 0
Optional: {}
healthThreshold integer EWMA health score threshold, expressed as 0 to 100.
When set, a backend is only evicted if its computed health drops below this value after an unhealthy response.
For example, 50 means the backend is evicted when its EWMA health falls below 50% following failures.
Unlike consecutiveFailures (which counts consecutive failures), this uses a sliding-window average
so a single success in a stream of failures can delay eviction.
When both consecutiveFailures and healthThreshold are set, the backend is evicted when either condition is met.
When neither is set, a single unhealthy response triggers eviction.		 Maximum: 100
Minimum: 0
Optional: {}

BackendFull

Appears in:

Field Description Default Validation
tcp BackendTCP Settings for managing TCP connections to the backend. Optional: {}
tls BackendTLS Settings for managing TLS connections to the backend.
If this field is set, TLS will be initiated to the backend; the system trusted CA certificates will be used to
validate the server, and the SNI will automatically be set based on the destination.		 AtMostOneOf: [verifySubjectAltNames insecureSkipVerify]
Optional: {}
http BackendHTTP Settings for managing HTTP requests to the backend. Optional: {}
tunnel BackendTunnel Settings for managing tunnel connections, with behavior like HTTPS_PROXY, to the backend. Optional: {}
auth BackendAuth Settings for managing authentication to the backend. ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange]
Optional: {}
ai BackendAI Settings for AI workloads. This is only applicable when
connecting to a Backend of type ai.		 Optional: {}
mcp BackendMCP Settings for MCP workloads. This is only applicable when
connecting to a Backend of type mcp.		 Optional: {}
transformation Transformation Mutates and transforms requests and responses sent to and from the backend. Optional: {}
health Health Settings for passive and active health checking. Optional: {}
extAuth ExtAuth External authentication configuration for requests
sent to this backend.		 Optional: {}

BackendHTTP

Appears in:

Field Description Default Validation
version HTTPVersion HTTP protocol version to use when connecting to
the backend.
If not specified, the version is automatically determined:
* Service types can specify it with appProtocol on the Service
port.
* If traffic is identified as gRPC, HTTP2 is used.
* If the incoming traffic was plaintext HTTP, the original protocol will
be used.
* If the incoming traffic was HTTPS, HTTP1 will be used. This is
because most clients will transparently upgrade HTTPS traffic to
HTTP2, even if the backend doesn't support it.		 Optional: {}
requestTimeout Duration Deadline for receiving a response from the backend. Optional: {}

BackendMCP

Appears in:

Field Description Default Validation
authorization Authorization MCP backend authorization. Unlike authorization at the HTTP level, which rejects
unauthorized requests with a 403 error, this policy works at the
MCPBackend level.
List operations, such as list_tools, will have each item evaluated.
Items that do not meet the rule will be filtered.
Get or call operations, such as call_tool, will evaluate the specific
item and reject requests that do not meet the rule.		 Optional: {}
authentication MCPAuthentication MCP backend-specific authentication rules.
This field is deprecated; prefer to use traffic policy jwtAuthentication.mcp, which ensures authentication runs before
other policies such as transformation and rate limiting.		 Optional: {}
guardrails MCPGuardrails guardrails routes selected JSON-RPC methods through a remote policy server. Optional: {}

BackendSimple

Appears in:

Field Description Default Validation
tcp BackendTCP Settings for managing TCP connections to the backend. Optional: {}
tls BackendTLS Settings for managing TLS connections to the backend.
If this field is set, TLS will be initiated to the backend; the system trusted CA certificates will be used to
validate the server, and the SNI will automatically be set based on the destination.		 AtMostOneOf: [verifySubjectAltNames insecureSkipVerify]
Optional: {}
http BackendHTTP Settings for managing HTTP requests to the backend. Optional: {}
tunnel BackendTunnel Settings for managing tunnel connections, with behavior like HTTPS_PROXY, to the backend. Optional: {}
auth BackendAuth Settings for managing authentication to the backend. ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange]
Optional: {}

BackendTCP

Appears in:

Field Description Default Validation
keepalive Keepalive Settings for enabling TCP keepalives on the
connection.		 Optional: {}
connectTimeout Duration Deadline for establishing a connection to
the destination.		 Optional: {}

BackendTLS

Validation:

  • AtMostOneOf: [verifySubjectAltNames insecureSkipVerify]

Appears in:

Field Description Default Validation
mtlsCertificateRef LocalSecretObjectRef array Enables mutual TLS to the backend, using the
specified key (tls.key) and cert (tls.crt) from the referenced
credential source, defaulting to a Kubernetes Secret.
An optional ca.cert field, if present, will be used to verify the
server certificate. If caCertificateRefs is also specified, the
caCertificateRefs field takes priority.
If unspecified, no client certificate will be used.		 MaxItems: 1
Optional: {}
caCertificateRefs LocalObjectReference array CA certificate ConfigMap to use to
verify the server certificate.
If unset, the system's trusted certificates are used.		 MaxItems: 1
Optional: {}
insecureSkipVerify InsecureTLSMode Originates TLS but skips verification of the backend's certificate.
WARNING: This is an insecure option that should only be used if the risks are understood.
There are two modes:
* All disables all TLS verification.
* Hostname verifies the CA certificate is trusted, but ignores any
mismatch of hostname or SANs. Note that this method is still insecure;
prefer setting verifySubjectAltNames to customize the valid hostnames
if possible.		 Optional: {}
sni SNI Server Name Indicator (SNI) to use in the TLS
handshake. If unset, the SNI is automatically set based on the
destination hostname.		 MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Optional: {}
verifySubjectAltNames ShortString array Subject Alternative Names (SAN)
to verify in the server certificate.
If not present, the destination hostname is automatically used.		 MaxItems: 16
MaxLength: 256
MinItems: 1
MinLength: 1
Optional: {}
alpnProtocols TinyString Application-Layer Protocol Negotiation (ALPN)
value to use in the TLS handshake.
If not present, defaults to ["h2", "http/1.1"].		 MaxItems: 16
MaxLength: 64
MinItems: 1
MinLength: 1
Optional: {}
keyExchangeGroups KeyExchangeGroup array Ordered list of key exchange groups for a TLS connection.
For example: X25519_MLKEM768,X25519.		 Optional: {}

BackendTunnel

Appears in:

Field Description Default Validation
backendRef BackendObjectReference Proxy server to reach.
Supported types: Service and Backend.		 Required: {}

BackendWithAI

Appears in:

Field Description Default Validation
tcp BackendTCP Settings for managing TCP connections to the backend. Optional: {}
tls BackendTLS Settings for managing TLS connections to the backend.
If this field is set, TLS will be initiated to the backend; the system trusted CA certificates will be used to
validate the server, and the SNI will automatically be set based on the destination.		 AtMostOneOf: [verifySubjectAltNames insecureSkipVerify]
Optional: {}
http BackendHTTP Settings for managing HTTP requests to the backend. Optional: {}
tunnel BackendTunnel Settings for managing tunnel connections, with behavior like HTTPS_PROXY, to the backend. Optional: {}
auth BackendAuth Settings for managing authentication to the backend. ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange]
Optional: {}
ai BackendAI Settings for AI workloads. This is only applicable when
connecting to a Backend of type ai.		 Optional: {}
transformation Transformation Mutates and transforms requests and responses sent to and from the backend. Optional: {}
health Health Settings for passive and active health checking. Optional: {}

BasicAuthentication

Validation:

  • ExactlyOneOf: [users secretRef]

Appears in:

Field Description Default Validation
mode BasicAuthenticationMode Validation mode for basic authentication. Strict Optional: {}
realm string realm value to return in the WWW-Authenticate
header for failed authentication requests. If unset, Restricted will
be used.		 Optional: {}
users string array Inline list of username and password pairs that will
be accepted. Each entry represents one line of the htpasswd format:
https://httpd.apache.org/docs/2.4/programs/htpasswd.html.
Note: passwords should be the hash of the password, not the raw password. Use the htpasswd or similar commands
to generate a hash. MD5, bcrypt, crypt, and SHA-1 are supported.
Example:
users:
- "user1:$apr1$ivPt0D4C$DmRhnewfHRSrb3DQC.WHC."
- "user2:$2y$05$r3J4d3VepzFkedkd/q1vI.pBYIpSqjfN0qOARV3ScUHysatnS0cL2"		 MaxItems: 256
MinItems: 1
Optional: {}
secretRef LocalSecretKeyRef Credential source, defaulting to a Kubernetes
Secret, storing the .htaccess file. When using the default Secret
resolver, the Secret must have a key named .htaccess by default;
override via secretRef.key. The value should contain the complete
.htaccess file.
Note: passwords should be the hash of the password, not the raw password. Use the htpasswd or similar commands
to generate a hash. MD5, bcrypt, crypt, and SHA-1 are supported.
Example:
apiVersion: v1
kind: Secret
metadata:
name: basic-auth
stringData:
.htaccess: |
alice:$apr1$3zSE0Abt$IuETi4l5yO87MuOrbSE4V.
bob:$apr1$Ukb5LgRD$EPY2lIfY.A54jzLELNIId/		 Optional: {}
location AuthorizationExtractionLocation Where Basic credentials are read from.
If omitted, credentials are read from the Authorization header with the Basic prefix.		 ExactlyOneOf: [header queryParameter cookie expression]
Optional: {}

BasicAuthenticationMode

Underlying type: string

Appears in:

Field Description
Strict A valid username and password must be present.
This is the default option.
Optional If a username and password exists, validate it.
Warning: this allows requests without a username!

BedrockConfig

Appears in:

Field Description Default Validation
region string AWS region to use for the backend.
Defaults to us-east-1 if not specified.		 us-east-1 MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9-]+$
Optional: {}
model ShortString Model name override, such as gpt-4o-mini.
If unset, the model name is taken from the request.		 MaxLength: 256
MinLength: 1
Optional: {}
guardrail AWSGuardrailConfig Guardrail policy to use for the backend. See
https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html.
If not specified, the AWS Guardrail policy will not be used.		 Optional: {}

BedrockGuardrails

Appears in:

Field Description Default Validation
identifier ShortString Identifier of the Guardrail policy to use for the backend. MaxLength: 256
MinLength: 1
Required: {}
version ShortString Version of the Guardrail policy to use for the backend. MaxLength: 256
MinLength: 1
Required: {}
region ShortString AWS region where the guardrail is deployed, for example
us-west-2).		 MaxLength: 256
MinLength: 1
Required: {}
policies BackendSimple Policies for communicating with AWS Bedrock Guardrails. Optional: {}

BodySendMode

Underlying type: string

How HTTP bodies are delivered to the external processor.

Appears in:

Field Description
None BodySendModeNone does not send the body to the external processor.
Buffered BodySendModeBuffered buffers the full body before sending it to the
external processor. It returns an error if the body exceeds 8KB.
BufferedPartial BodySendModeBufferedPartial buffers up to 8KB. If the body exceeds that
limit, it sends the buffered prefix instead of returning an error.
FullDuplexStreamed BodySendModeFullDuplexStreamed streams the body to the external processor.

Buffer

Appears in:

Field Description Default Validation
request BufferBody Request body buffering settings. Optional: {}
response BufferBody Response body buffering settings. Optional: {}

BufferBody

Appears in:

Field Description Default Validation
maxBytes ByteSize Maximum number of bytes to buffer from the request or response body.
If unset, defaults to the global proxy setting, which defaults to 2Mi.		 MaxLength: 32
MinLength: 1
Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
XIntOrString: {}
Optional: {}
failureMode FailureMode Behavior when the request or response body exceeds the buffer limit.
If unset, defaults to FailClosed, returning 413 for oversized requests and 502 for oversized responses.		 Optional: {}

BuiltIn

Underlying type: string

Built-in regex patterns for specific types of strings in prompts. For example, if you specify CreditCard, any credit card numbers in the request or response are matched.

Appears in:

Field Description
Ssn Default regex matching for Social Security numbers.
CreditCard Default regex matching for credit card numbers.
PhoneNumber Default regex matching for phone numbers.
Email Default regex matching for email addresses.
CaSin Default regex matching for Canadian Social Insurance Numbers.

ByteSize

Byte quantity that must fit in the data plane size limit.

Validation:

  • MaxLength: 32
  • MinLength: 1
  • Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
  • XIntOrString: {}

Appears in:

CELExpression

Underlying type: string

A Common Expression Language (CEL) expression.

Validation:

  • MaxLength: 16384
  • MinLength: 1

Appears in:

CORS

Appears in:

CSRF

Appears in:

Field Description Default Validation
additionalOrigins ShortString array Additional source origins that will be
allowed in addition to the destination origin. The Origin consists of
a scheme and a host, with an optional port, and takes the form
<scheme>://<host>(:<port>).		 MaxItems: 16
MaxLength: 256
MinItems: 1
MinLength: 1
Optional: {}

CipherSuite

Underlying type: string

Appears in:

Field Description
TLS13_AES_256_GCM_SHA384 TLS 1.3 cipher suites
TLS13_AES_128_GCM_SHA256
TLS13_CHACHA20_POLY1305_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS 1.2 cipher suites
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

ConfigMapSelector

Appears in:

Field Description Default Validation
matchLabels object (keys:string, values:string) Labels that must be present on each selected ConfigMap. Required: {}

CustomProvider

Provider with explicit API format support and an explicit target. Use this for local, self-hosted, or OpenAI-compatible providers whose supported request/response formats are not fully described by the managed provider types.

Appears in:

Field Description Default Validation
backendRef LocalBackendObjectReference Kubernetes backend that serves this provider.
backendRef may target only a namespace-local Service or InferencePool.
If unset, host and port must be set on the parent provider.		 Optional: {}
model ShortString Model name override, such as gpt-oss.
If unset, the model name is taken from the request.		 MaxLength: 256
MinLength: 1
Optional: {}
formats ProviderFormatConfig array Provider-native API formats this provider supports. MaxItems: 6
MinItems: 1
Required: {}

CustomResponse

Response to return to the client if request content is matched against a regex pattern and the action is REJECT.

Appears in:

Field Description Default Validation
message string Custom response message to return to the client. If not specified, defaults to
The request was rejected due to inappropriate content.		 The request was rejected due to inappropriate content Optional: {}
statusCode integer Status code to return to the client. Defaults to 403. 403 Maximum: 599
Minimum: 200
Optional: {}

DirectResponse

Direct response policy.

Appears in:

Field Description Default Validation
status integer HTTP status code to return. Maximum: 599
Minimum: 200
Optional: {}
body string Content to return in the HTTP response body.
The maximum length of the body is restricted to prevent excessively large responses.
If this field is omitted, no body is included in the response.		 MaxLength: 4096
MinLength: 1
Optional: {}
bodyExpression CELExpression CEL expression that produces the HTTP response body.
Strings and bytes are written directly; other values are serialized as JSON.
If this field is omitted, no expression body is included in the response.		 MaxLength: 16384
MinLength: 1
Optional: {}
headers DirectResponseHeader array Response headers to set on the direct response. MaxItems: 16
MinItems: 1
Optional: {}

DirectResponseConditional

Appears in:

Field Description Default Validation
condition CELExpression CEL expression that must evaluate to true for this policy to execute. MaxLength: 16384
MinLength: 1
Optional: {}
policy DirectResponse Policy to apply when the condition matches. Required: {}

DirectResponseHeader

Appears in:

Field Description Default Validation
name HTTPHeaderName The name of the header to set. MaxLength: 256
MinLength: 1
Pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Required: {}
value CELExpression CEL expression that generates the output value for
the header.		 MaxLength: 16384
MinLength: 1
Required: {}

DirectResponseOrConditional

Appears in:

Field Description Default Validation
status integer HTTP status code to return. Maximum: 599
Minimum: 200
Optional: {}
body string Content to return in the HTTP response body.
The maximum length of the body is restricted to prevent excessively large responses.
If this field is omitted, no body is included in the response.		 MaxLength: 4096
MinLength: 1
Optional: {}
bodyExpression CELExpression CEL expression that produces the HTTP response body.
Strings and bytes are written directly; other values are serialized as JSON.
If this field is omitted, no expression body is included in the response.		 MaxLength: 16384
MinLength: 1
Optional: {}
headers DirectResponseHeader array Response headers to set on the direct response. MaxItems: 16
MinItems: 1
Optional: {}
conditional DirectResponseConditional array Conditional policy execution. Set this or the top-level directResponse 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.		 MaxItems: 16
MinItems: 1
Optional: {}

DynamicForwardProxyBackend

Appears in:

ExtAuth

Appears in:

Field Description Default Validation
backendRef BackendObjectReference External Authorization server to reach.
Supported types: Service and Backend.		 Optional: {}
failureMode FailureMode Behavior when the external authorization service is
unavailable or returns an error. "FailOpen" allows the request to continue.
"FailClosed" (default) denies the request.		 Optional: {}
grpc AgentExtAuthGRPC Uses the gRPC External Authorization
protocol should be used.		 Optional: {}
http AgentExtAuthHTTP 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.		 Optional: {}
forwardBody ExtAuthBody Whether to include the HTTP body in the authorization request.
If enabled, the request body will be buffered.		 Optional: {}
cache ExtAuthCache 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.		 Optional: {}

ExtAuthBody

Appears in:

Field Description Default Validation
maxSize ByteSize Largest body, in bytes, that will be buffered
and sent to the authorization server. If the body size is larger than
maxSize, then the request will be rejected with a response.		 MaxLength: 32
MinLength: 1
Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
XIntOrString: {}
Required: {}

ExtAuthCache

Appears in:

Field Description Default Validation
key CELExpression array Ordered list of CEL expressions evaluated against the request
to construct the cache key.		 MaxItems: 16
MaxLength: 16384
MinItems: 1
MinLength: 1
Required: {}
ttl CELExpression 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.		 MaxLength: 16384
MinLength: 1
Required: {}
maxEntries integer Maximum number of authorization results to keep in
the cache. If unset, this defaults to 10000.		 Minimum: 1
Optional: {}

ExtAuthConditional

Appears in:

Field Description Default Validation
condition CELExpression CEL expression that must evaluate to true for this policy to execute. MaxLength: 16384
MinLength: 1
Optional: {}
policy ExtAuth Policy to apply when the condition matches. Required: {}

ExtAuthOrConditional

Appears in:

Field Description Default Validation
backendRef BackendObjectReference External Authorization server to reach.
Supported types: Service and Backend.		 Optional: {}
failureMode FailureMode Behavior when the external authorization service is
unavailable or returns an error. "FailOpen" allows the request to continue.
"FailClosed" (default) denies the request.		 Optional: {}
grpc AgentExtAuthGRPC Uses the gRPC External Authorization
protocol should be used.		 Optional: {}
http AgentExtAuthHTTP 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.		 Optional: {}
forwardBody ExtAuthBody Whether to include the HTTP body in the authorization request.
If enabled, the request body will be buffered.		 Optional: {}
cache ExtAuthCache 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.		 Optional: {}
conditional ExtAuthConditional array 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.		 MaxItems: 16
MinItems: 1
Optional: {}

ExtProc

Appears in:

Field Description Default Validation
backendRef BackendObjectReference External Processor server to reach.
Supported types: Service and Backend.		 Optional: {}
failureMode FailureMode 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.		 Optional: {}
processingOptions ProcessingOptions How request and response phases are sent to ext_proc. Optional: {}
metadataContext object (keys:string, values:map[string]CELExpression) 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.		 MaxProperties: 64
Optional: {}
requestAttributes object (keys:string, values:CELExpression) Request attributes to send to the external processor in the request
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per request.		 MaxProperties: 64
Optional: {}
responseAttributes object (keys:string, values:CELExpression) Response attributes to send to the external processor in the response
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per response.		 MaxProperties: 64
Optional: {}

ExtProcConditional

Appears in:

Field Description Default Validation
condition CELExpression CEL expression that must evaluate to true for this policy to execute. MaxLength: 16384
MinLength: 1
Optional: {}
policy ExtProc Policy to apply when the condition matches. Required: {}

ExtProcOrConditional

Appears in:

Field Description Default Validation
backendRef BackendObjectReference External Processor server to reach.
Supported types: Service and Backend.		 Optional: {}
failureMode FailureMode 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.		 Optional: {}
processingOptions ProcessingOptions How request and response phases are sent to ext_proc. Optional: {}
metadataContext object (keys:string, values:map[string]CELExpression) 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.		 MaxProperties: 64
Optional: {}
requestAttributes object (keys:string, values:CELExpression) Request attributes to send to the external processor in the request
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per request.		 MaxProperties: 64
Optional: {}
responseAttributes object (keys:string, values:CELExpression) Response attributes to send to the external processor in the response
attributes field of the ProcessingRequest. Values are CEL expressions
evaluated per response.		 MaxProperties: 64
Optional: {}
conditional ExtProcConditional array 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.		 MaxItems: 16
MinItems: 1
Optional: {}

FailureMode

Underlying type: string

Appears in:

Field Description
FailClosed FailClosed fails the entire MCP session if any target fails.
FailOpen FailOpen skips failed targets and continues serving from healthy ones.

FieldDefault

Default value for a field in the JSON request body sent to the LLM provider. These defaults are merged with the user-provided request to ensure missing fields are populated.

User input fields here refer to the fields in the JSON request body that a client sends when making a request to the LLM provider. Defaults set here do not override those user-provided values unless you explicitly set override to true.

Example: Setting a default system field for Anthropic, which does not support system role messages:

defaults:
  - field: "system"
    value: "answer all questions in French"

Example: Setting a default temperature and overriding max_tokens:

defaults:
  - field: "temperature"
    value: "0.5"
  - field: "max_tokens"
    value: "100"
    override: true

Example: Setting custom lists fields:

defaults:
  - field: "custom_integer_list"
    value: [1,2,3]

overrides:
  - field: "custom_string_list"
    value: ["one","two","three"]

Note: The field values correspond to keys in the JSON request body, not fields in this CRD.

Appears in:

Field Description Default Validation
field ShortString Name of the field. MaxLength: 256
MinLength: 1
Required: {}
value JSON Default value for the field. This can be any JSON data type. Required: {}

FieldTransformation

Maps a request JSON field to a CEL expression. The expression is evaluated against the current request body and its result is assigned to the configured field.

Appears in:

Field Description Default Validation
field ShortString Name of the field to set. MaxLength: 256
MinLength: 1
Required: {}
expression CELExpression CEL expression used to compute the field value. MaxLength: 16384
MinLength: 1
Required: {}

Frontend

Appears in:

Field Description Default Validation
tcp FrontendTCP Settings for managing incoming TCP connections. Optional: {}
networkAuthorization Authorization CEL authorization on downstream network connections.
This runs before protocol handling and is intended for L4 access control,
for example using source.address with cidr(...).containsIP(...).		 Optional: {}
tls FrontendTLS Settings for managing incoming TLS connections. Optional: {}
http FrontendHTTP Settings for managing incoming HTTP requests. Optional: {}
proxyProtocol FrontendProxyProtocol Settings for downstream PROXY protocol handling.
If configured, incoming connections may require a PROXY header before
normal protocol handling. This can also be configured to allow both
PROXY and non-PROXY traffic on the same listener.		 Optional: {}
connect FrontendConnect Settings for downstream HTTP CONNECT handling.
If unset, CONNECT requests are rejected with Method Not Allowed.		 Optional: {}
accessLog AccessLog Access logging configuration. Optional: {}
tracing Tracing OpenTelemetry tracing settings. Optional: {}
metrics MetricLabels Custom Prometheus metric label configuration.
CEL expressions are evaluated per-request and added as labels to all
Prometheus metrics exposed by agentgateway.		 Optional: {}

FrontendConnect

Appears in:

Field Description Default Validation
mode FrontendConnectMode Whether downstream CONNECT requests are accepted. Required: {}

FrontendConnectMode

Underlying type: string

Appears in:

Field Description
Deny Deny rejects downstream CONNECT requests.
Route Route treats CONNECT as an HTTP request and routes it through the HTTP
matching chain before establishing a raw tunnel to the selected backend.
Tunnel Tunnel terminates CONNECT and sends the upgraded stream through the
addressed gateway bind as a new downstream connection.

FrontendHTTP

Appears in:

Field Description Default Validation
maxBufferSize ByteSize Maximum HTTP body size that will be buffered
into memory.
Bodies will only be buffered for policies which require buffering.
If unset, this defaults to 2mb.		 MaxLength: 32
MinLength: 1
Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
XIntOrString: {}
Optional: {}
http1MaxHeaders integer Maximum number of headers allowed
in HTTP/1.1 requests.
If unset, this defaults to 100.		 Maximum: 4096
Minimum: 1
Optional: {}
http1IdleTimeout Duration Timeout before an unused connection is
closed.
If unset, this defaults to 10 minutes.		 Optional: {}
http1HeaderCase HTTPHeaderCase Controls HTTP/1 request header name casing when encoding responses on the same connection.
This only applies to HTTP/1. If a request is HTTP/2 in either the incoming or outgoing request, this will be ignored.
HTTP/2 requests are always lower case.
Modifying the headers from other policies may result in the original case being lost.		 Optional: {}
http2WindowSize ByteSize Initial window size for stream-level flow
control for received data.		 MaxLength: 32
MinLength: 1
Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
XIntOrString: {}
Optional: {}
http2ConnectionWindowSize ByteSize Initial window size for
connection-level flow control for received data.		 MaxLength: 32
MinLength: 1
Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
XIntOrString: {}
Optional: {}
http2FrameSize ByteSize Maximum frame size to use.
If unset, this defaults to 16kb.		 MaxLength: 32
MinLength: 1
Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
XIntOrString: {}
Optional: {}
http2MaxHeaderSize ByteSize Maximum aggregate size of decoded HTTP/2
request headers.
If unset, this defaults to 16Ki.		 MaxLength: 32
MinLength: 1
Pattern: ^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)(([KMGTPE]i)|[numkMGTPE]|[eE](\+?0*([0-9]|1[0-8])|-0*[0-9]))?$
XIntOrString: {}
Optional: {}
http2KeepaliveInterval Duration Optional: {}
http2KeepaliveTimeout Duration Optional: {}
maxConnectionDuration Duration Maximum time a connection is allowed to remain open.
After this duration, the connection is gracefully closed after the current in-flight request completes.
Useful for ensuring even traffic distribution behind load balancers during scaling events.		 Optional: {}

FrontendProxyProtocol

Appears in:

Field Description Default Validation
version ProxyProtocolVersion PROXY protocol version to accept.
If unset, this defaults to V2.		 V2 Optional: {}
mode ProxyProtocolMode Whether PROXY headers are required or optional.
If unset, this defaults to Strict.		 Strict Optional: {}

FrontendTCP

Appears in:

Field Description Default Validation
keepalive Keepalive Settings for enabling TCP keepalives on the connection. Optional: {}

FrontendTLS

Appears in:

Field Description Default Validation
handshakeTimeout Duration Deadline for a TLS handshake to
complete. If unset, this defaults to 15s.		 Optional: {}
alpnProtocols TinyString Application-Layer Protocol Negotiation (ALPN)
value to use in the TLS handshake.
If not present, defaults to ["h2", "http/1.1"].		 MaxItems: 16
MaxLength: 64
MinItems: 1
MinLength: 1
Optional: {}
minProtocolVersion TLSVersion Minimum TLS version to support. Optional: {}
maxProtocolVersion TLSVersion Maximum TLS version to support. Optional: {}
cipherSuites CipherSuite array Cipher suites for a TLS listener.
The value is a comma-separated list of cipher suites, for example
TLS13_AES_256_GCM_SHA384,TLS13_AES_128_GCM_SHA256.
Use this in the TLS options field of a TLS listener.		 Optional: {}
keyExchangeGroups KeyExchangeGroup array Ordered list of key exchange groups for a TLS listener.
For example: X25519_MLKEM768,X25519.		 Optional: {}

GcpAuth

Google Cloud authentication settings.

Appears in:

Field Description Default Validation
type GcpAuthType The type of token to generate. To authenticate to GCP services,
generally an AccessToken is used. To authenticate to Cloud Run, an
IdToken is used.		 Optional: {}
secretRef LocalSecretKeyRef Credential source, defaulting to a Kubernetes
Secret, containing ADC-compatible Google credential JSON. When using
the default Secret resolver, this must be stored in the credentials.json
key by default; override via secretRef.key. When omitted, ambient
credentials are used.		 Optional: {}
audience ShortString Explicit aud value for the ID token. Only
valid with IdToken type. If not set, the aud is automatically
derived from the backend hostname.		 MaxLength: 256
MinLength: 1
Optional: {}

GcpAuthType

Underlying type: string

Appears in:

Field Description
AccessToken
IdToken

GeminiConfig

Settings for the Gemini LLM provider.

Appears in:

Field Description Default Validation
model ShortString Model name override, such as gemini-2.5-pro.
If unset, the model name is taken from the request.		 MaxLength: 256
MinLength: 1
Optional: {}

GlobalRateLimit

Appears in:

Field Description Default Validation
backendRef BackendObjectReference Rate limit server to reach.
Supported types: Service and Backend.		 Required: {}
failureMode FailureMode Behavior when the remote rate limit service is
unavailable or returns an error. FailOpen allows the request to continue.
FailClosed (default) denies the request.		 Optional: {}
domain ShortString Domain under which this limit should apply.
This is an arbitrary string that enables a rate limit server to distinguish between different applications.		 MaxLength: 256
MinLength: 1
Required: {}
descriptors RateLimitDescriptor array 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.		 MaxItems: 16
MinItems: 1
Required: {}

GoogleModelArmor

Appears in:

Field Description Default Validation
templateId ShortString Template ID for Google Model Armor. MaxLength: 256
MinLength: 1
Required: {}
projectId ShortString Google Cloud project ID. MaxLength: 256
MinLength: 1
Required: {}
location ShortString Google Cloud location, for example us-central1.
Defaults to us-central1 if not specified.		 us-central1 MaxLength: 256
MinLength: 1
Optional: {}
policies BackendSimple Policies for communicating with Google Model Armor. Optional: {}

HTTPHeaderCase

Underlying type: string

Appears in:

Field Description
Lowercase
Preserve

HTTPHeaderName

Underlying type: string

HTTP header name that does not allow pseudo-headers.

Validation:

  • MaxLength: 256
  • MinLength: 1
  • Pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$

Appears in:

HTTPVersion

Underlying type: string

Appears in:

Field Description
HTTP1
HTTP2

HeaderModifiers

Modifies request and response headers.

Appears in:

Field Description Default Validation
request HTTPHeaderFilter Header changes to apply before forwarding a request. Optional: {}
response HTTPHeaderFilter Header changes to apply before returning a response. Optional: {}

HeaderName

Underlying type: string

HTTP header name.

Validation:

  • MaxLength: 256
  • MinLength: 1
  • Pattern: ^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$

Appears in:

HeaderSendMode

Underlying type: string

Whether HTTP headers are delivered to the external processor.

Appears in:

Field Description
Send HeaderSendModeSend sends headers to the external processor.
Skip HeaderSendModeSkip does not send headers to the external processor.

HeaderTransformation

Appears in:

Field Description Default Validation
name HeaderName The name of the header to add. MaxLength: 256
MinLength: 1
Pattern: ^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Required: {}
value CELExpression CEL expression that generates the output value for
the header.		 MaxLength: 16384
MinLength: 1
Required: {}

Health

Appears in:

Field Description Default Validation
unhealthyCondition CELExpression CEL expression that determines whether a response indicates an unhealthy backend.
When the expression evaluates to true, the backend is considered unhealthy and may be evicted.
For example, to evict on 5xx responses: response.code >= 500.
When unset, any 5xx response, or a connection failure, is treated as unhealthy.
This default lowers the backend's health score but does not trigger eviction on its own.		 MaxLength: 16384
MinLength: 1
Optional: {}
eviction BackendEviction Settings for evicting unhealthy backends. Optional: {}

HostnameRewrite

Appears in:

Field Description Default Validation
mode HostnameRewriteMode 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.		 Required: {}

HostnameRewriteMode

Underlying type: string

Appears in:

Field Description
Auto
None

Image

Container image settings. See https://kubernetes.io/docs/concepts/containers/images for details.

Appears in:

Field Description Default Validation
registry string Image registry. Optional: {}
repository string Image repository. Optional: {}
tag string Image tag. Optional: {}
digest string Image digest, such as sha256:12345.... Optional: {}
pullPolicy PullPolicy Image pull policy for the container. See
https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy
for details.		 Optional: {}

InsecureTLSMode

Underlying type: string

Appears in:

Field Description
All InsecureTLSModeInsecure disables all TLS verification
Hostname InsecureTLSModeHostname enables verifying the CA certificate, but disables verification of the hostname/SAN.
Note this is still, generally, very "insecure" as the name suggests.

IstioSpec

Appears in:

Field Description Default Validation
enabled boolean Explicitly turns Istio integration on or off for this gateway. Optional: {}
caAddress string Address of the Istio CA. If unset, defaults to https://istiod.istio-system.svc:15012. Optional: {}
trustDomain string Istio trust domain. If not set, defaults to cluster.local, or the default
trust domain for the control plane's istio revision.		 Optional: {}
additionalTrustDomains string array Additional SPIFFE trust domains accepted on inbound HBONE connections.
The local trust domain is always implicitly included.		 Optional: {}
clusterId string ID of the cluster this gateway runs in. If unset, defaults to Kubernetes. Optional: {}
network string Istio network this gateway runs in. If unset, defaults to the empty network. Optional: {}

JWKS

Validation:

  • ExactlyOneOf: [remote inline]

Appears in:

Field Description Default Validation
remote RemoteJWKS How to reach the JSON Web Key Set from a remote
address.		 Optional: {}
inline string Inline JSON Web Key Set used to validate the
signature of the JWT.		 MaxLength: 65536
MinLength: 2
Optional: {}

JWTAuthentication

Appears in:

Field Description Default Validation
mode JWTAuthenticationMode Validation mode for JWT authentication. Strict Optional: {}
providers JWTProvider array MaxItems: 64
MinItems: 1
Required: {}
location AuthorizationExtractionLocation Where JWT credentials are read from.
If omitted, credentials are read from the Authorization header with the Bearer prefix.		 ExactlyOneOf: [header queryParameter cookie expression]
Optional: {}
mcp JWTMCPConfig 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.		 Optional: {}

JWTAuthenticationMode

Underlying type: string

Appears in:

Field Description
Strict A valid token, issued by a configured issuer, must be present.
This is the default option.
Optional If a token exists, validate it.
Warning: this allows requests without a JWT token!
Permissive Requests are never rejected. This is useful for usage of claims in later steps (authorization, logging, etc).
Warning: this allows requests without a JWT token!

JWTMCPConfig

MCP-specific extensions for JWT authentication.

Appears in:

Field Description Default Validation
resourceMetadata object (keys:string, values:JSON) Metadata to use for MCP resources,
served at the MCP OAuth metadata endpoints.		 Optional: {}
provider McpIDP Identity provider to use for MCP authentication flows. Optional: {}
clientId 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.		 Optional: {}

JWTProvider

Appears in:

Field Description Default Validation
issuer ShortString IdP that issued the JWT. This corresponds to the
iss claim (RFC 7519 §4.1.1).		 MaxLength: 256
MinLength: 1
Required: {}
audiences string array Allowed audiences that are allowed
access. This corresponds to the aud claim
(RFC 7519 §4.1.3).
If unset, any audience is allowed.		 MaxItems: 64
MinItems: 1
Optional: {}
jwks JWKS JSON Web Key Set used to validate the signature of the
JWT.		 ExactlyOneOf: [remote inline]
Required: {}

Keepalive

TCP keepalive settings.

Appears in:

Field Description Default Validation
retries integer Maximum number of keepalive probes to send before dropping the connection.
If unset, this defaults to 9.		 Maximum: 64
Minimum: 1
Optional: {}
time Duration Time a connection needs to be idle before keepalive probes start being sent.
If unset, this defaults to 180s.		 Optional: {}
interval Duration Time between keepalive probes.
If unset, this defaults to 180s.		 Optional: {}

KeyExchangeGroup

Underlying type: string

Appears in:

Field Description
X25519
P-256
P-384
X25519_MLKEM768

KubernetesResourceOverlay

KubernetesResourceOverlay provides a mechanism to customize generated Kubernetes resources using Strategic Merge Patch semantics.

Overlay Application Order

Overlays are applied after all typed configuration fields have been processed. The full merge order is:

  1. GatewayClass typed configuration fields, for example replicas or image settings from parametersRef
  2. Gateway typed configuration fields from infrastructure.parametersRef
  3. GatewayClass overlays are applied
  4. Gateway overlays are applied

This ordering means Gateway-level configuration overrides GatewayClass-level configuration at each stage. For example, if both levels set the same label, the Gateway value wins.

Appears in:

Field Description Default Validation
metadata ObjectMetadata Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec JSON spec provides an opaque mechanism to configure the resource spec.
This field accepts a complete or partial Kubernetes resource spec, such
as PodSpec or ServiceSpec, and will be merged with the generated
configuration using Strategic Merge Patch semantics.
# Application Order
Overlays are applied after all typed configuration fields from both levels.
The full merge order is:
1. GatewayClass typed configuration fields
2. Gateway typed configuration fields
3. GatewayClass overlays
4. Gateway overlays (can override all previous values)
# Strategic Merge Patch & Deletion Guide
This merge strategy allows you to override individual fields, merge lists, or delete items
without needing to provide the entire resource definition.
1. Replacing Values (Scalars):
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
2. Merging Lists (Append/Merge):
Lists with "merge keys", like containers which merges on name, or
tolerations which merges on key,
will append your items to the generated list, or update existing items if keys match.
3. Deleting Fields or List Items ($patch: delete):
To remove a field or list item from the generated resource, use the
$patch: delete directive. This works for both map fields and list items,
and is the recommended approach because it works with both client-side
and server-side apply.
spec:
template:
spec:
# Delete pod-level securityContext
securityContext:
$patch: delete
# Delete nodeSelector
nodeSelector:
$patch: delete
containers:
# Be sure to use the correct proxy name here or you will add a
# container instead of modifying a container.
- name: proxy-name
# Delete container-level securityContext
securityContext:
$patch: delete
4. Null Values (server-side apply only):
Setting a field to null can also remove it, but this ONLY works with
kubectl apply --server-side or equivalent. With regular client-side
kubectl apply, null values are stripped by kubectl before reaching
the API server, so the deletion won't occur. Prefer $patch: delete
for consistent behavior across both apply modes.
spec:
template:
spec:
nodeSelector: null # Removes nodeSelector (server-side apply only!)
5. Replacing Maps Entirely ($patch: replace):
To replace an entire map with your values (instead of merging), use $patch: replace.
This removes all existing keys and replaces them with only your specified keys.
spec:
template:
spec:
nodeSelector:
$patch: replace
custom-key: custom-value
6. Replacing Lists Entirely ($patch: replace):
If you want to strictly define a list and ignore all generated defaults, use $patch: replace.
service:
spec:
ports:
- $patch: replace
- name: http
port: 80
targetPort: 8080
protocol: TCP
- name: https
port: 443
targetPort: 8443
protocol: TCP		 Type: object
Optional: {}

LLMProvider

Large language model provider that the backend routes requests to.

Validation:

  • ExactlyOneOf: [openai azureopenai azure anthropic gemini vertexai bedrock custom]

Appears in:

Field Description Default Validation
openai OpenAIConfig OpenAI provider settings. Optional: {}
azureopenai AzureOpenAIConfig Azure OpenAI provider settings. Optional: {}
azure AzureConfig Azure provider with resource-based configuration.
Supports both Azure OpenAI and Azure AI Foundry resource types.		 Optional: {}
anthropic AnthropicConfig Anthropic provider settings. Optional: {}
gemini GeminiConfig Gemini provider settings. Optional: {}
vertexai VertexAIConfig Vertex AI provider settings. Optional: {}
bedrock BedrockConfig Bedrock provider settings. Optional: {}
custom CustomProvider Custom provider configures a non-managed or self-hosted LLM provider.
Use this when the provider target and API formats should be declared
explicitly instead of inferred from a managed provider such as OpenAI or
Anthropic.		 Optional: {}
host ShortString Hostname to send requests to.
For custom providers without backendRef, host and port specify the target.
For managed providers, host and port override the provider default.		 MaxLength: 256
MinLength: 1
Optional: {}
port integer Port to send requests to. Maximum: 65535
Minimum: 1
Optional: {}
path LongString URL path to use for LLM provider API requests.
This is useful when you need to route requests to a different API endpoint while maintaining
compatibility with the original provider's API structure.
If not specified, the default path for the provider is used.		 MaxLength: 1024
MinLength: 1
Optional: {}
pathPrefix LongString Overrides the default base path prefix, such as /v1, for upstream requests.
Path translation for cross-format requests still applies using this prefix.
Only supported for OpenAI and Anthropic providers.		 MaxLength: 1024
MinLength: 1
Optional: {}

LocalBackendObjectReference

References a namespace-local backend resource.

Appears in:

Field Description Default Validation
group string API group of the referenced resource. For example, gateway.networking.k8s.io.
When unspecified or empty string, core API group is inferred.		 MaxLength: 253
Pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Optional: {}
kind string Kind of the referenced resource. For example, Service.
Defaults to "Service" when not specified.		 Service MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Optional: {}
name string Name of the referenced resource. MaxLength: 253
MinLength: 1
Required: {}
port integer Destination port number to use for this resource.
Required when the referenced resource is a Kubernetes Service.		 Maximum: 65535
Minimum: 1
Optional: {}

LocalPolicyTargetReference

Selects one same-namespace object by group, kind, and name. The object must be in the same namespace as the policy.

Appears in:

Field Description Default Validation
group Group The API group of the target resource.
For Kubernetes Gateway API resources, the group is gateway.networking.k8s.io.		 MaxLength: 253
Pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Required: {}
kind Kind The API kind of the target resource, such as Gateway or HTTPRoute. MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Required: {}
name ObjectName The name of the target resource. Required: {}

LocalPolicyTargetReferenceWithSectionName

Selects one same-namespace object by group, kind, name, and, optionally, sectionName or port. The object must be in the same namespace as the policy.

Validation:

  • AtMostOneOf: [sectionName port]

Appears in:

Field Description Default Validation
group Group The API group of the target resource.
For Kubernetes Gateway API resources, the group is gateway.networking.k8s.io.		 MaxLength: 253
Pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Required: {}
kind Kind The API kind of the target resource, such as Gateway or HTTPRoute. MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Required: {}
name ObjectName The name of the target resource. Required: {}
sectionName SectionName The named section of the target resource. Optional: {}
port integer The port of the target resource this policy applies to.
At most one of sectionName or port may be set.
Only valid on frontend policies targeting a Gateway.		 Maximum: 65535
Minimum: 1
Optional: {}

LocalPolicyTargetSelector

Selects same-namespace objects by group, kind, and matchLabels. The object must be in the same namespace as the policy and match the specified labels.

Appears in:

Field Description Default Validation
group Group The API group of the target resource.
For Kubernetes Gateway API resources, the group is gateway.networking.k8s.io.		 MaxLength: 253
Pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Required: {}
kind Kind The API kind of the target resource, such as Gateway or HTTPRoute. MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Required: {}
matchLabels object (keys:string, values:string) Labels that must be present on each selected target resource. Required: {}

LocalPolicyTargetSelectorWithSectionName

Selects same-namespace objects by group, kind, matchLabels, and, optionally, sectionName. Each selected object must be in the same namespace as the policy and match the specified labels. Prefer targetRefs when reconciliation latency is important, especially when many policies target the same resource.

Validation:

  • AtMostOneOf: [sectionName port]

Appears in:

Field Description Default Validation
group Group The API group of the target resource.
For Kubernetes Gateway API resources, the group is gateway.networking.k8s.io.		 MaxLength: 253
Pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Required: {}
kind Kind The API kind of the target resource, such as Gateway or HTTPRoute. MaxLength: 63
MinLength: 1
Pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
Required: {}
matchLabels object (keys:string, values:string) Labels that must be present on each selected target resource. Required: {}
sectionName SectionName The named section of each selected target resource. Optional: {}
port integer The port of each selected target resource this policy applies to.
At most one of sectionName or port may be set.
Only valid on frontend policies targeting a Gateway.		 Maximum: 65535
Minimum: 1
Optional: {}

LocalRateLimit

Local rate limiting policy. Local rate limits are handled on a per-proxy basis, without coordination between instances of the proxy.

Validation:

  • ExactlyOneOf: [requests tokens]

Appears in:

Field Description Default Validation
requests integer Number of HTTP requests per unit of time that
are allowed. Requests exceeding this limit will fail with a 429
error.		 Minimum: 1
Optional: {}
tokens 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.		 Minimum: 1
Optional: {}
unit LocalRateLimitUnit Unit of time for the limit. Required: {}
burst integer Allowance of requests above the request-per-unit
that should be allowed within a short period of time.		 Optional: {}

LocalRateLimitUnit

Underlying type: string

Appears in:

Field Description
Seconds
Minutes
Hours

LocalSecretKeyRef

References a same-namespace credential and, optionally, a specific key within it whose value should be used. Set only name to reference a Kubernetes Secret. When key is omitted, a location-specific default key is used.

Appears in:

Field Description Default Validation
name ObjectName The name of the referenced credential. Required: {}
group string The API group of the referenced credential.
Empty selects the core API group.		 Optional: {}
kind string The kind of the referenced credential.
Empty defaults to Secret.		 Optional: {}
key string The key in the referenced Secret whose value is used. If omitted, a
location-specific default key is used.		 MaxLength: 253
MinLength: 1
Optional: {}

LocalSecretObjectRef

References a same-namespace credential. Set only name to reference a Kubernetes Secret.

Appears in:

Field Description Default Validation
name ObjectName The name of the referenced credential. Required: {}
group string The API group of the referenced credential.
Empty selects the core API group.		 Optional: {}
kind string The kind of the referenced credential.
Empty defaults to Secret.		 Optional: {}

LogTracingAttributes

Appears in:

Field Description Default Validation
remove TinyString array Default fields to remove. For example,
http.method.		 MaxItems: 32
MaxLength: 64
MinItems: 1
MinLength: 1
Optional: {}
add AttributeAdd array Additional key-value pairs to add to each entry.
The value is a CEL expression. If the CEL expression fails to evaluate,
the pair will be excluded.		 MinItems: 1
Optional: {}

MCPAuthentication

Appears in:

Field Description Default Validation
resourceMetadata object (keys:string, values:JSON) Metadata to use for MCP resources. Optional: {}
provider McpIDP Identity provider to use for authentication. Optional: {}
issuer ShortString IdP that issued the JWT. This corresponds to the
iss claim (RFC 7519 §4.1.1).		 MaxLength: 256
MinLength: 1
Optional: {}
audiences string array Allowed audiences that are allowed
access. This corresponds to the aud claim
(RFC 7519 §4.1.3).
If unset, any audience is allowed.		 MaxItems: 64
MinItems: 1
Optional: {}
jwks RemoteJWKS Remote JSON Web Key used to validate the signature of
the JWT.		 Required: {}
mode JWTAuthenticationMode Validation mode for JWT authentication. Strict Optional: {}
clientId 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.		 Optional: {}

MCPBackend

MCP backend settings.

Appears in:

Field Description Default Validation
targets McpTargetSelector array MCP targets to use for this backend. Policies
targeting MCP targets must use targetRefs[].sectionName to select
the target by name.		 ExactlyOneOf: [selector static]
MaxItems: 32
MinItems: 1
Required: {}
sessionRouting SessionRouting MCP session routing behavior.
Defaults to Stateful if not set.		 Optional: {}
failureMode FailureMode Behavior when MCP targets fail to initialize or
become unavailable at runtime. FailOpen skips failed targets and
continues serving from healthy ones. FailClosed (default) fails the
entire session if any target fails.		 Optional: {}
prefixMode PrefixMode How tool and prompt names are prefixed with the target name. Resource URIs
always retain target routing information when multiplexing and are unaffected.
Conditional (default) prefixes only when there are multiple targets.
Always prefixes even with a single target. Never exposes unprefixed
names and routes calls by looking up which target serves the name;
names must be unique across targets.		 Optional: {}

MCPGuardrails

MCPGuardrails is the MCP-layer analog of Envoy ext_authz: an ordered chain of policy processors invoked per JSON-RPC method.

Appears in:

Field Description Default Validation
processors MCPGuardrailsProcessor array processors is the ordered list of policy processors applied to matched
methods. Processors run in the order listed; the first to reject a request
short-circuits the chain.		 ExactlyOneOf: [remote]
MaxItems: 16
MinItems: 1
Required: {}

MCPGuardrailsProcessor

MCPGuardrailsProcessor selects a single policy processor. Exactly one variant must be set.

Validation:

  • ExactlyOneOf: [remote]

Appears in:

Field Description Default Validation
remote MCPGuardrailsRemote remote configures a gRPC policy server. Optional: {}
methods object (keys:string, values:MCPMethodPhase) methods is the allowlist of JSON-RPC methods (e.g. tools/call,
tools/list) routed through this processor, keyed by method name with the
phase it runs in. Keys may be exact, a prefix wildcard (tools/*), a suffix
wildcard (*/list), or * for all methods; the most specific match wins.
Methods matching no key, including unknown ones, bypass this processor.		 MaxProperties: 64
MinProperties: 1
Required: {}

MCPGuardrailsRemote

Appears in:

Field Description Default Validation
backendRef BackendObjectReference backendRef references the remote guardrails policy server.
Supported types: Service and Backend.		 Required: {}
failureMode FailureMode failureMode controls behavior when the policy server is unreachable
or returns an error. FailOpen allows the request; FailClosed
(default) denies it.		 Optional: {}
metadata object (keys:string, values:CELExpression) Refer to Kubernetes API documentation for fields of metadata. MaxProperties: 64
Optional: {}
allowedRequestHeaders HeaderName array allowedRequestHeaders lists the incoming request headers forwarded to
the policy server in McpRequest.headers. If empty, all headers and
pseudo-headers (:authority, :method, ...) are forwarded. Matching is
case-insensitive.		 MaxItems: 64
MaxLength: 256
MinLength: 1
Pattern: ^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Optional: {}
disallowedRequestHeaders HeaderName array disallowedRequestHeaders lists header names never forwarded to the
policy server, even if listed in allowedRequestHeaders. Matching is
case-insensitive.		 MaxItems: 64
MaxLength: 256
MinLength: 1
Pattern: ^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Optional: {}

MCPMethodPhase

Underlying type: string

MCPMethodPhase controls when an MCP method is run through the guardrails pipeline.

Appears in:

Field Description
Off
Request
Response
Full

MCPProtocol

Underlying type: string

Protocol to use for an MCP target.

Appears in:

Field Description
StreamableHTTP MCPProtocolStreamableHTTP specifies that StreamableHTTP must be used as
the protocol.
SSE MCPProtocolSSE specifies that Server-Sent Events (SSE) must be used as
the protocol.

McpIDP

Underlying type: string

Appears in:

Field Description
Auth0
Keycloak
Okta
Descope
Authentik

McpSelector

Appears in:

Field Description Default Validation
namespaces LabelSelector namespace is the label selector for namespaces that Service
resources should be selected from. If unset, only the namespace of the
AgentgatewayBackend is searched.		 Optional: {}
services LabelSelector services is the label selector for which Service resources should be
selected.		 Optional: {}

McpTarget

MCP target configuration.

Validation:

  • ExactlyOneOf: [host backendRef]

Appears in:

Field Description Default Validation
host ShortString Hostname or IP address of the MCP target. MaxLength: 256
MinLength: 1
Optional: {}
backendRef LocalObjectReference Namespace-local Service resource by name.
When set, this replaces host only; port, path, and protocol
remain configured on this target.		 Optional: {}
port integer Port number of the MCP target. Maximum: 65535
Minimum: 1
Required: {}
path LongString URL path of the MCP target endpoint.
Defaults to "/sse" for the SSE protocol or "/mcp" for the
StreamableHTTP protocol if not specified.		 MaxLength: 1024
MinLength: 1
Optional: {}
protocol MCPProtocol Protocol to use for the connection to the MCP
target.		 Optional: {}
policies BackendSimple Policies for communicating with this backend.
Policies may also be set in AgentgatewayPolicy, or in the top-level
AgentgatewayBackend. Policies are merged on a field-level basis, with
order: AgentgatewayPolicy < AgentgatewayBackend < AgentgatewayBackend MCP (this field).
This field may only be used with host-based static targets, not
backendRef.		 Optional: {}

McpTargetSelector

MCP target selection for this backend.

Validation:

  • ExactlyOneOf: [selector static]

Appears in:

Field Description Default Validation
name SectionName Name of the MCP target. Required: {}
selector McpSelector Label selector used to select Service resources.
If policies are needed on a per-service basis, AgentgatewayPolicy can
target the desired Service.		 Optional: {}
static McpTarget Static MCP destination. When connecting to
in-cluster Service resources, it is recommended to use selector
instead.		 ExactlyOneOf: [host backendRef]
Optional: {}

Message

An entry for a message to prepend or append to each prompt.

Appears in:

Field Description Default Validation
role string Role of the message. The available roles depend on the backend
LLM provider model, such as SYSTEM or USER in the OpenAI API.		 Required: {}
content string String content of the message. Required: {}

MetricAttributes

Appears in:

Field Description Default Validation
add AttributeAdd array Additional key-value pairs to add as custom labels
to all Prometheus metrics. The value is a CEL expression evaluated
per-request. If the CEL expression fails to evaluate, the label value
is set to "unknown".
WARNING: High-cardinality labels (e.g., per-user IDs) can significantly
increase Prometheus storage and memory usage. Prefer low-cardinality
dimensions like team or environment.		 MaxItems: 16
MinItems: 1
Optional: {}

MetricLabels

Custom labels to add to Prometheus metrics.

Appears in:

Field Description Default Validation
attributes MetricAttributes Customizations to the labels that are
added to Prometheus metrics.		 Required: {}

ModelCatalogConfigMapRef

ModelCatalogConfigMapRef identifies a ConfigMap holding model cost catalog JSON. The ConfigMap must be in the same namespace as the Gateway that references it.

Appears in:

Field Description Default Validation
name string MinLength: 1
Required: {}
key string Data key whose value is the catalog JSON. Defaults to "catalog.json". Optional: {}

ModelCatalogSource

ModelCatalogSource is a single source of model cost catalog data.

Appears in:

Field Description Default Validation
configMap ModelCatalogConfigMapRef Optional: {}

ModelCatalogSpec

ModelCatalogSpec configures model cost catalog sources for the agentgateway proxy.

Appears in:

Field Description Default Validation
sources ModelCatalogSource array Optional: {}

NamedLLMProvider

Appears in:

Field Description Default Validation
name SectionName Name of the provider. Policies can target this provider by name. Required: {}
policies BackendWithAI Policies for communicating with this backend.
Policies may also be set in AgentgatewayPolicy, or in the top-level
AgentgatewayBackend. Policies are merged on a field-level basis, with
order: AgentgatewayPolicy < AgentgatewayBackend < AgentgatewayBackend
LLM provider (this field).		 Optional: {}
openai OpenAIConfig OpenAI provider settings. Optional: {}
azureopenai AzureOpenAIConfig Azure OpenAI provider settings. Optional: {}
azure AzureConfig Azure provider with resource-based configuration.
Supports both Azure OpenAI and Azure AI Foundry resource types.		 Optional: {}
anthropic AnthropicConfig Anthropic provider settings. Optional: {}
gemini GeminiConfig Gemini provider settings. Optional: {}
vertexai VertexAIConfig Vertex AI provider settings. Optional: {}
bedrock BedrockConfig Bedrock provider settings. Optional: {}
custom CustomProvider Custom provider configures a non-managed or self-hosted LLM provider.
Use this when the provider target and API formats should be declared
explicitly instead of inferred from a managed provider such as OpenAI or
Anthropic.		 Optional: {}
host ShortString Hostname to send requests to.
For custom providers without backendRef, host and port specify the target.
For managed providers, host and port override the provider default.		 MaxLength: 256
MinLength: 1
Optional: {}
port integer Port to send requests to. Maximum: 65535
Minimum: 1
Optional: {}
path LongString URL path to use for LLM provider API requests.
This is useful when you need to route requests to a different API endpoint while maintaining
compatibility with the original provider's API structure.
If not specified, the default path for the provider is used.		 MaxLength: 1024
MinLength: 1
Optional: {}
pathPrefix LongString Overrides the default base path prefix, such as /v1, for upstream requests.
Path translation for cross-format requests still applies using this prefix.
Only supported for OpenAI and Anthropic providers.		 MaxLength: 1024
MinLength: 1
Optional: {}

OAuthActorToken

Appears in:

Field Description Default Validation
source AuthorizationExtractionLocation Where to read the actor token. Actor tokens have no default source. ExactlyOneOf: [header queryParameter cookie expression]
Required: {}
tokenType OAuthTokenType OAuth token type. Empty defaults to AccessToken. Optional: {}
mayAct OAuthMayActValidationMode may_act claim validation mode. When omitted, may_act is not enforced. Optional: {}

OAuthClientAuth

OAuthClientAuth configures token endpoint client authentication.

Appears in:

Field Description Default Validation
clientId string Client ID sent to the token endpoint. MinLength: 1
Required: {}
secretRef LocalSecretKeyRef Secret providing the clientSecret key by default; override via
secretRef.key. When omitted, client_id is sent without a secret, which
is only valid with ClientSecretPost.		 Optional: {}
privateKeyJwt OAuthPrivateKeyJWT privateKeyJwt client assertion settings. Required when method is PrivateKeyJwt. Optional: {}
method OAuthClientAuthMethod Defaults to ClientSecretBasic. Optional: {}

OAuthClientAuthMethod

Underlying type: string

Appears in:

Field Description
ClientSecretBasic
ClientSecretPost
PrivateKeyJwt

OAuthGrantType

Underlying type: string

Appears in:

Field Description
TokenExchange
JwtBearer

OAuthInMemoryTokenCache

Appears in:

Field Description Default Validation
maxEntries integer Default 8192; 0 disables the cache. Optional: {}
defaultTtl Duration TTL used when the token endpoint omits expires_in. Default 300s. Optional: {}

OAuthMayActValidationMode

Underlying type: string

Appears in:

Field Description
Required Require the subject's may_act claim to authorize the actor.

OAuthPrivateKeyJWT

OAuthPrivateKeyJWT configures RFC 7523 private_key_jwt client authentication.

Appears in:

Field Description Default Validation
signingKeyRef LocalSecretKeyRef Secret providing the signingKey key by default with a PEM-encoded RSA
or EC private key; override the key name via signingKeyRef.key.		 Required: {}
alg OAuthPrivateKeyJWTSigningAlgorithm JWS signing algorithm. Defaults to RS256. Optional: {}
kid string Optional JWS key ID header. Optional: {}
assertionAudience string Audience for the client assertion, typically the token endpoint URL. MinLength: 1
Required: {}

OAuthPrivateKeyJWTSigningAlgorithm

Underlying type: string

Appears in:

Field Description
RS256
RS384
RS512
ES256
ES384

OAuthTokenCache

Appears in:

Field Description Default Validation
inMemory OAuthInMemoryTokenCache Optional: {}

OAuthTokenExchange

OAuth token exchange settings for backend authentication.

Appears in:

Field Description Default Validation
backendRef BackendObjectReference RFC 8693 token endpoint backend. Required: {}
path string Token endpoint path; defaults to "/". Must start with "/". Pattern: ^/
Optional: {}
grantType OAuthGrantType RFC followed by the request. Defaults to TokenExchange (RFC 8693). Optional: {}
subjectToken OAuthTokenSpec Subject token / assertion source and type. Defaults to Authorization Bearer, AccessToken. Optional: {}
actorToken OAuthActorToken RFC 8693 delegation actor token. TokenExchange grant only. Optional: {}
audiences string array Audiences sent to the token endpoint. MaxItems: 64
MinItems: 1
Optional: {}
scopes string array Scopes sent to the token endpoint. MaxItems: 64
MinItems: 1
Optional: {}
resources string array Resources sent to the token endpoint. MaxItems: 64
MinItems: 1
Optional: {}
requestedTokenType OAuthTokenType RFC 8693 requested_token_type. Optional: {}
additionalParams object (keys:string, values:CELExpression) Extra form params; values are CEL expressions over the incoming request. MaxProperties: 64
Optional: {}
clientAuth OAuthClientAuth Client authentication for the token endpoint. When unset, none is sent. Optional: {}
location AuthorizationLocation Where the exchanged token is written to the backend request.
Defaults to Authorization: Bearer.		 ExactlyOneOf: [header queryParameter cookie]
Optional: {}
cache OAuthTokenCache Response cache configuration. Optional: {}

OAuthTokenSpec

Appears in:

Field Description Default Validation
source AuthorizationExtractionLocation Where to read the token. CEL expression variant is permitted. ExactlyOneOf: [header queryParameter cookie expression]
Optional: {}
tokenType OAuthTokenType OAuth token type. Empty defaults to AccessToken. Optional: {}

OAuthTokenType

Underlying type: string

Appears in:

Field Description
AccessToken
Jwt
IdToken
IdJag

OTLPProtocol

Underlying type: string

Appears in:

Field Description
HTTP
GRPC

ObjectMetadata

ObjectMetadata contains labels and annotations for metadata overlays.

Appears in:

Field Description Default Validation
labels object (keys:string, values:string) Map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels		 Optional: {}
annotations object (keys:string, values:string) Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations		 Optional: {}

OpenAIConfig

Settings for the OpenAI LLM provider.

Appears in:

Field Description Default Validation
model ShortString Model name override, such as gpt-4o-mini.
If unset, the model name is taken from the request.		 MaxLength: 256
MinLength: 1
Optional: {}

OpenAIModeration

Appears in:

Field Description Default Validation
model string Moderation model to use. For example,
omni-moderation.		 Optional: {}
policies BackendSimple Policies for communicating with OpenAI. Optional: {}

OtlpAccessLog

Ships access logs to an OpenTelemetry-compatible backend via OTLP.

Appears in:

Field Description Default Validation
backendRef BackendObjectReference OTLP server to send access logs to.
Supported types: Service and AgentgatewayBackend.		 Required: {}
filter CELExpression CEL expression used to filter OTLP logs. A log
will only be exported if the expression evaluates to true.
If unset, the parent access log filter is used.		 MaxLength: 16384
MinLength: 1
Optional: {}
attributes LogTracingAttributes Customizations to the key-value pairs exported over OTLP.
If unset, the parent access log attributes are used.		 Optional: {}
protocol OTLPProtocol OTLP protocol variant to use. GRPC Optional: {}
path LongString OTLP/HTTP path to use. This is only applicable
when protocol is HTTP. If unset, this defaults to /v1/logs.		 MaxLength: 1024
MinLength: 1
Optional: {}

PolicyAncestorStatus

Appears in:

Field Description Default Validation
ancestorRef ParentReference The ancestor resource that this status entry describes. Required: {}
controllerName string The controller that wrote this status entry.
Example: example.net/gateway-controller.		 Required: {}
conditions Condition array Conditions for this policy's effect on the specified ancestor. MaxItems: 8
MinItems: 1
Optional: {}

PolicyInheritance

Underlying type: string

How a traffic policy affects policy inheritance across attachment specificity levels.

Appears in:

Field Description
Default PolicyInheritanceDefault allows the normal traffic policy merge order, where more-specific
policies may override fields from less-specific policies.
Override PolicyInheritanceOverride makes the policy authoritative for lower levels, excluding
more-specific traffic policies from the effective policy.

PolicyPhase

Underlying type: string

Appears in:

Field Description
PreRouting
PostRouting

PolicyStrategy

Appears in:

Field Description Default Validation
inheritance PolicyInheritance Controls whether less-specific traffic policies prevent more-specific traffic policies
from contributing to the effective policy.
This field is only valid on traffic policies. Frontend and backend policy merging does not use
inheritance.
When unset or set to Default, traffic policy fields are merged by specificity, with more-specific
attachment points such as routes and route rules able to override fields from less-specific
attachment points such as gateways and listeners.
In other words, this policy provides Defaults that can be overridden. For example, you may provide a Default
timeout policy for the entire Gateway that is overridden by specific routes.
When set to Override, this policy blocks traffic policies at more-specific attachment points from
being included in the effective policy. This is useful when a gateway-level policy must remain
authoritative for all routes below it.		 Optional: {}

PrefixMode

Underlying type: string

Appears in:

Field Description
Conditional Conditional prefixes tool and prompt names only when there are multiple targets.
Always Always prefixes tool and prompt names, even with a single target.
Never Never prefixes tool and prompt names; calls are routed by target lookup.
Names must be unique across targets.

PriorityGroup

Appears in:

Field Description Default Validation
providers NamedLLMProvider array LLM providers within this group. Each provider is treated equally in terms of priority,
with automatic weighting based on health.		 MaxItems: 16
MinItems: 1
Required: {}

ProcessingOptions

External processor request and response phase settings.

Appears in:

Field Description Default Validation
requestBodyMode BodySendMode How request bodies are sent to the external processor.
Buffered buffers the full body and returns an error if it exceeds 8KB.
BufferedPartial buffers up to 8KB and sends the buffered prefix if the
body exceeds that limit. Defaults to FullDuplexStreamed.		 FullDuplexStreamed Optional: {}
responseBodyMode BodySendMode How response bodies are sent to the external processor.
Buffered buffers the full body and returns an error if it exceeds 8KB.
BufferedPartial buffers up to 8KB and sends the buffered prefix if the
body exceeds that limit. Defaults to FullDuplexStreamed.		 FullDuplexStreamed Optional: {}
requestHeaderMode HeaderSendMode Whether request headers are sent to the external processor.
Defaults to Send.		 Send Optional: {}
responseHeaderMode HeaderSendMode Whether response headers are sent to the external processor.
Defaults to Send.		 Send Optional: {}
requestTrailerMode TrailerSendMode Whether request trailers are sent to the external processor.
Defaults to Send.		 Send Optional: {}
responseTrailerMode TrailerSendMode Whether response trailers are sent to the external processor.
Defaults to Send.		 Send Optional: {}
allowModeOverride boolean Allows ext_proc mode_override values from matching header responses to update
subsequent request/response processing phases for this exchange. Defaults to false.		 false Optional: {}

PromptCachingConfig

Automatic prompt caching for supported LLM providers. Currently only AWS Bedrock supports this feature (Claude 3+ and Nova models).

When enabled, the gateway automatically inserts cache points at strategic locations to reduce API costs. Bedrock charges lower rates for cached tokens (90% discount).

Example:

promptCaching:
  cacheSystem: true
  cacheMessages: true
  cacheTools: false

Cost savings example:

  • Without caching: 10,000 tokens × $3/MTok = $0.03
  • With caching (90% cached): 1,000 × $3/MTok + 9,000 × $0.30/MTok = $0.0057 (81% savings)

Appears in:

Field Description Default Validation
cacheSystem boolean Enables caching for system prompts.
Inserts a cache point after all system messages.		 true Optional: {}
cacheMessages boolean Enables caching for conversation messages.
Caches all messages in the conversation for cost savings.		 true Optional: {}
cacheTools boolean Enables caching for tool definitions.
Inserts a cache point after all tool specifications.		 false Optional: {}
minTokens integer Minimum estimated token count
before caching is enabled. Uses rough heuristic (word count × 1.3) to estimate tokens.
Bedrock requires at least 1,024 tokens for caching to be effective.		 1024 Minimum: 0
Optional: {}
cacheMessageOffset integer Shifts the message cache point further back in the
conversation. 0 (default) places it at the second-to-last message.
Higher values move it N additional messages towards the start, clamped
to bounds.		 0 Minimum: 0
Optional: {}

PromptGuardStreamingMode

Underlying type: string

Streaming prompt guard mode.

Appears in:

Field Description
Enabled Enable prompt guards for streaming responses and realtime websocket messages.

PromptguardRequest

Prompt guards to apply to requests sent by the client.

Validation:

  • ExactlyOneOf: [regex webhook openAIModeration bedrockGuardrails googleModelArmor]

Appears in:

Field Description Default Validation
response CustomResponse Custom response message to return to the client. If not specified, defaults to
The request was rejected due to inappropriate content.		 Optional: {}
regex Regex Regular expression (regex) matching for prompt guards and data masking. Optional: {}
webhook Webhook Webhook that receives requests for prompt guarding. Optional: {}
openAIModeration OpenAIModeration Passes prompt data through the OpenAI Moderations
endpoint.
See https://developers.openai.com/api/reference/resources/moderations for more information.		 Optional: {}
bedrockGuardrails BedrockGuardrails AWS Bedrock Guardrails settings for prompt
guarding.		 Optional: {}
googleModelArmor GoogleModelArmor Google Model Armor settings for prompt guarding. Optional: {}

PromptguardResponse

Prompt guards to apply to responses returned by the LLM provider.

Validation:

  • ExactlyOneOf: [regex webhook bedrockGuardrails googleModelArmor]

Appears in:

Field Description Default Validation
response CustomResponse Custom response message to return to the client. If not specified, defaults to
The response was rejected due to inappropriate content.		 Optional: {}
regex Regex Regular expression (regex) matching for prompt guards and data masking. Optional: {}
webhook Webhook Webhook that receives responses for prompt guarding. Optional: {}
bedrockGuardrails BedrockGuardrails AWS Bedrock Guardrails settings for prompt
guarding.		 Optional: {}
googleModelArmor GoogleModelArmor Google Model Armor settings for prompt guarding. Optional: {}

ProviderFormat

Underlying type: string

Provider-native LLM API format.

Appears in:

Field Description
Completions ProviderFormatCompletions is the OpenAI-compatible chat completions API.
Messages ProviderFormatMessages is the Anthropic-compatible messages API.
Responses ProviderFormatResponses is the OpenAI responses API.
Embeddings ProviderFormatEmbeddings is the OpenAI-compatible embeddings API.
AnthropicTokenCount ProviderFormatAnthropicTokenCount is the Anthropic token-count API.
Realtime ProviderFormatRealtime is the OpenAI-compatible realtime API.
Rerank ProviderFormatRerank is the Cohere-compatible rerank API.

ProviderFormatConfig

Provider-native LLM API format settings.

Appears in:

Field Description Default Validation
type ProviderFormat Provider-native API format. Required: {}
path LongString Default upstream path override for this format.
If unset, agentgateway uses the default path for the format.		 MaxLength: 1024
MinLength: 1
Optional: {}

ProxyProtocolMode

Underlying type: string

Appears in:

Field Description
Strict A valid PROXY header must be present. This is the default option.
Optional Accept either a PROXY header or plain downstream traffic.

ProxyProtocolVersion

Underlying type: string

Appears in:

Field Description
V1
V2
All

RateLimitDescriptor

Appears in:

Field Description Default Validation
entries RateLimitDescriptorEntry array Individual components that make up this descriptor. MaxItems: 16
MinItems: 1
Required: {}
unit RateLimitUnit Cost unit. If unspecified,
Requests is used.		 Optional: {}
cost CELExpression 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.		 MaxLength: 16384
MinLength: 1
Optional: {}

RateLimitDescriptorEntry

Entry in a rate limit descriptor.

Appears in:

Field Description Default Validation
name TinyString Name of the descriptor. MaxLength: 64
MinLength: 1
Required: {}
expression CELExpression 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.		 MaxLength: 16384
MinLength: 1
Required: {}

RateLimitUnit

Underlying type: string

Appears in:

Field Description
Tokens
Requests

RateLimits

Appears in:

Field Description Default Validation
local LocalRateLimit array Local rate limiting policy. ExactlyOneOf: [requests tokens]
MaxItems: 16
MinItems: 1
Optional: {}
global GlobalRateLimit Global rate limiting policy using an external service. Optional: {}

RateLimitsConditional

Appears in:

Field Description Default Validation
condition CELExpression CEL expression that must evaluate to true for this policy to execute. MaxLength: 16384
MinLength: 1
Optional: {}
policy RateLimits Policy to apply when the condition matches. Required: {}

RateLimitsOrConditional

Appears in:

Field Description Default Validation
local LocalRateLimit array Local rate limiting policy. ExactlyOneOf: [requests tokens]
MaxItems: 16
MinItems: 1
Optional: {}
global GlobalRateLimit Global rate limiting policy using an external service. Optional: {}
conditional RateLimitsConditional array 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.		 MaxItems: 16
MinItems: 1
Optional: {}

Regex

Regular expression matching for prompt guards and data masking.

Appears in:

Field Description Default Validation
matches LongString array Regex patterns to match against the request or response.
Matches and built-ins are additive.		 MaxLength: 1024
MinLength: 1
Optional: {}
builtins BuiltIn array Built-in regex patterns to match against the request or response.
Matches and built-ins are additive.		 Optional: {}
action Action The action to take if a regex pattern is matched in a request or response.
This setting applies only to request matches. PromptguardResponse
matches are always masked by default.
Defaults to Mask.		 Mask Optional: {}

RemoteJWKS

Appears in:

Field Description Default Validation
jwksPath string Path to the IdP jwks endpoint, relative to the root, commonly
".well-known/jwks.json".		 MaxLength: 2000
MinLength: 1
Required: {}
cacheDuration Duration 5m Optional: {}
backendRef BackendObjectReference Remote JWKS server to reach.
Supported types are Service and static Backend. An
AgentgatewayPolicy containing backend TLS config can then be attached
to the Service or Backend in order to set TLS options for a
connection to the remote jwks source.		 Required: {}

ResourceAdd

Appears in:

Field Description Default Validation
name ShortString MaxLength: 256
MinLength: 1
Required: {}
expression CELExpression MaxLength: 16384
MinLength: 1
Required: {}

Retry

Retry policy.

Appears in:

Field Description Default Validation
precondition CELExpression 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).		 MaxLength: 16384
MinLength: 1
Optional: {}
condition CELExpression 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.		 MaxLength: 16384
MinLength: 1
Optional: {}

RouteType

Underlying type: string

How the AI gateway should process incoming requests based on the URL path and the API format expected.

Appears in:

Field Description
Completions RouteTypeCompletions processes OpenAI /v1/chat/completions format requests.
Messages RouteTypeMessages processes Anthropic /v1/messages format requests.
Models RouteTypeModels handles the /v1/models endpoint.
Passthrough RouteTypePassthrough sends requests upstream as-is without LLM processing.
Detect RouteTypeDetect sends requests as-is but attempts to extract
request/response metadata for telemetry and rate limiting.
Responses RouteTypeResponses processes OpenAI /v1/responses format requests.
AnthropicTokenCount RouteTypeAnthropicTokenCount processes Anthropic
/v1/messages/count_tokens format requests.
Embeddings RouteTypeEmbeddings processes OpenAI /v1/embeddings format requests.
Realtime RouteTypeRealtime processes OpenAI /v1/realtime requests.
Rerank RouteTypeRerank processes Cohere /v2/rerank format requests.

SecretSelector

Appears in:

Field Description Default Validation
matchLabels object (keys:string, values:string) Labels that must be present on each selected Secret. Required: {}

SessionRouting

Underlying type: string

Appears in:

Field Description
Stateful Stateful mode creates an MCP session (via mcp-session-id) and
internally
ensures requests for that session are routed to a consistent backend replica.
Stateless

ShutdownSpec

Appears in:

Field Description Default Validation
min integer Minimum time (in seconds) to wait before allowing Agentgateway to
terminate. Refer to the CONNECTION_MIN_TERMINATION_DEADLINE
environment variable for details.		 Maximum: 3.1536e+07
Minimum: 0
Required: {}
max integer Maximum time (in seconds) to wait before allowing Agentgateway to
terminate. Refer to the TERMINATION_GRACE_PERIOD_SECONDS
environment variable for details.		 Maximum: 3.1536e+07
Minimum: 0
Required: {}

StaticBackend

Static backend endpoint, either TCP (host and port) or Unix Domain Socket.

Appears in:

Field Description Default Validation
host ShortString Host to connect to for TCP backends. MaxLength: 256
MinLength: 1
Optional: {}
port integer Port to connect to for TCP backends. Maximum: 65535
Minimum: 1
Optional: {}
unixPath string Filesystem path to a Unix Domain Socket. The gateway pod
must share a volume with the target (e.g., via emptyDir sidecar pattern).
Mutually exclusive with host/port.		 MinLength: 1
Optional: {}

TLSVersion

Underlying type: string

Appears in:

Field Description
1.2 agentgateway currently only supports TLS 1.2 and TLS 1.3.
1.3

Timeouts

Appears in:

Field Description Default Validation
request Duration Timeout for an individual request from the gateway to a backend. This covers the time from when
the request first starts being sent from the gateway to when the full response has been received from the backend.		 Optional: {}

Tracing

Appears in:

Field Description Default Validation
backendRef BackendObjectReference OTLP server to reach.
Supported types: Service and AgentgatewayBackend.		 Required: {}
protocol OTLPProtocol OTLP protocol variant to use. GRPC Optional: {}
path LongString OTLP path to use. This is only applicable when
protocol is HTTP. If unset, this defaults to /v1/traces.		 MaxLength: 1024
MinLength: 1
Optional: {}
attributes LogTracingAttributes Customizations to the key-value pairs that are
included in the trace.		 Optional: {}
resources ResourceAdd array Entity producing telemetry and resources
resources to be included in the trace.		 Optional: {}
randomSampling CELExpression Expression that determines the amount of random
sampling. Random sampling will initiate a new trace span if the incoming
request does not have a trace initiated already. This should evaluate to
a float between 0.0 and 1.0, or a boolean (true or false). If
unspecified, random sampling is disabled.		 MaxLength: 16384
MinLength: 1
Optional: {}
clientSampling CELExpression Expression that determines the amount of client
sampling. Client sampling determines whether to initiate a new trace
span if the incoming request does have a trace already. This should
evaluate to a float between 0.0 and 1.0, or a boolean (true or
false). If unspecified, client sampling is 100% enabled.		 MaxLength: 16384
MinLength: 1
Optional: {}
filter CELExpression Expression that determines whether a sampled span is exported.
This uses keep semantics: spans are exported only when the expression
evaluates to true. If unspecified, all sampled spans are exported.		 MaxLength: 16384
MinLength: 1
Optional: {}

Traffic

Appears in:

Field Description Default Validation
phase PolicyPhase 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.		 Optional: {}
transformation TransformationOrConditional Mutates and transforms requests and responses
before forwarding them to the destination.		 Optional: {}
extProc ExtProcOrConditional External processing configuration for the policy. Optional: {}
extAuth ExtAuthOrConditional 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.		 Optional: {}
rateLimit RateLimitsOrConditional Rate limiting configuration for the policy.
This limits the rate at which requests are processed.		 Optional: {}
cors CORS CORS configuration for the policy. Optional: {}
csrf CSRF Cross-Site Request Forgery (CSRF) policy for this traffic policy.
The CSRF policy has the following behavior:
* Safe methods (GET, HEAD, OPTIONS) are automatically allowed.
* Requests without Sec-Fetch-Site or Origin headers are assumed to
be same-origin or non-browser requests and are allowed.
* Otherwise, the Sec-Fetch-Site header is checked, with a fallback to
comparing the Origin header to the Host header.		 Optional: {}
headerModifiers HeaderModifiers Request and response header modification policy. Optional: {}
hostRewrite HostnameRewrite How to rewrite the Host header for requests.
If the HTTPRoute urlRewrite filter already specifies a host rewrite,
this setting is ignored.		 Optional: {}
timeouts Timeouts Request timeouts.
It is applicable to HTTPRoute resources and ignored for other targeted
kinds.		 Optional: {}
retry Retry Retry policy. Optional: {}
authorization Authorization Access rules based on roles and
permissions.
If multiple authorization rules are applied across different policies, at the same or different attachment points,
all rules are merged.		 Optional: {}
jwtAuthentication JWTAuthentication Authenticates users based on JWT tokens. Optional: {}
basicAuthentication BasicAuthentication Authenticates users based on the Basic
authentication scheme (RFC 7617), where a username and password are
encoded in the request.		 ExactlyOneOf: [users secretRef]
Optional: {}
apiKeyAuthentication APIKeyAuthentication Authenticates users based on a configured API
key.		 ExactlyOneOf: [secretRef secretSelector configMapSelector]
Optional: {}
directResponse DirectResponseOrConditional Sends a direct response to the
client.		 Optional: {}
buffer Buffer Buffers request and response bodies. Buffered bodies are accumulated in memory
by the proxy until completion before being forwarded. This changes the proxies default behavior, which streams bodies.
Warning: large bodies can lead to excessive memory usage in the proxy. Utilize with care, or with strict limits.		 Optional: {}

TrailerSendMode

Underlying type: string

Whether HTTP trailers are delivered to the external processor.

Appears in:

Field Description
Skip TrailerSendModeSkip does not send trailers to the external processor.
Send TrailerSendModeSend sends trailers to the external processor.

Transform

Appears in:

Field Description Default Validation
set HeaderTransformation array Headers to set and the values to use. MaxItems: 16
MinItems: 1
Optional: {}
add HeaderTransformation array 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.		 MaxItems: 16
MinItems: 1
Optional: {}
remove HeaderName array Header names to remove from the request or
response.		 MaxItems: 16
MaxLength: 256
MinItems: 1
MinLength: 1
Pattern: ^:?[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Optional: {}
body CELExpression HTTP body transformation. MaxLength: 16384
MinLength: 1
Optional: {}
metadata object (keys:string, values:CELExpression) Refer to Kubernetes API documentation for fields of metadata. MaxProperties: 16
MinProperties: 1
Optional: {}

Transformation

Appears in:

Field Description Default Validation
request Transform Request transformation settings. Optional: {}
response Transform Response transformation settings. Optional: {}

TransformationConditional

Appears in:

Field Description Default Validation
condition CELExpression CEL expression that must evaluate to true for this policy to execute. MaxLength: 16384
MinLength: 1
Optional: {}
policy Transformation Policy to apply when the condition matches. Required: {}

TransformationOrConditional

Appears in:

Field Description Default Validation
request Transform Request transformation settings. Optional: {}
response Transform Response transformation settings. Optional: {}
conditional TransformationConditional array 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.		 MaxItems: 16
MinItems: 1
Optional: {}

VertexAIConfig

Settings for the Vertex AI LLM provider.

Appears in:

Field Description Default Validation
model ShortString Model name override, such as gpt-4o-mini.
If unset, the model name is taken from the request.		 MaxLength: 256
MinLength: 1
Optional: {}
projectId TinyString The ID of the Google Cloud Project that you use for the Vertex AI. MaxLength: 64
MinLength: 1
Required: {}
region TinyString The location of the Google Cloud Project that you use for the Vertex AI.
Special values: global uses the global endpoint, while us and eu use restricted
multi-region endpoints. Other values are treated as regional locations.
Defaults to global if not specified.		 global MaxLength: 64
MinLength: 1
Optional: {}

Webhook

Webhook for prompt guard request or response checks.

Appears in:

Field Description Default Validation
backendRef BackendObjectReference Webhook server to reach.
Supported types: Service and Backend.		 Required: {}
forwardHeaderMatches HTTPHeaderMatch array HTTP header matches used to select the headers to forward to the webhook.
Request headers are used when forwarding requests and response headers
are used when forwarding responses.
By default, no headers are forwarded.		 Optional: {}
failureMode FailureMode Behavior when the webhook guardrail is unavailable
or returns an error. FailOpen allows the request to continue.
FailClosed (default) rejects the request.		 Optional: {}

Shared Types

The following types are defined in the shared package and used across multiple APIs.

LongString

Underlying type: string

Validation:

  • MinLength=1
  • MaxLength=1024

PolicyAncestorStatus

Field Type Description
ancestorRef gwv1.ParentReference The ancestor resource that this status entry describes. Required.
controllerName string The controller that wrote this status entry. Example: example.net/gateway-controller. Required.
conditions []metav1.Condition Conditions for this policy's effect on the specified ancestor.

PolicyStatus

Field Type Description
conditions []metav1.Condition The current condition state for the policy.
ancestors []PolicyAncestorStatus Status for each ancestor that is affected by this policy. Required.

SNI

Underlying type: string

Validation:

  • MinLength=1
  • MaxLength=253
  • Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

ShortString

Underlying type: string

Validation:

  • MinLength=1
  • MaxLength=256

TinyString

Underlying type: string

Validation:

  • MinLength=1
  • MaxLength=64