On this page

Kgateway API

Review the kgateway API reference docs.

The Gloo Gateway API is a superset of the kgateway project’s API.

Packages

gateway.kgateway.dev/v1alpha1

gateway.kgateway.dev/v1alpha1

Resource Types

Backend
BackendConfigPolicy
DirectResponse
GatewayExtension
GatewayParameters
HTTPListenerPolicy
TrafficPolicy

AIBackend

AIBackend specifies the AI backend configuration

Appears in:

BackendSpec

Field	Description	Default	Validation
`llm` LLMProvider	The LLM configures the AI gateway to use a single LLM provider backend.
`priorityGroups` PriorityGroup array	PriorityGroups specifies a list of 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: yaml<br />priorityGroups:<br /> - providers:<br /> - azureOpenai:<br /> deploymentName: gpt-4o-mini<br /> apiVersion: 2024-02-15-preview<br /> endpoint: ai-gateway.openai.azure.com<br /> authToken:<br /> secretRef:<br /> name: azure-secret<br /> namespace: kgateway-system<br /> - providers:<br /> - azureOpenai:<br /> deploymentName: gpt-4o-mini-2<br /> apiVersion: 2024-02-15-preview<br /> endpoint: ai-gateway-2.openai.azure.com<br /> authToken:<br /> secretRef:<br /> name: azure-secret-2<br /> namespace: kgateway-system<br /> TODO: enable this rule when we don’t need to support older k8s versions where this rule breaks // +kubebuilder:validation:XValidation:message=“provider names must be unique across groups”,rule=“self.map(pg, pg.providers.map(pp, pp.name)).map(p, self.map(pg, pg.providers.map(pp, pp.name)).filter(cp, cp != p).exists(cp, p.exists(pn, pn in cp))).exists(p, !p)”		MaxItems: 32 MinItems: 1

AIPolicy

AIPolicy config is used to configure the behavior of the LLM provider on the level of individual routes. These route settings, such as prompt enrichment, retrieval augmented generation (RAG), and semantic caching, are applicable only for routes that send requests to an LLM provider backend.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`promptEnrichment` AIPromptEnrichment	Enrich 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.
`promptGuard` AIPromptGuard	Set up prompt guards to 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.
`defaults` FieldDefault array	Provide defaults to merge with user input fields. Defaults do not override the user input fields, unless you explicitly set `override` to `true`.
`modelAliases` object (keys:string, values:string)	ModelAliases 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.

AIPromptEnrichment

AIPromptEnrichment defines the config to enrich 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: kgateway-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:

AIPolicy

Field	Description	Default	Validation
`prepend` Message array	A list of messages to be prepended to the prompt sent by the client.
`append` Message array	A list of messages to be appended to the prompt sent by the client.

AIPromptGuard

AIPromptGuard configures a prompt guards to 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:
	  customResponse:
	    message: "Rejected due to inappropriate content"
	  regex:
	    action: REJECT
	    matches:
	    - pattern: "credit card"
	      name: "CC"
	response:
	  regex:
	    builtins:
	    - CREDIT_CARD
	    action: MASK

Appears in:

AIPolicy

Field	Description	Default	Validation
`request` PromptguardRequest	Prompt guards to apply to requests sent by the client.
`response` PromptguardResponse	Prompt guards to apply to responses returned by the LLM provider.

AWSGuardrailConfig

Appears in:

BedrockConfig

Field	Description	Default	Validation
`identifier` string	GuardrailIdentifier is the identifier of the Guardrail policy to use for the backend.		MinLength: 1
`version` string	GuardrailVersion is the version of the Guardrail policy to use for the backend.		MinLength: 1

AWSLambdaPayloadTransformMode

Underlying type: string

AWSLambdaPayloadTransformMode defines the transformation mode for the payload in the request before it is sent to the AWS Lambda function.

Validation:

Enum: [None Envoy]

Appears in:

AwsLambda

Field	Description
`None`	AWSLambdaPayloadTransformNone indicates that the payload will not be transformed using Envoy’s built-in transformation before it is sent to the Lambda function. Note: Transformation policies configured on the route will still apply.
`Envoy`	AWSLambdaPayloadTransformEnvoy indicates that the payload will be transformed using Envoy’s built-in transformation. Refer to https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_lambda_filter#configuration-as-a-listener-filter for more details on how Envoy transforms the payload.

AccessLog

AccessLog represents the top-level access log configuration.

Appears in:

HTTPListenerPolicySpec

Field	Description	Validation
`fileSink` FileSink	Output access logs to local file
`grpcService` AccessLogGrpcService	Send access logs to gRPC service
`openTelemetry` OpenTelemetryAccessLogService	Send access logs to an OTel collector
`filter` AccessLogFilter	Filter access logs configuration	MaxProperties: 1 MinProperties: 1

AccessLogFilter

AccessLogFilter represents the top-level filter structure. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-accesslogfilter

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

AccessLog

Field	Description	Default	Validation
`andFilter` FilterType array	Performs a logical “and” operation on the result of each individual filter. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-andfilter		MaxProperties: 1 MinItems: 2 MinProperties: 1
`orFilter` FilterType array	Performs a logical “or” operation on the result of each individual filter. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-orfilter		MaxProperties: 1 MinItems: 2 MinProperties: 1

AccessLogGrpcService

AccessLogGrpcService represents the gRPC service configuration for access logs. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto#envoy-v3-api-msg-extensions-access-loggers-grpc-v3-httpgrpcaccesslogconfig

Appears in:

AccessLog

Field	Description	Validation
`backendRef` BackendRef	The backend gRPC service. Can be any type of supported backend (Kubernetes Service, kgateway Backend, etc..)
`authority` string	The :authority header in the grpc request. If this field is not set, the authority header value will be cluster_name. Note that this authority does not override the SNI. The SNI is provided by the transport socket of the cluster.
`maxReceiveMessageLength` integer	Maximum gRPC message size that is allowed to be received. If a message over this limit is received, the gRPC stream is terminated with the RESOURCE_EXHAUSTED error. Defaults to 0, which means unlimited.	Minimum: 1
`skipEnvoyHeaders` boolean	This provides gRPC client level control over envoy generated headers. If false, the header will be sent but it can be overridden by per stream option. If true, the header will be removed and can not be overridden by per stream option. Default to false.
`timeout` Duration	The timeout for the gRPC request. This is the timeout for a specific request
`initialMetadata` HeaderValue array	Additional metadata to include in streams initiated to the GrpcService. This can be used for scenarios in which additional ad hoc authorization headers (e.g. x-foo-bar: baz-key) are to be injected
`retryPolicy` RetryPolicy	Indicates the retry policy for re-establishing the gRPC stream. If max interval is not provided, it will be set to ten times the provided base interval
`logName` string	name of log stream
`additionalRequestHeadersToLog` string array	Additional request headers to log in the access log
`additionalResponseHeadersToLog` string array	Additional response headers to log in the access log
`additionalResponseTrailersToLog` string array	Additional response trailers to log in the access log

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:

Regex

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

Agentgateway

Agentgateway configures the agentgateway dataplane integration to be enabled if the agentgateway GatewayClass is used.

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`enabled` boolean	Whether to enable the extension.
`logLevel` string	Log level for the agentgateway. Defaults to info. Levels include “trace”, “debug”, “info”, “error”, “warn”. See: https://docs.rs/tracing/latest/tracing/struct.Level.html
`image` Image	The agentgateway container image. See https://kubernetes.io/docs/concepts/containers/images for details. Default values, which may be overridden individually: registry: ghcr.io/agentgateway repository: agentgateway tag: pullPolicy: IfNotPresent
`securityContext` SecurityContext	The security context for this container. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#securitycontext-v1-core for details.
`resources` ResourceRequirements	The compute resources required by this container. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for details.
`env` EnvVar array	The container environment variables.
`customConfigMapName` string	Name of the custom configmap to use instead of the default generated one. When set, the agent gateway will use this configmap instead of creating the default one. The configmap must contain a ‘config.yaml’ key with the agent gateway configuration.
`extraVolumeMounts` VolumeMount array	Additional volume mounts to add to the container. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#volumemount-v1-core for details.

AiExtension

Configuration for the AI extension.

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`enabled` boolean	Whether to enable the extension.
`image` Image	The extension’s container image. See https://kubernetes.io/docs/concepts/containers/images for details.
`securityContext` SecurityContext	The security context for this container. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#securitycontext-v1-core for details.
`resources` ResourceRequirements	The compute resources required by this container. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for details.
`env` EnvVar array	The extension’s container environment variables.
`ports` ContainerPort array	The extension’s container ports.
`stats` AiExtensionStats	Additional stats config for AI Extension. This config can be useful for adding custom labels to the request metrics. Example: `yaml<br />stats:<br /> customLabels:<br /> - name: "subject"<br /> metadataNamespace: "envoy.filters.http.jwt_authn"<br /> metadataKey: "principal:sub"<br /> - name: "issuer"<br /> metadataNamespace: "envoy.filters.http.jwt_authn"<br /> metadataKey: "principal:iss"<br />`
`tracing` AiExtensionTrace	Additional OTel tracing config for AI Extension.

AiExtensionStats

Appears in:

AiExtension

Field	Description	Default	Validation
`customLabels` CustomLabel array	Set of custom labels to be added to the request metrics. These will be added on each request which goes through the AI Extension.

AiExtensionTrace

AiExtensionTrace defines the tracing configuration for the AI extension

Appears in:

AiExtension

Field	Description	Validation
`endpoint` AbsoluteURI	EndPoint specifies the URL of the OTLP Exporter for traces. Example: “http://my-otel-collector.svc.cluster.local:4317” https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_endpoint
`sampler` OTelTracesSampler	Sampler defines the sampling strategy for OpenTelemetry traces. Sampling helps in reducing the volume of trace data by selectively recording only a subset of traces. https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler
`timeout` Duration	OTLPTimeout specifies timeout configurations for OTLP (OpenTelemetry Protocol) exports. It allows setting general and trace-specific timeouts for sending data. https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_timeout
`protocol` OTLPTracesProtocolType	OTLPProtocol specifies the protocol to be used for OTLP exports. This determines how tracing data is serialized and transported (e.g., gRPC, HTTP/Protobuf). https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_protocol	Enum: [grpc http/protobuf http/json]

AlwaysOnConfig

Underlying type: struct{}

AlwaysOnConfig specified the AlwaysOn samplerc

Appears in:

Sampler

AnthropicConfig

AnthropicConfig settings for the Anthropic LLM provider.

Appears in:

LLMProvider
NamedLLMProvider

Field	Description	Default	Validation
`authToken` SingleAuthToken	The authorization token that the AI gateway uses to access the Anthropic API. This token is automatically sent in the `x-api-key` header of the request.
`apiVersion` string	Optional: A version header to pass to the Anthropic API. For more information, see the Anthropic API versioning docs.
`model` string	Optional: Override the model name. If unset, the model name is taken from the request. This setting can be useful when testing model failover scenarios.

AnyValue

AnyValue is used to represent any type of attribute value. AnyValue may contain a primitive value such as a string or integer or it may contain an arbitrary nested object containing arrays, key-value lists and primitives. This is limited to string and nested values as OTel only supports them

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

AnyValue
KeyAnyValue

Field	Description	Default	Validation
`stringValue` string
`arrayValue` AnyValue array	TODO: Add support for ArrayValue && KvListValue		MaxProperties: 1 MinProperties: 1

AppProtocol

Underlying type: string

AppProtocol defines the application protocol to use when communicating with the backend.

Validation:

Enum: [http2 grpc grpc-web kubernetes.io/h2c kubernetes.io/ws]

Appears in:

StaticBackend

Field	Description
`http2`	AppProtocolHttp2 is the http2 app protocol.
`grpc`	AppProtocolGrpc is the grpc app protocol.
`grpc-web`	AppProtocolGrpcWeb is the grpc-web app protocol.
`kubernetes.io/h2c`	AppProtocolKubernetesH2C is the kubernetes.io/h2c app protocol.
`kubernetes.io/ws`	AppProtocolKubernetesWs is the kubernetes.io/ws app protocol.

AuthHeader

AuthHeader allows customization of the default Authorization header sent to the LLM Provider. The default header is Authorization: Bearer <token>. HeaderName can change the Authorization header name and Prefix can change the Bearer prefix

Appears in:

LLMProvider
NamedLLMProvider

Field	Description	Default	Validation
`prefix` string	Prefix specifies the prefix to use in the Authorization header.		MinLength: 1
`headerName` string	HeaderName specifies the name of the header to use for authorization.		MinLength: 1

AuthorizationPolicyAction

Underlying type: string

AuthorizationPolicyAction defines the action to take when the RBACPolicies matches.

Appears in:

RBAC

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

AwsAuth

AwsAuth specifies the authentication method to use for the backend.

Appears in:

AwsBackend
BedrockConfig

Field	Description	Default	Validation
`type` AwsAuthType	Type specifies the authentication method to use for the backend.		Enum: [Secret]
`secretRef` LocalObjectReference	SecretRef references a Kubernetes Secret containing the AWS credentials. The Secret must have keys “accessKey”, “secretKey”, and optionally “sessionToken”.

AwsAuthType

Underlying type: string

AwsAuthType specifies the authentication method to use for the backend.

Appears in:

AwsAuth

Field	Description
`Secret`	AwsAuthTypeSecret uses credentials stored in a Kubernetes Secret.

AwsBackend

AwsBackend is the AWS backend configuration.

Appears in:

BackendSpec

Field	Description	Default	Validation
`lambda` AwsLambda	Lambda configures the AWS lambda service.
`accountId` string	AccountId is the AWS account ID to use for the backend.		MaxLength: 12 MinLength: 1 Pattern: `^[0-9]\{12\}$`
`auth` AwsAuth	Auth specifies an explicit AWS authentication method for the backend. When omitted, the following credential providers are tried in order, stopping when one of them returns an access key ID and a secret access key (the session token is optional): 1. Environment variables: when the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN are set. 2. AssumeRoleWithWebIdentity API call: when the environment variables AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN are set. 3. EKS Pod Identity: when the environment variable AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE is set. See the Envoy docs for more info: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_request_signing_filter#credentials
`region` string	Region is the 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-]+$`

AwsLambda

AwsLambda configures the AWS lambda service.

Appears in:

AwsBackend

Field	Description	Default	Validation
`endpointURL` string	EndpointURL is the URL or domain for the Lambda service. This is primarily useful for testing and development purposes. When omitted, the default lambda hostname will be used.		MaxLength: 2048 Pattern: `^https?://[-a-zA-Z0-9@:%.+~#?&/=]+$`
`functionName` string	FunctionName is the name of the Lambda function to invoke.		Pattern: `^[A-Za-z0-9-_]\{1,140\}$`
`invocationMode` string	InvocationMode defines how to invoke the Lambda function. Defaults to Sync.	Sync	Enum: [Sync Async]
`qualifier` string	Qualifier is the alias or version for the Lambda function. Valid values include a numeric version (e.g. “1”), an alias name (alphanumeric plus “-” or “_”), or the special literal “$LATEST”.	$LATEST	Pattern: `^(\$LATEST\|[0-9]+\|[A-Za-z0-9-_]\{1,128\})$`
`payloadTransformMode` AWSLambdaPayloadTransformMode	PayloadTransformation specifies payload transformation mode before it is sent to the Lambda function. Defaults to Envoy.	Envoy	Enum: [None Envoy]

AzureOpenAIConfig

AzureOpenAIConfig settings for the Azure OpenAI LLM provider.

Appears in:

LLMProvider
NamedLLMProvider

Field	Description	Validation
`authToken` SingleAuthToken	The authorization token that the AI gateway uses to access the Azure OpenAI API. This token is automatically sent in the `api-key` header of the request.
`endpoint` string	The endpoint for the Azure OpenAI API to use, such as `my-endpoint.openai.azure.com`. If the scheme is included, it is stripped.	MinLength: 1
`deploymentName` string	The name of the Azure OpenAI model deployment to use. For more information, see the Azure OpenAI model docs.	MinLength: 1
`apiVersion` string	The version of the Azure OpenAI API to use. For more information, see the Azure OpenAI API version reference.	MinLength: 1

Backend

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`Backend`
`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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` BackendSpec
`status` BackendStatus

BackendConfigPolicy

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`BackendConfigPolicy`
`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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` BackendConfigPolicySpec
`status` PolicyStatus

BackendConfigPolicySpec

BackendConfigPolicySpec defines the desired state of BackendConfigPolicy.

Appears in:

BackendConfigPolicy

Field	Description	Validation
`targetRefs` LocalPolicyTargetReference array	TargetRefs specifies the target references to attach the policy to.	MaxItems: 16 MinItems: 1
`targetSelectors` LocalPolicyTargetSelector array	TargetSelectors specifies the target selectors to select resources to attach the policy to.
`connectTimeout` Duration	The timeout for new network connections to hosts in the cluster.
`perConnectionBufferLimitBytes` integer	Soft limit on the size of the cluster’s connections read and write buffers. If unspecified, an implementation-defined default is applied (1MiB).	Minimum: 0
`tcpKeepalive` TCPKeepalive	Configure OS-level TCP keepalive checks.
`commonHttpProtocolOptions` CommonHttpProtocolOptions	Additional options when handling HTTP requests upstream, applicable to both HTTP1 and HTTP2 requests.
`http1ProtocolOptions` Http1ProtocolOptions	Additional options when handling HTTP1 requests upstream.
`http2ProtocolOptions` Http2ProtocolOptions	Http2ProtocolOptions contains the options necessary to configure HTTP/2 backends. Note: Http2ProtocolOptions can only be applied to HTTP/2 backends. See Envoy documentation for more details.
`tls` TLS	TLS contains the options necessary to configure a backend to use TLS origination. See Envoy documentation for more details.
`loadBalancer` LoadBalancer	LoadBalancer contains the options necessary to configure the load balancer.
`healthCheck` HealthCheck	HealthCheck contains the options necessary to configure the health check.
`outlierDetection` OutlierDetection	OutlierDetection contains the options necessary to configure passive health checking.

BackendSpec

BackendSpec defines the desired state of Backend.

Appears in:

Backend

Field	Description	Validation
`type` BackendType	Type indicates the type of the backend to be used.	Enum: [AI AWS Static DynamicForwardProxy MCP]
`ai` AIBackend	AI is the AI backend configuration.
`aws` AwsBackend	Aws is the AWS backend configuration. The Aws backend type is only supported with envoy-based gateways, it is not supported in agentgateway.
`static` StaticBackend	Static is the static backend configuration.
`dynamicForwardProxy` DynamicForwardProxyBackend	DynamicForwardProxy is the dynamic forward proxy backend configuration. The DynamicForwardProxy backend type is only supported with envoy-based gateways, it is not supported in agentgateway.
`mcp` MCP	MCP is the mcp backend configuration. The MCP backend type is only supported with agentgateway.

BackendStatus

BackendStatus defines the observed state of Backend.

Appears in:

Backend

Field	Description	Default	Validation
`conditions` Condition array	Conditions is the list of conditions for the backend.		MaxItems: 8

BackendType

Underlying type: string

BackendType indicates the type of the backend.

Appears in:

BackendSpec

Field	Description
`AI`	BackendTypeAI is the type for AI backends.
`AWS`	BackendTypeAWS is the type for AWS backends.
`Static`	BackendTypeStatic is the type for static backends.
`DynamicForwardProxy`	BackendTypeDynamicForwardProxy is the type for dynamic forward proxy backends.
`MCP`	BackendTypeMCP is the type for MCP backends.

BedrockConfig

Appears in:

LLMProvider
NamedLLMProvider

Field	Description	Default	Validation
`auth` AwsAuth	Auth specifies an explicit AWS authentication method for the backend. When omitted, the following credential providers are tried in order, stopping when one of them returns an access key ID and a secret access key (the session token is optional): 1. Environment variables: when the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN are set. 2. AssumeRoleWithWebIdentity API call: when the environment variables AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN are set. 3. EKS Pod Identity: when the environment variable AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE is set. See the Envoy docs for more info: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_request_signing_filter#credentials
`model` string	Optional: Override the model ID. If unset, the model is taken from the request. See https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html		MinLength: 1
`region` string	Region is the 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-]+$`
`guardrail` AWSGuardrailConfig	Guardrail configures the 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.

BodyParseBehavior

Underlying type: string

BodyparseBehavior defines how the body should be parsed If set to json and the body is not json then the filter will not perform the transformation.

Validation:

Enum: [AsString AsJson]

Appears in:

BodyTransformation

Field	Description
`AsString`	BodyParseBehaviorAsString will parse the body as a string.
`AsJson`	BodyParseBehaviorAsJSON will parse the body as a json object.

BodyTransformation

BodyTransformation controls how the body should be parsed and transformed.

Appears in:

Transform

Field	Description	Default	Validation
`parseAs` BodyParseBehavior	ParseAs defines what auto formatting should be applied to the body. This can make interacting with keys within a json body much easier if AsJson is selected. This field is only supported for kgateway (Envoy) data plane and is ignored by agentgateway. For agentgateway, use json(request.body) or json(response.body) directly in CEL expressions.	AsString	Enum: [AsString AsJson]
`value` Template	Value is the template to apply to generate the output value for the body. Inja templates are supported for Envoy-based data planes only. CEL expressions are supported for agentgateway data plane only. The system will auto-detect the appropriate template format based on the data plane.

Buffer

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`maxRequestSize` Quantity	MaxRequestSize sets the maximum size in bytes of a message body to buffer. Requests exceeding this size will receive HTTP 413. Example format: “1Mi”, “512Ki”, “1Gi”
`disable` PolicyDisable	Disable the buffer filter. Can be used to disable buffer policies applied at a higher level in the config hierarchy.

BuiltIn

Underlying type: string

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

Validation:

Enum: [SSN CREDIT_CARD PHONE_NUMBER EMAIL]

Appears in:

Regex

Field	Description
`SSN`	Default regex matching for Social Security numbers.
`CREDIT_CARD`	Default regex matching for credit card numbers.
`PHONE_NUMBER`	Default regex matching for phone numbers.
`EMAIL`	Default regex matching for email addresses.

CELFilter

CELFilter filters requests based on Common Expression Language (CEL).

Appears in:

FilterType

Field	Description	Default	Validation
`match` string	The CEL expressions to evaluate. AccessLogs are only emitted when the CEL expressions evaluates to true. see: https://www.envoyproxy.io/docs/envoy/v1.33.0/xds/type/v3/cel.proto.html#common-expression-language-cel-proto

CSRFPolicy

CSRFPolicy can be used to set percent of requests for which the CSRF filter is enabled, enable shadow-only mode where policies will be evaluated and tracked, but not enforced and add additional source origins that will be allowed in addition to the destination origin.

Dataplane Support:

Envoy: Supports PercentageEnabled, PercentageShadowed, and AdditionalOrigins
Agentgateway: Only supports AdditionalOrigins (PercentageEnabled and PercentageShadowed are ignored)

Appears in:

TrafficPolicySpec

Field	Description	Validation
`percentageEnabled` integer	Specifies the percentage of requests for which the CSRF filter is enabled. Envoy: Supported Agentgateway: Not supported (ignored)	Maximum: 100 Minimum: 0
`percentageShadowed` integer	Specifies that CSRF policies will be evaluated and tracked, but not enforced. Envoy: Supported Agentgateway: Not supported (ignored)	Maximum: 100 Minimum: 0
`additionalOrigins` StringMatcher array	Specifies additional source origins that will be allowed in addition to the destination origin. Envoy: Supported Agentgateway: Supported	MaxItems: 16

CommonAccessLogGrpcService

Common configuration for gRPC access logs. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto#envoy-v3-api-msg-extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig

Appears in:

AccessLogGrpcService
OpenTelemetryAccessLogService

Field	Description	Validation
`backendRef` BackendRef	The backend gRPC service. Can be any type of supported backend (Kubernetes Service, kgateway Backend, etc..)
`authority` string	The :authority header in the grpc request. If this field is not set, the authority header value will be cluster_name. Note that this authority does not override the SNI. The SNI is provided by the transport socket of the cluster.
`maxReceiveMessageLength` integer	Maximum gRPC message size that is allowed to be received. If a message over this limit is received, the gRPC stream is terminated with the RESOURCE_EXHAUSTED error. Defaults to 0, which means unlimited.	Minimum: 1
`skipEnvoyHeaders` boolean	This provides gRPC client level control over envoy generated headers. If false, the header will be sent but it can be overridden by per stream option. If true, the header will be removed and can not be overridden by per stream option. Default to false.
`timeout` Duration	The timeout for the gRPC request. This is the timeout for a specific request
`initialMetadata` HeaderValue array	Additional metadata to include in streams initiated to the GrpcService. This can be used for scenarios in which additional ad hoc authorization headers (e.g. x-foo-bar: baz-key) are to be injected
`retryPolicy` RetryPolicy	Indicates the retry policy for re-establishing the gRPC stream. If max interval is not provided, it will be set to ten times the provided base interval
`logName` string	name of log stream

CommonGrpcService

Common gRPC service configuration created by setting `envoy_grpc“ as the gRPC client Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/grpc_service.proto#envoy-v3-api-msg-config-core-v3-grpcservice Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/grpc_service.proto#envoy-v3-api-msg-config-core-v3-grpcservice-envoygrpc

Appears in:

AccessLogGrpcService
CommonAccessLogGrpcService
OpenTelemetryTracingConfig

Field	Description	Validation
`backendRef` BackendRef	The backend gRPC service. Can be any type of supported backend (Kubernetes Service, kgateway Backend, etc..)
`authority` string	The :authority header in the grpc request. If this field is not set, the authority header value will be cluster_name. Note that this authority does not override the SNI. The SNI is provided by the transport socket of the cluster.
`maxReceiveMessageLength` integer	Maximum gRPC message size that is allowed to be received. If a message over this limit is received, the gRPC stream is terminated with the RESOURCE_EXHAUSTED error. Defaults to 0, which means unlimited.	Minimum: 1
`skipEnvoyHeaders` boolean	This provides gRPC client level control over envoy generated headers. If false, the header will be sent but it can be overridden by per stream option. If true, the header will be removed and can not be overridden by per stream option. Default to false.
`timeout` Duration	The timeout for the gRPC request. This is the timeout for a specific request
`initialMetadata` HeaderValue array	Additional metadata to include in streams initiated to the GrpcService. This can be used for scenarios in which additional ad hoc authorization headers (e.g. x-foo-bar: baz-key) are to be injected
`retryPolicy` RetryPolicy	Indicates the retry policy for re-establishing the gRPC stream. If max interval is not provided, it will be set to ten times the provided base interval

CommonHttpProtocolOptions

CommonHttpProtocolOptions are options that are applicable to both HTTP1 and HTTP2 requests. See Envoy documentation for more details.

Appears in:

BackendConfigPolicySpec

Field	Description	Validation
`idleTimeout` Duration	The idle timeout for connections. The idle timeout is defined as the period in which there are no active requests. When the idle timeout is reached the connection will be closed. If the connection is an HTTP/2 downstream connection a drain sequence will occur prior to closing the connection. Note that request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. If not specified, this defaults to 1 hour. To disable idle timeouts explicitly set this to 0. Disabling this timeout has a highly likelihood of yielding connection leaks due to lost TCP FIN packets, etc.
`maxHeadersCount` integer	Specifies the maximum number of headers that the connection will accept. If not specified, the default of 100 is used. Requests that exceed this limit will receive a 431 response for HTTP/1.x and cause a stream reset for HTTP/2.	Minimum: 0
`maxStreamDuration` Duration	Total duration to keep alive an HTTP request/response stream. If the time limit is reached the stream will be reset independent of any other timeouts. If not specified, this value is not set.
`maxRequestsPerConnection` integer	Maximum requests for a single upstream connection. If set to 0 or unspecified, defaults to unlimited.	Minimum: 0

ComparisonFilter

Underlying type: struct{Op Op “json:"op,omitempty"”; Value int32 “json:"value,omitempty"”}

ComparisonFilter represents a filter based on a comparison. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-comparisonfilter

Appears in:

DurationFilter
StatusCodeFilter

Underlying type: struct{Name string “json:"name"”; Path *string “json:"path,omitempty"”; TTL *k8s.io/apimachinery/pkg/apis/meta/v1.Duration “json:"ttl,omitempty"”; Secure *bool “json:"secure,omitempty"”; HttpOnly *bool “json:"httpOnly,omitempty"”; SameSite *string “json:"sameSite,omitempty"”}

Appears in:

HashPolicy

CorsPolicy

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`disable` PolicyDisable	Disable the CORS filter. Can be used to disable CORS policies applied at a higher level in the config hierarchy.

CustomAttribute

Describes attributes for the active span. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#envoy-v3-api-msg-type-tracing-v3-customtag

Validation:

MaxProperties: 2
MinProperties: 1

Appears in:

Tracing

Field	Description	Default	Validation
`name` string	The name of the attribute
`literal` CustomAttributeLiteral	A literal attribute value.
`environment` CustomAttributeEnvironment	An environment attribute value.
`requestHeader` CustomAttributeHeader	A request header attribute value.
`metadata` CustomAttributeMetadata	Refer to Kubernetes API documentation for fields of `metadata`.

CustomAttributeEnvironment

Environment type attribute with environment name and default value. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#type-tracing-v3-customtag-environment

Appears in:

CustomAttribute

Field	Description	Default	Validation
`name` string	Environment variable name to obtain the value to populate the attribute value.
`defaultValue` string	When the environment variable is not found, the attribute value will be populated with this default value if specified, otherwise no attribute will be populated.

CustomAttributeHeader

Header type attribute with header name and default value. https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#type-tracing-v3-customtag-header

Appears in:

CustomAttribute

Field	Description	Default	Validation
`name` string	Header name to obtain the value to populate the attribute value.
`defaultValue` string	When the header does not exist, the attribute value will be populated with this default value if specified, otherwise no attribute will be populated.

CustomAttributeLiteral

Literal type attribute with a static value. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#type-tracing-v3-customtag-literal

Appears in:

CustomAttribute

Field	Description	Default	Validation
`value` string	Static literal value to populate the attribute value.

CustomAttributeMetadata

Metadata type attribute using MetadataKey to retrieve the protobuf value from Metadata, and populate the attribute value with the canonical JSON representation of it. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#type-tracing-v3-customtag-metadata

Appears in:

CustomAttribute

Field	Description	Validation
`kind` MetadataKind	Specify what kind of metadata to obtain attribute value from	Enum: [Request Route Cluster Host]
`metadataKey` MetadataKey	Metadata key to define the path to retrieve the attribute value.
`defaultValue` string	When no valid metadata is found, the attribute value would be populated with this default value if specified, otherwise no attribute would be populated.

CustomLabel

Appears in:

AiExtensionStats

Field	Description	Validation
`name` string	Name of the label to use in the prometheus metrics	MinLength: 1
`metadataNamespace` string	The dynamic metadata namespace to get the data from. If not specified, the default namespace will be the envoy JWT filter namespace. This can also be used in combination with early_transformations to insert custom data.	Enum: [envoy.filters.http.jwt_authn io.solo.transformation]
`metadataKey` string	The key to use to get the data from the metadata namespace. If using a JWT data please see the following envoy docs: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto#envoy-v3-api-field-extensions-filters-http-jwt-authn-v3-jwtprovider-payload-in-metadata This key follows the same format as the envoy access logging for dynamic metadata. Examples can be found here: https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage	MinLength: 1
`keyDelimiter` string	The key delimiter to use, by default this is set to `:`. This allows for keys with `.` in them to be used. For example, if you have keys in your path with `:` in them, (e.g. `key1:key2:value`) you can instead set this to `~` to be able to split those keys properly.

CustomResponse

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

Appears in:

PromptguardRequest

Field	Description	Default	Validation
`message` string	A 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
`statusCode` integer	The status code to return to the client. Defaults to 403.	403	Maximum: 599 Minimum: 200

DirectResponse

DirectResponse contains configuration for defining direct response routes.

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`DirectResponse`
`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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` DirectResponseSpec
`status` DirectResponseStatus

DirectResponseSpec

DirectResponseSpec describes the desired state of a DirectResponse.

Appears in:

DirectResponse

Field	Description	Default	Validation
`status` integer	StatusCode defines the HTTP status code to return for this route.		Maximum: 599 Minimum: 200
`body` string	Body defines the content to be returned 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

DirectResponseStatus

DirectResponseStatus defines the observed state of a DirectResponse.

Appears in:

DirectResponse

DurationFilter

Underlying type: ComparisonFilter

DurationFilter filters based on request duration. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-durationfilter

Appears in:

FilterType

DynamicForwardProxyBackend

DynamicForwardProxyBackend is the dynamic forward proxy backend configuration.

Appears in:

BackendSpec

Field	Description	Default	Validation
`enableTls` boolean	EnableTls enables TLS. When true, the backend will be configured to use TLS. System CA will be used for validation. The hostname will be used for SNI and auto SAN validation.

EnvironmentResourceDetectorConfig

Underlying type: struct{}

EnvironmentResourceDetectorConfig specified the EnvironmentResourceDetector

Appears in:

ResourceDetector

EnvoyBootstrap

EnvoyBootstrap configures the Envoy proxy instance that is provisioned from a Kubernetes Gateway.

Appears in:

EnvoyContainer

Field	Description	Default	Validation
`logLevel` string	Envoy log level. Options include “trace”, “debug”, “info”, “warn”, “error”, “critical” and “off”. Defaults to “info”. See https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/run-envoy#debugging-envoy for more information.
`componentLogLevels` object (keys:string, values:string)	Envoy log levels for specific components. The keys are component names and the values are one of “trace”, “debug”, “info”, “warn”, “error”, “critical”, or “off”, e.g. `yaml<br /> componentLogLevels:<br /> upstream: debug<br /> connection: trace<br />` These will be converted to the `--component-log-level` Envoy argument value. See https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/run-envoy#debugging-envoy for more information. Note: the keys and values cannot be empty, but they are not otherwise validated.

EnvoyContainer

EnvoyContainer configures the container running Envoy.

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`bootstrap` EnvoyBootstrap	Initial envoy configuration.
`image` Image	The envoy container image. See https://kubernetes.io/docs/concepts/containers/images for details. Default values, which may be overridden individually: registry: quay.io/solo-io repository: envoy-wrapper tag: pullPolicy: IfNotPresent
`securityContext` SecurityContext	The security context for this container. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#securitycontext-v1-core for details.
`resources` ResourceRequirements	The compute resources required by this container. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for details.
`env` EnvVar array	The container environment variables.
`extraVolumeMounts` VolumeMount array	Additional volume mounts to add to the container. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#volumemount-v1-core for details.

EnvoyHealthCheck

EnvoyHealthCheck represents configuration for Envoy’s health check filter. The filter will be configured in No pass through mode, and will only match requests with the specified path.

Appears in:

HTTPListenerPolicySpec

Field	Description	Default	Validation
`path` string	Path defines the exact path that will be matched for health check requests.		MaxLength: 2048 Pattern: `^/[-a-zA-Z0-9@:%.+~#?&/=_]+$`

ExtAuthBufferSettings

ExtAuthBufferSettings configures how the request body should be buffered.

Appears in:

Field	Description	Default	Validation
`maxRequestBytes` integer	MaxRequestBytes sets the maximum size of a message body to buffer. Requests exceeding this size will receive HTTP 413 and not be sent to the auth service.		Minimum: 1
`allowPartialMessage` boolean	AllowPartialMessage determines if partial messages should be allowed. When true, requests will be sent to the auth service even if they exceed maxRequestBytes. The default behavior is false.	false
`packAsBytes` boolean	PackAsBytes determines if the body should be sent as raw bytes. When true, the body is sent as raw bytes in the raw_body field. When false, the body is sent as UTF-8 string in the body field. The default behavior is false.	false

ExtAuthPolicy

ExtAuthPolicy configures external authentication/authorization for a route. This policy will determine the ext auth server to use and how to talk to it. Note that most of these fields are passed along as is to Envoy. For more details on particular fields please see the Envoy ExtAuth documentation. https://raw.githubusercontent.com/envoyproxy/envoy/f910f4abea24904aff04ec33a00147184ea7cffa/api/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`extensionRef` NamespacedObjectReference	ExtensionRef references the GatewayExtension that should be used for auth.
`withRequestBody` ExtAuthBufferSettings	WithRequestBody allows the request body to be buffered and sent to the auth service. Warning buffering has implications for streaming and therefore performance.
`contextExtensions` object (keys:string, values:string)	Additional context for the auth service.
`disable` PolicyDisable	Disable all external auth filters. Can be used to disable external auth policies applied at a higher level in the config hierarchy.

ExtAuthProvider

ExtAuthProvider defines the configuration for an ExtAuth provider.

Appears in:

GatewayExtensionSpec

Field	Description	Default	Validation
`grpcService` ExtGrpcService	GrpcService is the GRPC service that will handle the auth.
`failOpen` boolean	FailOpen determines if requests are allowed when the ext auth service is unavailable. Defaults to false, meaning requests will be denied if the ext auth service is unavailable.	false
`clearRouteCache` boolean	ClearRouteCache determines if the route cache should be cleared to allow the external authentication service to correctly affect routing decisions.	false
`withRequestBody` ExtAuthBufferSettings	WithRequestBody allows the request body to be buffered and sent to the auth service. Warning: buffering has implications for streaming and therefore performance.
`statusOnError` integer	StatusOnError sets the HTTP status response code that is returned to the client when the auth server returns an error or cannot be reached. Must be in the range of 100-511 inclusive. The default matches the deny response code of 403 Forbidden.	403	Maximum: 511 Minimum: 100
`statPrefix` string	StatPrefix is an optional prefix to include when emitting stats from the extauthz filter, enabling different instances of the filter to have unique stats.		MinLength: 1

ExtGrpcService

ExtGrpcService defines the GRPC service that will handle the processing.

Appears in:

ExtAuthProvider
ExtProcProvider
RateLimitProvider

Field	Description	Default	Validation
`backendRef` BackendRef	BackendRef references the backend GRPC service.
`authority` string	Authority is the authority header to use for the GRPC service.
`requestTimeout` Duration	RequestTimeout is the timeout for the gRPC request. This is the timeout for a specific request.
`retry` GRPCRetryPolicy	Retry specifies the retry policy for gRPC streams associated with the service.

ExtProcPolicy

ExtProcPolicy defines the configuration for the Envoy External Processing filter.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`extensionRef` NamespacedObjectReference	ExtensionRef references the GatewayExtension that should be used for external processing.
`processingMode` ProcessingMode	ProcessingMode defines how the filter should interact with the request/response streams
`disable` PolicyDisable	Disable all external processing filters. Can be used to disable external processing policies applied at a higher level in the config hierarchy.

ExtProcProvider

ExtProcProvider defines the configuration for an ExtProc provider.

Appears in:

GatewayExtensionSpec

Field	Description	Default	Validation
`grpcService` ExtGrpcService	GrpcService is the GRPC service that will handle the processing.
`failOpen` boolean	FailOpen determines if requests are allowed when the ext proc service is unavailable. Defaults to true, meaning requests are allowed upstream even if the ext proc service is unavailable.	true
`processingMode` ProcessingMode	ProcessingMode defines how the filter should interact with the request/response streams.
`messageTimeout` Duration	MessageTimeout is the timeout for each message sent to the external processing server.
`maxMessageTimeout` Duration	MaxMessageTimeout specifies the upper bound of override_message_timeout that may be sent from the external processing server. The default value 0, which effectively disables the override_message_timeout API.
`statPrefix` string	StatPrefix is an optional prefix to include when emitting stats from the extproc filter, enabling different instances of the filter to have unique stats.		MinLength: 1
`routeCacheAction` ExtProcRouteCacheAction	RouteCacheAction describes the route cache action to be taken when an external processor response is received in response to request headers. The default behavior is “FromResponse” which will only clear the route cache when an external processing response has the clear_route_cache field set.	FromResponse	Enum: [FromResponse Clear Retain]
`metadataOptions` MetadataOptions	MetadataOptions allows configuring metadata namespaces to forwarded or received from the external processing server.

ExtProcRouteCacheAction

Underlying type: string

Appears in:

ExtProcProvider

Field	Description
`FromResponse`	RouteCacheActionFromResponse is the default behavior, which clears the route cache only when the clear_route_cache field is set in an external processor response.
`Clear`	RouteCacheActionClear always clears the route cache irrespective of the clear_route_cache field in the external processor response.
`Retain`	RouteCacheActionRetain never clears the route cache irrespective of the clear_route_cache field in the external processor response.

FieldDefault

FieldDefault provides default values for specific fields 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]"
  - field: "custom_string_list"
    value: '["one","two","three"]'
    override: true

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

Appears in:

AIPolicy

Field	Description	Default	Validation
`field` string	The name of the field.		MinLength: 1
`value` string	The field default value, which can be any JSON Data Type.		MinLength: 1
`override` boolean	Whether to override the field’s value if it already exists. Defaults to false.	false

FileSink

FileSink represents the file sink configuration for access logs.

Appears in:

AccessLog

Field	Description	Default	Validation
`path` string	the file path to which the file access logging service will sink
`stringFormat` string	the format string by which envoy will format the log lines https://www.envoyproxy.io/docs/envoy/v1.33.0/configuration/observability/access_log/usage#format-strings
`jsonFormat` RawExtension	the format object by which to envoy will emit the logs in a structured way. https://www.envoyproxy.io/docs/envoy/v1.33.0/configuration/observability/access_log/usage#format-dictionaries

FilterType

FilterType represents the type of filter to apply (only one of these should be set). Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#envoy-v3-api-msg-config-accesslog-v3-accesslogfilter

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

AccessLogFilter

Field	Description	Default	Validation
`statusCodeFilter` StatusCodeFilter
`durationFilter` DurationFilter
`notHealthCheckFilter` boolean	Filters for requests that are not health check requests. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-nothealthcheckfilter
`traceableFilter` boolean	Filters for requests that are traceable. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-traceablefilter
`headerFilter` HeaderFilter
`responseFlagFilter` ResponseFlagFilter
`grpcStatusFilter` GrpcStatusFilter
`celFilter` CELFilter

GRPCRetryBackoff

Appears in:

GRPCRetryPolicy

Field	Description	Default	Validation
`baseInterval` Duration	BaseInterval specifies the base interval used with a fully jittered exponential back-off between retries.
`maxInterval` Duration	MaxInterval specifies the maximum interval between retry attempts. Defaults to 10 times the BaseInterval if not set.

GRPCRetryPolicy

Appears in:

ExtGrpcService

Field	Description	Default	Validation
`attempts` integer	Attempts specifies the number of retry attempts for a request. Defaults to 1 attempt if not set. A value of 0 effectively disables retries.	1	Minimum: 0
`backoff` GRPCRetryBackoff	Backoff specifies the retry backoff strategy. If not set, a default backoff with a base interval of 1000ms is used. The default max interval is 10 times the base interval.

GatewayExtension

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`GatewayExtension`
`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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` GatewayExtensionSpec
`status` GatewayExtensionStatus

GatewayExtensionSpec

GatewayExtensionSpec defines the desired state of GatewayExtension.

Appears in:

GatewayExtension

Field	Description	Validation
`type` GatewayExtensionType	Type indicates the type of the GatewayExtension to be used.	Enum: [ExtAuth ExtProc RateLimit]
`extAuth` ExtAuthProvider	ExtAuth configuration for ExtAuth extension type.
`extProc` ExtProcProvider	ExtProc configuration for ExtProc extension type.
`rateLimit` RateLimitProvider	RateLimit configuration for RateLimit extension type.

GatewayExtensionStatus

GatewayExtensionStatus defines the observed state of GatewayExtension.

Appears in:

GatewayExtension

Field	Description	Default	Validation
`conditions` Condition array	Conditions is the list of conditions for the GatewayExtension.		MaxItems: 8

GatewayExtensionType

Underlying type: string

GatewayExtensionType indicates the type of the GatewayExtension.

Appears in:

GatewayExtensionSpec

Field	Description
`ExtAuth`	GatewayExtensionTypeExtAuth is the type for Extauth extensions.
`ExtProc`	GatewayExtensionTypeExtProc is the type for ExtProc extensions.
`RateLimit`	GatewayExtensionTypeRateLimit is the type for RateLimit extensions.

GatewayParameters

A GatewayParameters contains configuration that is used to dynamically provision kgateway’s data plane (Envoy proxy instance), based on a Kubernetes Gateway.

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`GatewayParameters`
`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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` GatewayParametersSpec
`status` GatewayParametersStatus

GatewayParametersSpec

A GatewayParametersSpec describes the type of environment/platform in which the proxy will be provisioned.

Appears in:

GatewayParameters

Field	Description	Default	Validation
`kube` KubernetesProxyConfig	The proxy will be deployed on Kubernetes.
`selfManaged` SelfManagedGateway	The proxy will be self-managed and not auto-provisioned.

GatewayParametersStatus

The current conditions of the GatewayParameters. This is not currently implemented.

Appears in:

GatewayParameters

GeminiConfig

GeminiConfig settings for the Gemini LLM provider.

Appears in:

LLMProvider
NamedLLMProvider

Field	Description	Default	Validation
`authToken` SingleAuthToken	The authorization token that the AI gateway uses to access the Gemini API. This token is automatically sent in the `key` query parameter of the request.
`model` string	The Gemini model to use. For more information, see the Gemini models docs.
`apiVersion` string	The version of the Gemini API to use. For more information, see the Gemini API version docs.

GracefulShutdownSpec

Appears in:

Field	Description	Default	Validation
`enabled` boolean	Enable grace period before shutdown to finish current requests while Envoy health checks fail to e.g. notify external load balancers. NOTE: This will not have any effect if you have not defined health checks via the health check filter
`sleepTimeSeconds` integer	Time (in seconds) for the preStop hook to wait before allowing Envoy to terminate		Maximum: 3.1536e+07 Minimum: 0

GrpcStatusFilter

GrpcStatusFilter filters gRPC requests based on their response status. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#enum-config-accesslog-v3-grpcstatusfilter-status

Appears in:

FilterType

Field	Description	Default	Validation
`statuses` GrpcStatus array			Enum: [OK CANCELED UNKNOWN INVALID_ARGUMENT DEADLINE_EXCEEDED NOT_FOUND ALREADY_EXISTS PERMISSION_DENIED RESOURCE_EXHAUSTED FAILED_PRECONDITION ABORTED OUT_OF_RANGE UNIMPLEMENTED INTERNAL UNAVAILABLE DATA_LOSS UNAUTHENTICATED] MinItems: 1
`exclude` boolean

HTTPListenerPolicy

HTTPListenerPolicy is intended to be used for configuring the Envoy HttpConnectionManager and any other config or policy that should map 1-to-1 with a given HTTP listener, such as the Envoy health check HTTP filter. Currently these policies can only be applied per Gateway but support for Listener attachment may be added in the future. See https://github.com/kgateway-dev/kgateway/issues/11786 for more details.

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`HTTPListenerPolicy`
`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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HTTPListenerPolicySpec
`status` PolicyStatus

HTTPListenerPolicySpec

HTTPListenerPolicySpec defines the desired state of a HTTP listener policy.

Appears in:

HTTPListenerPolicy

Field	Description	Validation
`targetRefs` LocalPolicyTargetReference array	TargetRefs specifies the target resources by reference to attach the policy to.	MaxItems: 16 MinItems: 1
`targetSelectors` LocalPolicyTargetSelector array	TargetSelectors specifies the target selectors to select resources to attach the policy to.
`accessLog` AccessLog array	AccessLoggingConfig contains various settings for Envoy’s access logging service. See here for more information: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto	MaxItems: 16
`tracing` Tracing	Tracing contains various settings for Envoy’s OpenTelemetry tracer. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/opentelemetry.proto.html
`upgradeConfig` UpgradeConfig	UpgradeConfig contains configuration for HTTP upgrades like WebSocket. See here for more information: https://www.envoyproxy.io/docs/envoy/v1.34.1/intro/arch_overview/http/upgrades.html
`useRemoteAddress` boolean	UseRemoteAddress determines whether to use the remote address for the original client. Note: If this field is omitted, it will fallback to the default value of ’true’, which we set for all Envoy HCMs. Thus, setting this explicitly to true is unnecessary (but will not cause any harm). When true, Envoy will use the remote address of the connection as the client address. When false, Envoy will use the X-Forwarded-For header to determine the client address. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address
`xffNumTrustedHops` integer	XffNumTrustedHops is the number of additional ingress proxy hops from the right side of the X-Forwarded-For HTTP header to trust when determining the origin client’s IP address. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-xff-num-trusted-hops	Minimum: 0
`serverHeaderTransformation` ServerHeaderTransformation	ServerHeaderTransformation determines how the server header is transformed. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-server-header-transformation	Enum: [Overwrite AppendIfAbsent PassThrough]
`streamIdleTimeout` Duration	StreamIdleTimeout is the idle timeout for HTTP streams. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-stream-idle-timeout
`idleTimeout` Duration	IdleTimeout is the idle timeout for connnections. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-msg-config-core-v3-httpprotocoloptions
`healthCheck` EnvoyHealthCheck	HealthCheck configures Envoy health checks
`preserveHttp1HeaderCase` boolean	PreserveHttp1HeaderCase determines whether to preserve the case of HTTP1 request headers. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing
`acceptHttp10` boolean	AcceptHTTP10 determines whether to accept incoming HTTP/1.0 and HTTP 0.9 requests. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-http1protocoloptions
`defaultHostForHttp10` string	DefaultHostForHttp10 specifies a default host for HTTP/1.0 requests. This is highly suggested if acceptHttp10 is true and a no-op if acceptHttp10 is false. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-http1protocoloptions	MinLength: 1

HashPolicy

Appears in:

LoadBalancerMaglevConfig
LoadBalancerRingHashConfig

Field	Description	Default	Validation
`header` Header	Header specifies a header’s value as a component of the hash key.
`cookie` Cookie	Cookie specifies a given cookie as a component of the hash key.
`sourceIP` SourceIP	SourceIP specifies whether to use the request’s source IP address as a component of the hash key.
`terminal` boolean	Terminal, if set, and a hash key is available after evaluating this policy, will cause Envoy to skip the subsequent policies and use the key as it is. This is useful for defining “fallback” policies and limiting the time Envoy spends generating hash keys.

Underlying type: struct{Name string “json:"name"”}

Appears in:

HashPolicy

HeaderFilter

HeaderFilter filters requests based on headers. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-headerfilter

Appears in:

FilterType

Field	Description	Default	Validation
`header` HTTPHeaderMatch

HeaderModifiers

HeaderModifiers can be used to define the policy to modify request and response headers.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`request` HTTPHeaderFilter	Request modifies request headers.
`response` HTTPHeaderFilter	Response modifies response headers.

HeaderName

Underlying type: string

Appears in:

HeaderTransformation

HeaderTransformation

Appears in:

Transform

Field	Description	Default	Validation
`name` HeaderName	Name is the name of the header to interact with.
`value` Template	Value is the template to apply to generate the output value for the header. Inja templates are supported for Envoy-based data planes only. CEL expressions are supported for agentgateway data plane only. The system will auto-detect the appropriate template format based on the data plane.

HeaderValue

Header name/value pair. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-msg-config-core-v3-headervalue

Appears in:

AccessLogGrpcService
CommonAccessLogGrpcService
CommonGrpcService

Field	Description	Default	Validation
`key` string	Header name.
`value` string	Header value.

HealthCheck

HealthCheck contains the options to configure the health check. See Envoy documentation for more details.

Appears in:

BackendConfigPolicySpec

Field	Description	Validation
`timeout` Duration	Timeout is time to wait for a health check response. If the timeout is reached the health check attempt will be considered a failure.
`interval` Duration	Interval is the time between health checks.
`unhealthyThreshold` integer	UnhealthyThreshold is the number of consecutive failed health checks that will be considered unhealthy. Note that for HTTP health checks, if a host responds with a code not in ExpectedStatuses or RetriableStatuses, this threshold is ignored and the host is considered immediately unhealthy.	Minimum: 0
`healthyThreshold` integer	HealthyThreshold is the number of healthy health checks required before a host is marked healthy. Note that during startup, only a single successful health check is required to mark a host healthy.	Minimum: 0
`http` HealthCheckHttp	Http contains the options to configure the HTTP health check.
`grpc` HealthCheckGrpc	Grpc contains the options to configure the gRPC health check.

HealthCheckGrpc

Appears in:

HealthCheck

Field	Description	Default	Validation
`serviceName` string	ServiceName is the optional name of the service to check.
`authority` string	Authority is the authority header used to make the gRPC health check request. If unset, the name of the cluster this health check is associated with will be used.

HealthCheckHttp

Appears in:

HealthCheck

Field	Description	Validation
`host` string	Host is the value of the host header in the HTTP health check request. If unset, the name of the cluster this health check is associated with will be used.
`path` string	Path is the HTTP path requested.
`method` string	Method is the HTTP method to use. If unset, GET is used.	Enum: [GET HEAD POST PUT DELETE OPTIONS TRACE PATCH]

Host

Host defines a static backend host.

Appears in:

StaticBackend
Webhook

Field	Description	Default	Validation
`host` string	Host is the host name to use for the backend.		MinLength: 1
`port` integer	Port is the port to use for the backend.

Http1ProtocolOptions

See Envoy documentation for more details.

Appears in:

BackendConfigPolicySpec

Field	Description	Default	Validation
`enableTrailers` boolean	Enables trailers for HTTP/1. By default the HTTP/1 codec drops proxied trailers. Note: Trailers must also be enabled at the gateway level in order for this option to take effect
`preserveHttp1HeaderCase` boolean	PreserveHttp1HeaderCase determines whether to preserve the case of HTTP1 response headers. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing
`overrideStreamErrorOnInvalidHttpMessage` boolean	Allows invalid HTTP messaging. When this option is false, then Envoy will terminate HTTP/1.1 connections upon receiving an invalid HTTP message. However, when this option is true, then Envoy will leave the HTTP/1.1 connection open where possible.

Http2ProtocolOptions

Appears in:

BackendConfigPolicySpec

Field	Description	Validation
`initialStreamWindowSize` Quantity	InitialStreamWindowSize is the initial window size for the stream. Valid values range from 65535 (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum). Defaults to 268435456 (256 * 1024 * 1024). Values can be specified with units like “64Ki”.
`initialConnectionWindowSize` Quantity	InitialConnectionWindowSize is similar to InitialStreamWindowSize, but for the connection level. Same range and default value as InitialStreamWindowSize. Values can be specified with units like “64Ki”.
`maxConcurrentStreams` integer	The maximum number of concurrent streams that the connection can have.	Minimum: 0
`overrideStreamErrorOnInvalidHttpMessage` boolean	Allows invalid HTTP messaging and headers. When disabled (default), then the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. When enabled, only the offending stream is terminated.

Image

A container image. See https://kubernetes.io/docs/concepts/containers/images for details.

Appears in:

Field	Description	Default	Validation
`registry` string	The image registry.
`repository` string	The image repository (name).
`tag` string	The image tag.
`digest` string	The hash digest of the image, e.g. `sha256:12345...`
`pullPolicy` PullPolicy	The image pull policy for the container. See https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy for details.

IstioContainer

IstioContainer configures the container running the istio-proxy.

Appears in:

IstioIntegration

Field	Description	Default	Validation
`image` Image	The envoy container image. See https://kubernetes.io/docs/concepts/containers/images for details.
`securityContext` SecurityContext	The security context for this container. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#securitycontext-v1-core for details.
`resources` ResourceRequirements	The compute resources required by this container. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for details.
`logLevel` string	Log level for istio-proxy. Options include “info”, “debug”, “warning”, and “error”. Default level is info Default is “warning”.
`istioDiscoveryAddress` string	The address of the istio discovery service. Defaults to “istiod.istio-system.svc:15012”.
`istioMetaMeshId` string	The mesh id of the istio mesh. Defaults to “cluster.local”.
`istioMetaClusterId` string	The cluster id of the istio cluster. Defaults to “Kubernetes”.

IstioIntegration

IstioIntegration configures the Istio integration settings used by a kgateway’s data plane (Envoy proxy instance)

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`istioProxyContainer` IstioContainer	Configuration for the container running istio-proxy. Note that if Istio integration is not enabled, the istio container will not be injected into the gateway proxy deployment.
`customSidecars` Container array	do not use slice of pointers: https://github.com/kubernetes/code-generator/issues/166 Override the default Istio sidecar in gateway-proxy with a custom container.

KubernetesProxyConfig

KubernetesProxyConfig configures the set of Kubernetes resources that will be provisioned for a given Gateway.

Appears in:

GatewayParametersSpec

Field	Description	Default	Validation
`deployment` ProxyDeployment	Use a Kubernetes deployment as the proxy workload type. Currently, this is the only supported workload type.
`envoyContainer` EnvoyContainer	Configuration for the container running Envoy. If agentgateway is enabled, the EnvoyContainer values will be ignored.
`sdsContainer` SdsContainer	Configuration for the container running the Secret Discovery Service (SDS).
`podTemplate` Pod	Configuration for the pods that will be created.
`service` Service	Configuration for the Kubernetes Service that exposes the Envoy proxy over the network.
`serviceAccount` ServiceAccount	Configuration for the Kubernetes ServiceAccount used by the Envoy pod.
`istio` IstioIntegration	Configuration for the Istio integration.
`stats` StatsConfig	Configuration for the stats server.
`aiExtension` AiExtension	Deprecated: `aiExtension` is deprecated in v2.1 and will be removed in v2.2. Prefer to use `agentgateway` instead. Configuration for the AI extension.
`agentgateway` Agentgateway	Configure the agentgateway integration. If agentgateway is disabled, the EnvoyContainer values will be used by default to configure the data plane proxy.
`omitDefaultSecurityContext` boolean	OmitDefaultSecurityContext is used to control whether or not `securityContext` fields should be rendered for the various generated Deployments/Containers that are dynamically provisioned by the deployer. When set to true, no `securityContexts` will be provided and will left to the user/platform to be provided. This should be enabled on platforms such as Red Hat OpenShift where the `securityContext` will be dynamically added to enforce the appropriate level of security.

LLMProvider

LLMProvider specifies the target large language model provider that the backend should route requests to. TODO: Move auth options off of SupportedLLMProvider to BackendConfigPolicy: https://github.com/kgateway-dev/kgateway/issues/11930

Appears in:

AIBackend
NamedLLMProvider

Field	Description	Validation
`openai` OpenAIConfig	OpenAI provider
`azureopenai` AzureOpenAIConfig	Azure OpenAI provider
`anthropic` AnthropicConfig	Anthropic provider
`gemini` GeminiConfig	Gemini provider
`vertexai` VertexAIConfig	Vertex AI provider
`bedrock` BedrockConfig	Bedrock provider
`host` string	Host specifies the hostname to send the requests to. If not specified, the default hostname for the provider is used.	MinLength: 1
`port` integer	Port specifies the port to send the requests to.
`path` PathOverride	Path specifies the URL path to use for the 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.
`authHeader` AuthHeader	AuthHeader specifies how the Authorization header is set in the request sent to the LLM provider. Allows changing the header name and/or the prefix (e.g., “Bearer”). Note: Not all LLM providers use the Authorization header and prefix. For example, OpenAI uses header: “Authorization” and prefix: “Bearer” But Azure OpenAI uses header: “api-key” and no Bearer.
`routes` object (keys:string, values:RouteType)	Routes defines how to identify the type of traffic to handle. The keys are URL path suffixes matched using ends-with comparison (e.g., “/v1/chat/completions”). The special “*” wildcard matches any path. If not specified, all traffic defaults to “completions” type.

LoadBalancer

Appears in:

BackendConfigPolicySpec

Field	Description	Validation
`healthyPanicThreshold` integer	HealthyPanicThreshold configures envoy’s panic threshold percentage between 0-100. Once the number of non-healthy hosts reaches this percentage, envoy disregards health information. See Envoy documentation.	Maximum: 100 Minimum: 0
`updateMergeWindow` Duration	This allows batch updates of endpoints health/weight/metadata that happen during a time window. this help lower cpu usage when endpoint change rate is high. defaults to 1 second. Set to 0 to disable and have changes applied immediately.
`leastRequest` LoadBalancerLeastRequestConfig	LeastRequest configures the least request load balancer type.
`roundRobin` LoadBalancerRoundRobinConfig	RoundRobin configures the round robin load balancer type.
`ringHash` LoadBalancerRingHashConfig	RingHash configures the ring hash load balancer type.
`maglev` LoadBalancerMaglevConfig	Maglev configures the maglev load balancer type.
`random` LoadBalancerRandomConfig	Random configures the random load balancer type.
`localityType` LocalityType	LocalityType specifies the locality config type to use. See https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/load_balancing_policies/common/v3/common.proto#envoy-v3-api-msg-extensions-load-balancing-policies-common-v3-localitylbconfig	Enum: [WeightedLb]
`closeConnectionsOnHostSetChange` boolean	If set to true, the load balancer will drain connections when the host set changes. Ring Hash or Maglev can be used to ensure that clients with the same key are routed to the same upstream host. Distruptions can cause new connections with the same key as existing connections to be routed to different hosts. Enabling this feature will cause the load balancer to drain existing connections when the host set changes, ensuring that new connections with the same key are consistently routed to the same host. Connections are not immediately closed, but are allowed to drain before being closed.

LoadBalancerLeastRequestConfig

LoadBalancerLeastRequestConfig configures the least request load balancer type.

Appears in:

LoadBalancer

Field	Description	Default	Validation
`choiceCount` integer	How many choices to take into account. Defaults to 2.
`slowStart` SlowStart	SlowStart configures the slow start configuration for the load balancer.

LoadBalancerMaglevConfig

Appears in:

LoadBalancer

Field	Description	Default	Validation
`useHostnameForHashing` boolean	UseHostnameForHashing specifies whether to use the hostname instead of the resolved IP address for hashing. Defaults to false.
`hashPolicies` HashPolicy array	HashPolicies specifies the hash policies for hashing load balancers (RingHash, Maglev).		MaxItems: 16 MinItems: 1

LoadBalancerRandomConfig

Appears in:

LoadBalancer

LoadBalancerRingHashConfig

LoadBalancerRingHashConfig configures the ring hash load balancer type.

Appears in:

LoadBalancer

Field	Description	Validation
`minimumRingSize` integer	MinimumRingSize is the minimum size of the ring.	Minimum: 0
`maximumRingSize` integer	MaximumRingSize is the maximum size of the ring.	Minimum: 0
`useHostnameForHashing` boolean	UseHostnameForHashing specifies whether to use the hostname instead of the resolved IP address for hashing. Defaults to false.
`hashPolicies` HashPolicy array	HashPolicies specifies the hash policies for hashing load balancers (RingHash, Maglev).	MaxItems: 16 MinItems: 1

LoadBalancerRoundRobinConfig

LoadBalancerRoundRobinConfig configures the round robin load balancer type.

Appears in:

LoadBalancer

Field	Description	Default	Validation
`slowStart` SlowStart	SlowStart configures the slow start configuration for the load balancer.

LocalPolicyTargetReference

Select the object to attach the policy by Group, Kind, and Name. The object must be in the same namespace as the policy. You can target only one object at a time.

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`.
`kind` Kind	The API kind of the target resource, such as Gateway or HTTPRoute.
`name` ObjectName	The name of the target resource.

LocalPolicyTargetReferenceWithSectionName

Select the object to attach the policy by Group, Kind, Name and SectionName. The object must be in the same namespace as the policy. You can target only one object at a time.

Appears in:

TrafficPolicySpec

Field	Description	Validation
`group` Group	The API group of the target resource. For Kubernetes Gateway API resources, the group is `gateway.networking.k8s.io`.
`kind` Kind	The API kind of the target resource, such as Gateway or HTTPRoute.
`name` ObjectName	The name of the target resource.
`sectionName` SectionName	The section name of the target resource.	MaxLength: 253 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`

LocalPolicyTargetSelector

LocalPolicyTargetSelector selects the object to attach the policy by Group, Kind, and MatchLabels. The object must be in the same namespace as the policy and match the specified labels. Do not use targetSelectors when reconciliation times are critical, especially if you have a large number of policies that target the same resource. Instead, use targetRefs to attach 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`.
`kind` Kind	The API kind of the target resource, such as Gateway or HTTPRoute.
`matchLabels` object (keys:string, values:string)	Label selector to select the target resource.

LocalPolicyTargetSelectorWithSectionName

LocalPolicyTargetSelectorWithSectionName the object to attach the policy by Group, Kind, MatchLabels, and optionally SectionName. The object must be in the same namespace as the policy and match the specified labels. Do not use targetSelectors when reconciliation times are critical, especially if you have a large number of policies that target the same resource. Instead, use targetRefs to attach the policy.

Appears in:

TrafficPolicySpec

Field	Description	Validation
`group` Group	The API group of the target resource. For Kubernetes Gateway API resources, the group is `gateway.networking.k8s.io`.
`kind` Kind	The API kind of the target resource, such as Gateway or HTTPRoute.
`matchLabels` object (keys:string, values:string)	Label selector to select the target resource.
`sectionName` SectionName	The section name of the target resource.	MaxLength: 253 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`

LocalRateLimitPolicy

LocalRateLimitPolicy represents a policy for local rate limiting. It defines the configuration for rate limiting using a token bucket mechanism.

Appears in:

RateLimit

Field	Description	Default	Validation
`tokenBucket` TokenBucket	TokenBucket represents the configuration for a token bucket local rate-limiting mechanism. It defines the parameters for controlling the rate at which requests are allowed.

LocalityType

Underlying type: string

Appears in:

LoadBalancer

Field	Description
`WeightedLb`	https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/locality_weight#locality-weighted-load-balancing Locality weighted load balancing enables weighting assignments across different zones and geographical locations by using explicit weights. This field is required to enable locality weighted load balancing.

MCP

MCP configures mcp backends

Appears in:

BackendSpec

Field	Description	Default	Validation
`targets` McpTargetSelector array	Targets is a list of MCP targets to use for this backend. Policies targeting MCP targets must use targetRefs[].sectionName to select the target by name.		MaxItems: 32 MinItems: 1

MCPProtocol

Underlying type: string

MCPProtocol defines the protocol to use for the MCP target

Appears in:

McpTarget

Field	Description
`StreamableHTTP`	MCPProtocolStreamableHTTP specifies Streamable HTTP must be used as the protocol
`SSE`	MCPProtocolSSE specifies Server-Sent Events (SSE) must be used as the protocol

McpSelector

McpSelector defines the selector logic to search for MCP targets.

Appears in:

McpTargetSelector

Field	Description	Default	Validation
`namespace` LabelSelector	Namespace is the label selector in which namespace the MCP targets are searched for.
`service` LabelSelector	Service is the label selector in which services the MCP targets are searched for.

McpTarget

McpTarget defines a single MCP target configuration.

Appears in:

McpTargetSelector

Field	Description	Validation
`host` string	Host is the hostname or IP address of the MCP target.	MinLength: 1
`port` integer	Port is the port number of the MCP target.	Maximum: 65535 Minimum: 1
`path` string	Path is the URL path of the MCP target endpoint. Defaults to “/sse” for SSE protocol or “/mcp” for StreamableHTTP protocol if not specified.
`protocol` MCPProtocol	Protocol is the protocol to use for the connection to the MCP target.	Enum: [StreamableHTTP SSE]

McpTargetSelector

McpTargetSelector defines the MCP target to use for this backend.

Appears in:

Field	Description	Default	Validation
`name` SectionName	Name of the MCP target.
`selector` McpSelector	Selector is the selector to use to select the MCP targets. Note: Policies must target the resource selected by the target and not the name of the selector-based target on the Backend resource.
`static` McpTarget	Static is the static MCP target to use. Policies can target static backends by targeting the Backend resource and using sectionName to target the specific static target by name.

Message

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

Appears in:

AIPromptEnrichment

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.
`content` string	String content of the message.

MetadataKey

MetadataKey provides a way to retrieve values from Metadata using a key and a path.

Appears in:

CustomAttributeMetadata

Field	Description	Default	Validation
`key` string	The key name of the Metadata from which to retrieve the Struct
`path` MetadataPathSegment array	The path used to retrieve a specific Value from the Struct. This can be either a prefix or a full path, depending on the use case

MetadataKind

Underlying type: string

Describes different types of metadata sources. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/metadata/v3/metadata.proto#envoy-v3-api-msg-type-metadata-v3-metadatakind-request

Validation:

Enum: [Request Route Cluster Host]

Appears in:

CustomAttributeMetadata

Field	Description
`Request`	Request kind of metadata.
`Route`	Route kind of metadata.
`Cluster`	Cluster kind of metadata.
`Host`	Host kind of metadata.

MetadataNamespaces

MetadataNamespaces configures which metadata namespaces to use. See envoy docs for specifics.

Appears in:

MetadataOptions

Field	Description	Default	Validation
`typed` string array			MinItems: 1
`untyped` string array			MinItems: 1

MetadataOptions

MetadataOptions allows configuring metadata namespaces to forward or receive from the external processing server.

Appears in:

ExtProcProvider

Field	Description	Default	Validation
`forwarding` MetadataNamespaces	Forwarding defines the typed or untyped dynamic metadata namespaces to forward to the external processing server.

MetadataPathSegment

Underlying type: struct{Key string “json:"key"”}

Specifies a segment in a path for retrieving values from Metadata.

Appears in:

MetadataKey

Moderation

Moderation configures an external moderation model endpoint. This endpoint evaluates request prompt data against predefined content rules to determine if the content adheres to those rules.

Any requests routed through the AI Gateway are processed by the specified moderation model. If the model identifies the content as harmful based on its rules, the request is automatically rejected.

You can configure a moderation endpoint either as a standalone prompt guard setting or alongside other request and response guard settings.

Appears in:

PromptguardRequest

Field	Description	Default	Validation
`openAIModeration` OpenAIConfig	Pass prompt data through an external moderation model endpoint, which compares the request prompt input to predefined content rules. Configure an OpenAI moderation endpoint.

NamedLLMProvider

NamedLLMProvider wraps an LLMProvider with a name.

Appears in:

PriorityGroup

Field	Description	Validation
`name` SectionName	Name of the provider. Policies can target this provider by name.
`openai` OpenAIConfig	OpenAI provider
`azureopenai` AzureOpenAIConfig	Azure OpenAI provider
`anthropic` AnthropicConfig	Anthropic provider
`gemini` GeminiConfig	Gemini provider
`vertexai` VertexAIConfig	Vertex AI provider
`bedrock` BedrockConfig	Bedrock provider
`host` string	Host specifies the hostname to send the requests to. If not specified, the default hostname for the provider is used.	MinLength: 1
`port` integer	Port specifies the port to send the requests to.
`path` PathOverride	Path specifies the URL path to use for the 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.
`authHeader` AuthHeader	AuthHeader specifies how the Authorization header is set in the request sent to the LLM provider. Allows changing the header name and/or the prefix (e.g., “Bearer”). Note: Not all LLM providers use the Authorization header and prefix. For example, OpenAI uses header: “Authorization” and prefix: “Bearer” But Azure OpenAI uses header: “api-key” and no Bearer.
`routes` object (keys:string, values:RouteType)	Routes defines how to identify the type of traffic to handle. The keys are URL path suffixes matched using ends-with comparison (e.g., “/v1/chat/completions”). The special “*” wildcard matches any path. If not specified, all traffic defaults to “completions” type.

NamespacedObjectReference

Select the object by Name and Namespace. You can target only one object at a time.

Appears in:

Field	Description	Default	Validation
`name` ObjectName	The name of the target resource.
`namespace` Namespace	The namespace of the target resource. If not set, defaults to the namespace of the parent object.		MaxLength: 63 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`

OTLPTracesProtocolType

Underlying type: string

OTLPTracesProtocolType defines the supported protocols for OTLP exporter.

Appears in:

AiExtensionTrace

Field	Description
`grpc`	OTLPTracesProtocolTypeGrpc specifies OTLP over gRPC protocol. This is typically the most efficient protocol for OpenTelemetry data transfer.
`http/protobuf`	OTLPTracesProtocolTypeProtobuf specifies OTLP over HTTP with Protobuf serialization. Data is sent via HTTP POST requests with Protobuf message bodies.
`http/json`	OTLPTracesProtocolTypeJson specifies OTLP over HTTP with JSON serialization. Data is sent via HTTP POST requests with JSON message bodies.

OTelTracesSampler

OTelTracesSampler defines the configuration for an OpenTelemetry trace sampler. It combines the sampler type with any required arguments for that type.

Appears in:

AiExtensionTrace

Field	Description	Default	Validation
`type` OTelTracesSamplerType	SamplerType specifies the type of sampler to use (default value: “parentbased_always_on”). Refer to OTelTracesSamplerType for available options. https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler		Enum: [alwaysOn alwaysOff traceidratio parentbasedAlwaysOn parentbasedAlwaysOff parentbasedTraceidratio]
`arg` string	SamplerArg provides an argument for the chosen sampler type. For “traceidratio” or “parentbased_traceidratio” samplers: Sampling probability, a number in the [0..1] range, e.g. 0.25. Default is 1.0 if unset. https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler_arg		Pattern: `^0(\.\d+)?\|1(\.0+)?$`

OpenAIConfig

OpenAIConfig settings for the OpenAI LLM provider.

Appears in:

LLMProvider
Moderation
NamedLLMProvider

Field	Description	Default	Validation
`authToken` SingleAuthToken	The authorization token that the AI gateway uses to access the OpenAI API. This token is automatically sent in the `Authorization` header of the request and prefixed with `Bearer`.
`model` string	Optional: Override the model name, such as `gpt-4o-mini`. If unset, the model name is taken from the request. This setting can be useful when setting up model failover within the same LLM provider.

OpenTelemetryAccessLogService

OpenTelemetryAccessLogService represents the OTel configuration for access logs. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/open_telemetry/v3/logs_service.proto

Appears in:

AccessLog

Field	Description	Default	Validation
`grpcService` CommonAccessLogGrpcService	Send access logs to gRPC service
`body` string	OpenTelemetry LogResource fields, following Envoy access logging formatting.
`disableBuiltinLabels` boolean	If specified, Envoy will not generate built-in resource labels like log_name, zone_name, cluster_name, node_name.

OpenTelemetryTracingConfig

OpenTelemetryTracingConfig represents the top-level Envoy’s OpenTelemetry tracer. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/opentelemetry.proto.html

Appears in:

TracingProvider

Field	Description	Validation
`grpcService` CommonGrpcService	Send traces to the gRPC service
`serviceName` string	The name for the service. This will be populated in the ResourceSpan Resource attributes Defaults to the envoy cluster name. Ie: `<gateway-name>.<gateway-namespace>`
`resourceDetectors` ResourceDetector array	An ordered list of resource detectors. Currently supported values are `EnvironmentResourceDetector`	MaxProperties: 1 MinProperties: 1
`sampler` Sampler	Specifies the sampler to be used by the OpenTelemetry tracer. This field can be left empty. In this case, the default Envoy sampling decision is used. Currently supported values are `AlwaysOn`	MaxProperties: 1 MinProperties: 1

OutlierDetection

OutlierDetection contains the options to configure passive health checks. See Envoy documentation for more details.

Appears in:

BackendConfigPolicySpec

Field	Description	Default	Validation
`consecutive5xx` integer	The number of consecutive server-side error responses (for HTTP traffic, 5xx responses; for TCP traffic, connection failures; etc.) before an ejection occurs. Defaults to 5. If this is zero, consecutive 5xx passive health checks will be disabled. In the future, other types of passive health checking might be added, but none will be enabled by default.	5	Minimum: 0
`interval` Duration	The time interval between ejection analysis sweeps. This can result in both new ejections as well as hosts being returned to service. Defaults to 10s.	10s
`baseEjectionTime` Duration	The base time that a host is ejected for. The real time is equal to the base time multiplied by the number of times the host has been ejected. Defaults to 30s.	30s
`maxEjectionPercent` integer	The maximum % of an upstream cluster that can be ejected due to outlier detection. Defaults to 10%.	10	Maximum: 100 Minimum: 0

PathOverride

PathOverride allows overriding the default URL path used for LLM provider API requests.

Appears in:

LLMProvider
NamedLLMProvider

Field	Description	Default	Validation
`full` string			MinLength: 1

Pod

Configuration for a Kubernetes Pod template.

Appears in:

KubernetesProxyConfig

Field	Description	Validation
`extraLabels` object (keys:string, values:string)	Additional labels to add to the Pod object metadata. If the same label is present on `Gateway.spec.infrastructure.labels`, the `Gateway` takes precedence.
`extraAnnotations` object (keys:string, values:string)	Additional annotations to add to the Pod object metadata. If the same annotation is present on `Gateway.spec.infrastructure.annotations`, the `Gateway` takes precedence.
`securityContext` PodSecurityContext	The pod security context. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podsecuritycontext-v1-core for details.
`imagePullSecrets` LocalObjectReference array	An optional list of references to secrets in the same namespace to use for pulling any of the images used by this Pod spec. See https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod for details.
`nodeSelector` object (keys:string, values:string)	A selector which must be true for the pod to fit on a node. See https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ for details.
`affinity` Affinity	If specified, the pod’s scheduling constraints. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#affinity-v1-core for details.
`tolerations` Toleration array	do not use slice of pointers: https://github.com/kubernetes/code-generator/issues/166 If specified, the pod’s tolerations. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core for details.
`gracefulShutdown` GracefulShutdownSpec	If specified, the pod’s graceful shutdown spec.
`terminationGracePeriodSeconds` integer	If specified, the pod’s termination grace period in seconds. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#pod-v1-core for details	Maximum: 3.1536e+07 Minimum: 0
`startupProbe` Probe	If specified, the pod’s startup probe. A probe of container startup readiness. Container will be only be added to service endpoints if the probe succeeds. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#probe-v1-core for details.
`readinessProbe` Probe	If specified, the pod’s readiness probe. Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#probe-v1-core for details.
`livenessProbe` Probe	If specified, the pod’s liveness probe. Periodic probe of container service readiness. Container will be restarted if the probe fails. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#probe-v1-core for details.
`topologySpreadConstraints` TopologySpreadConstraint array	If specified, the pod’s topology spread constraints. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#topologyspreadconstraint-v1-core for details.
`extraVolumes` Volume array	Additional volumes to add to the pod. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#volume-v1-core for details.

PolicyAncestorStatus

Appears in:

PolicyStatus

Field	Description	Validation
`ancestorRef` ParentReference	AncestorRef corresponds with a ParentRef in the spec that this PolicyAncestorStatus struct describes the status of.
`controllerName` string	ControllerName is a domain/path string that indicates the name of the controller that wrote this status. This corresponds with the controllerName field on GatewayClass. Example: “example.net/gateway-controller”. The format of this field is DOMAIN “/” PATH, where DOMAIN and PATH are valid Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). Controllers MUST populate this field when writing status. Controllers should ensure that entries to status populated with their ControllerName are cleaned up when they are no longer necessary.
`conditions` Condition array	Conditions describes the status of the Policy with respect to the given Ancestor.	MaxItems: 8 MinItems: 1

PolicyDisable

PolicyDisable is used to disable a policy.

Appears in:

Port

Appears in:

Service

Field	Description	Default	Validation
`port` integer	The port number to match on the Gateway		Maximum: 65535 Minimum: 1
`nodePort` integer	The NodePort to be used for the service. If not specified, a random port will be assigned by the Kubernetes API server.		Maximum: 65535 Minimum: 1

PriorityGroup

MultiPoolConfig configures the backends for multiple hosts or models from the same provider in one Backend resource. This method can be useful for creating one logical endpoint that is backed by multiple hosts or models.

In the priorities section, the order of pool entries defines the priority of the backend endpoints. The pool entries can either define a list of backends or a single backend. Note: Only two levels of nesting are permitted. Any nested entries after the second level are ignored.

Appears in:

AIBackend

Field	Description	Default	Validation
`providers` NamedLLMProvider array	A list of LLM provider backends within a single endpoint pool entry.		MaxItems: 32 MinItems: 1

ProcessingMode

ProcessingMode defines how the filter should interact with the request/response streams

Appears in:

Field	Description	Default	Validation
`requestHeaderMode` string	RequestHeaderMode determines how to handle the request headers	SEND	Enum: [DEFAULT SEND SKIP]
`responseHeaderMode` string	ResponseHeaderMode determines how to handle the response headers	SEND	Enum: [DEFAULT SEND SKIP]
`requestBodyMode` string	RequestBodyMode determines how to handle the request body	NONE	Enum: [NONE STREAMED BUFFERED BUFFERED_PARTIAL FULL_DUPLEX_STREAMED]
`responseBodyMode` string	ResponseBodyMode determines how to handle the response body	NONE	Enum: [NONE STREAMED BUFFERED BUFFERED_PARTIAL FULL_DUPLEX_STREAMED]
`requestTrailerMode` string	RequestTrailerMode determines how to handle the request trailers	SKIP	Enum: [DEFAULT SEND SKIP]
`responseTrailerMode` string	ResponseTrailerMode determines how to handle the response trailers	SKIP	Enum: [DEFAULT SEND SKIP]

PromptguardRequest

PromptguardRequest defines the prompt guards to apply to requests sent by the client. Multiple prompt guard configurations can be set, and they will be executed in the following order: webhook → regex → moderation for requests, where each step can reject the request and stop further processing.

Appears in:

AIPromptGuard

Field	Description	Default	Validation
`customResponse` CustomResponse	A custom response message to return to the client. If not specified, defaults to “The request was rejected due to inappropriate content”.
`regex` Regex	Regular expression (regex) matching for prompt guards and data masking.
`webhook` Webhook	Configure a webhook to forward requests to for prompt guarding.
`moderation` Moderation	Pass prompt data through an external moderation model endpoint, which compares the request prompt input to predefined content rules.

PromptguardResponse

PromptguardResponse configures the response that the prompt guard applies to responses returned by the LLM provider. Both webhook and regex can be set, they will be executed in the following order: webhook → regex, where each step can reject the request and stop further processing. Note: This is not yet supported for agentgateway.

Appears in:

AIPromptGuard

Field	Description	Default	Validation
`regex` Regex	Regular expression (regex) matching for prompt guards and data masking.
`webhook` Webhook	Configure a webhook to forward responses to for prompt guarding.

ProxyDeployment

ProxyDeployment configures the Proxy deployment in Kubernetes.

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`replicas` integer	The number of desired pods. If omitted, behavior will be managed by the K8s control plane, and will default to 1. If you are using an HPA, make sure to not explicitly define this. K8s reference: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#replicas		Minimum: 0
`strategy` DeploymentStrategy	The deployment strategy to use to replace existing pods with new ones. The Kubernetes default is a RollingUpdate with 25% maxUnavailable, 25% maxSurge. E.g., to recreate pods, minimizing resources for the rollout but causing downtime: strategy: type: Recreate E.g., to roll out as a RollingUpdate but with non-default parameters: strategy: type: RollingUpdate rollingUpdate: maxSurge: 100%

Publisher

Underlying type: string

Publisher configures the type of publisher model to use for VertexAI. Currently, only Google is supported.

Appears in:

VertexAIConfig

Field	Description
`GOOGLE`

RBAC

RBAC defines the configuration for role-based access control.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`policy` RBACPolicy	Policy specifies the RBAC rule to evaluate. A policy matches only all the conditions evaluates to true.
`action` AuthorizationPolicyAction	Action defines whether the rule allows or denies the request if matched. If unspecified, the default is “Allow”.	Allow	Enum: [Allow Deny]

RBACPolicy

RBACPolicy defines a single RBAC rule.

Appears in:

RBAC

Field	Description	Default	Validation
`matchExpressions` string array	MatchExpressions defines a set of conditions that must be satisfied for the rule to match. These expression should be in the form of a Common Expression Language (CEL) expression. See: https://www.envoyproxy.io/docs/envoy/latest/xds/type/matcher/v3/cel.proto		MinItems: 1

RateLimit

RateLimit defines a rate limiting policy.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`local` LocalRateLimitPolicy	Local defines a local rate limiting policy.
`global` RateLimitPolicy	Global defines a global rate limiting policy using an external service.

RateLimitDescriptor

RateLimitDescriptor defines a descriptor for rate limiting. A descriptor is a group of entries that form a single rate limit rule.

Appears in:

RateLimitPolicy

Field	Description	Default	Validation
`entries` RateLimitDescriptorEntry array	Entries are the individual components that make up this descriptor. When translated to Envoy, these entries combine to form a single descriptor.		MinItems: 1

RateLimitDescriptorEntry

RateLimitDescriptorEntry defines a single entry in a rate limit descriptor. Only one entry type may be specified.

Appears in:

RateLimitDescriptor

Field	Description	Validation
`type` RateLimitDescriptorEntryType	Type specifies what kind of rate limit descriptor entry this is.	Enum: [Generic Header RemoteAddress Path]
`generic` RateLimitDescriptorEntryGeneric	Generic contains the configuration for a generic key-value descriptor entry. This field must be specified when Type is Generic.
`header` string	Header specifies a request header to extract the descriptor value from. This field must be specified when Type is Header.	MinLength: 1

RateLimitDescriptorEntryType

Underlying type: string

RateLimitDescriptorEntryType defines the type of a rate limit descriptor entry.

Validation:

Enum: [Generic Header RemoteAddress Path]

Appears in:

RateLimitDescriptorEntry

Field	Description
`Generic`	RateLimitDescriptorEntryTypeGeneric represents a generic key-value descriptor entry.
`Header`	RateLimitDescriptorEntryTypeHeader represents a descriptor entry that extracts its value from a request header.
`RemoteAddress`	RateLimitDescriptorEntryTypeRemoteAddress represents a descriptor entry that uses the client’s IP address as its value.
`Path`	RateLimitDescriptorEntryTypePath represents a descriptor entry that uses the request path as its value.

RateLimitPolicy

RateLimitPolicy defines a global rate limiting policy using an external service.

Appears in:

RateLimit

Field	Description	Default	Validation
`descriptors` RateLimitDescriptor array	Descriptors define the 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.		MinItems: 1
`extensionRef` NamespacedObjectReference	ExtensionRef references a GatewayExtension that provides the global rate limit service.

RateLimitProvider

RateLimitProvider defines the configuration for a RateLimit service provider.

Appears in:

GatewayExtensionSpec

Field	Description	Default	Validation
`grpcService` ExtGrpcService	GrpcService is the GRPC service that will handle the rate limiting.
`domain` string	Domain identifies a rate limiting configuration for the rate limit service. All rate limit requests must specify a domain, which enables the configuration to be per application without fear of overlap (e.g., “api”, “web”, “admin”).
`failOpen` boolean	FailOpen determines if requests are limited when the rate limit service is unavailable. Defaults to true, meaning requests are allowed upstream and not limited if the rate limit service is unavailable.	true
`timeout` Duration	Timeout provides an optional timeout value for requests to the rate limit service. For rate limiting, prefer using this timeout rather than setting the generic `timeout` on the `GrpcService`. See envoy issue for more info.	100ms
`xRateLimitHeaders` XRateLimitHeadersStandard	XRateLimitHeaders configures the standard version to use for X-RateLimit headers emitted. See envoy docs for more info. Disabled by default.	Off	Enum: [Off DraftVersion03]

Regex

Regex configures the regular expression (regex) matching for prompt guards and data masking.

Appears in:

PromptguardRequest
PromptguardResponse

Field	Description	Default	Validation
`matches` RegexMatch array	A list of regex patterns to match against the request or response. Matches and built-ins are additive.
`builtins` BuiltIn array	A list of built-in regex patterns to match against the request or response. Matches and built-ins are additive.		Enum: [SSN CREDIT_CARD PHONE_NUMBER EMAIL]
`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

RegexMatch

RegexMatch configures the regular expression (regex) matching for prompt guards and data masking.

Appears in:

Regex

Field	Description	Default	Validation
`pattern` string	The regex pattern to match against the request or response.
`name` string	An optional name for this match, which can be used for debugging purposes.

ResourceDetector

ResourceDetector defines the list of supported ResourceDetectors

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

OpenTelemetryTracingConfig

Field	Description	Default	Validation
`environmentResourceDetector` EnvironmentResourceDetectorConfig

ResponseFlagFilter

ResponseFlagFilter filters based on response flags. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-responseflagfilter

Appears in:

FilterType

Field	Description	Default	Validation
`flags` string array			MinItems: 1

Retry

Retry defines the retry policy

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`retryOn` RetryOnCondition array	RetryOn specifies the conditions under which a retry should be attempted.		Enum: [5xx gateway-error reset reset-before-request connect-failure envoy-ratelimited retriable-4xx refused-stream retriable-status-codes http3-post-connect-failure cancelled deadline-exceeded internal resource-exhausted unavailable] MinItems: 1
`attempts` integer	Attempts specifies the number of retry attempts for a request. Defaults to 1 attempt if not set. A value of 0 effectively disables retries.	1	Minimum: 0
`perTryTimeout` Duration	PerTryTimeout specifies the timeout per retry attempt (incliding the initial attempt). If a global timeout is configured on a route, this timeout must be less than the global route timeout. It is specified as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “1s” or “500ms”.
`statusCodes` HTTPRouteRetryStatusCode array	StatusCodes specifies the HTTP status codes in the range 400-599 that should be retried in addition to the conditions specified in RetryOn.		MinItems: 1
`backoffBaseInterval` Duration	BackoffBaseInterval specifies the base interval used with a fully jittered exponential back-off between retries. Defaults to 25ms if not set. Given a backoff base interval B and retry number N, the back-off for the retry is in the range [0, (2^N-1)*B]. The backoff interval is capped at a max of 10 times the base interval. E.g., given a value of 25ms, the first retry will be delayed randomly by 0-24ms, the 2nd by 0-74ms, the 3rd by 0-174ms, and so on, and capped to a max of 10 times the base interval (250ms).	25ms

RetryOnCondition

Underlying type: string

RetryOnCondition specifies the condition under which retry takes place.

Validation:

Enum: [5xx gateway-error reset reset-before-request connect-failure envoy-ratelimited retriable-4xx refused-stream retriable-status-codes http3-post-connect-failure cancelled deadline-exceeded internal resource-exhausted unavailable]

Appears in:

Retry

RetryPolicy

Specifies the retry policy of remote data source when fetching fails. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-msg-config-core-v3-retrypolicy

Appears in:

AccessLogGrpcService
CommonAccessLogGrpcService
CommonGrpcService

Field	Description	Default	Validation
`retryBackOff` BackoffStrategy	Specifies parameters that control retry backoff strategy. the default base interval is 1000 milliseconds and the default maximum interval is 10 times the base interval.
`numRetries` integer	Specifies the allowed number of retries. Defaults to 1.		Minimum: 1

RouteType

Underlying type: string

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

Validation:

Enum: [completions messages models passthrough]

Appears in:

LLMProvider
NamedLLMProvider

Field	Description
`completions`	RouteTypeCompletions processes OpenAI /v1/chat/completions format requests
`messages`	RouteTypeMessages processes Anthropic /v1/messages format requests
`models`	RouteTypeModels handles /v1/models endpoint (returns available models)
`passthrough`	RouteTypePassthrough sends requests to upstream as-is without LLM processing

Sampler

Sampler defines the list of supported Samplers

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

OpenTelemetryTracingConfig

Field	Description	Default	Validation
`alwaysOnConfig` AlwaysOnConfig

SdsBootstrap

SdsBootstrap configures the SDS instance that is provisioned from a Kubernetes Gateway.

Appears in:

SdsContainer

Field	Description	Default	Validation
`logLevel` string	Log level for SDS. Options include “info”, “debug”, “warn”, “error”, “panic” and “fatal”. Default level is “info”.

SdsContainer

SdsContainer configures the container running SDS sidecar.

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`image` Image	The SDS container image. See https://kubernetes.io/docs/concepts/containers/images for details.
`securityContext` SecurityContext	The security context for this container. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#securitycontext-v1-core for details.
`resources` ResourceRequirements	The compute resources required by this container. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for details.
`bootstrap` SdsBootstrap	Initial SDS container configuration.

SelfManagedGateway

Appears in:

GatewayParametersSpec

ServerHeaderTransformation

Underlying type: string

ServerHeaderTransformation determines how the server header is transformed.

Appears in:

HTTPListenerPolicySpec

Field	Description
`Overwrite`	OverwriteServerHeaderTransformation overwrites the server header.
`AppendIfAbsent`	AppendIfAbsentServerHeaderTransformation appends to the server header if it’s not present.
`PassThrough`	PassThroughServerHeaderTransformation passes through the server header unchanged.

Service

Configuration for a Kubernetes Service.

Appears in:

KubernetesProxyConfig

Field	Description	Validation
`type` ServiceType	The Kubernetes Service type.	Enum: [ClusterIP NodePort LoadBalancer ExternalName]
`clusterIP` string	The manually specified IP address of the service, if a randomly assigned IP is not desired. See https://kubernetes.io/docs/concepts/services-networking/service/#choosing-your-own-ip-address and https://kubernetes.io/docs/concepts/services-networking/service/#headless-services on the implications of setting `clusterIP`.
`extraLabels` object (keys:string, values:string)	Additional labels to add to the Service object metadata. If the same label is present on `Gateway.spec.infrastructure.labels`, the `Gateway` takes precedence.
`extraAnnotations` object (keys:string, values:string)	Additional annotations to add to the Service object metadata. If the same annotation is present on `Gateway.spec.infrastructure.annotations`, the `Gateway` takes precedence.
`ports` Port array	Additional configuration for the service ports. The actual port numbers are specified in the Gateway resource.
`externalTrafficPolicy` string	ExternalTrafficPolicy defines the external traffic policy for the service. Valid values are Cluster and Local. Default value is Cluster.

ServiceAccount

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`extraLabels` object (keys:string, values:string)	Additional labels to add to the ServiceAccount object metadata.
`extraAnnotations` object (keys:string, values:string)	Additional annotations to add to the ServiceAccount object metadata. If the same annotation is present on `Gateway.spec.infrastructure.annotations`, the `Gateway` takes precedence.

SingleAuthToken

SingleAuthToken configures the authorization token that the AI gateway uses to access the LLM provider API. This token is automatically sent in a request header, depending on the LLM provider.

Appears in:

AnthropicConfig
AzureOpenAIConfig
GeminiConfig
OpenAIConfig
VertexAIConfig

Field	Description	Validation
`kind` SingleAuthTokenKind	Kind specifies which type of authorization token is being used. Must be one of: “Inline”, “SecretRef”, “Passthrough”.	Enum: [Inline SecretRef Passthrough]
`inline` string	Provide the token directly in the configuration for the Backend. This option is the least secure. Only use this option for quick tests such as trying out AI Gateway.
`secretRef` LocalObjectReference	Store the API key in a Kubernetes secret in the same namespace as the Backend. Then, refer to the secret in the Backend configuration. This option is more secure than an inline token, because the API key is encoded and you can restrict access to secrets through RBAC rules. You might use this option in proofs of concept, controlled development and staging environments, or well-controlled prod environments that use secrets.

SingleAuthTokenKind

Underlying type: string

Appears in:

SingleAuthToken

Field	Description
`Inline`	Inline provides the token directly in the configuration for the Backend.
`SecretRef`	SecretRef provides the token directly in the configuration for the Backend.
`Passthrough`	Passthrough the existing token. This token can either come directly from the client, or be generated by an OIDC flow early in the request lifecycle. This option is useful for backends which have federated identity setup and can re-use the token from the client. Currently, this token must exist in the `Authorization` header.

SlowStart

Appears in:

LoadBalancerLeastRequestConfig
LoadBalancerRoundRobinConfig

Field	Description	Validation
`window` Duration	Represents the size of slow start window. If set, the newly created host remains in slow start mode starting from its creation time for the duration of slow start window.
`aggression` string	This parameter controls the speed of traffic increase over the slow start window. Defaults to 1.0, so that endpoint would get linearly increasing amount of traffic. When increasing the value for this parameter, the speed of traffic ramp-up increases non-linearly. The value of aggression parameter should be greater than 0.0. By tuning the parameter, is possible to achieve polynomial or exponential shape of ramp-up curve. During slow start window, effective weight of an endpoint would be scaled with time factor and aggression: `new_weight = weight * max(min_weight_percent, time_factor ^ (1 / aggression))`, where `time_factor=(time_since_start_seconds / slow_start_time_seconds)`. As time progresses, more and more traffic would be sent to endpoint, which is in slow start window. Once host exits slow start, time_factor and aggression no longer affect its weight.
`minWeightPercent` integer	Minimum weight percentage of an endpoint during slow start.	Maximum: 100 Minimum: 0

SourceIP

Underlying type: struct{}

Appears in:

HashPolicy

StaticBackend

StaticBackend references a static list of hosts.

Appears in:

BackendSpec

Field	Description	Default	Validation
`hosts` Host array	Hosts is a list of hosts to use for the backend.		MinItems: 1
`appProtocol` AppProtocol	AppProtocol is the application protocol to use when communicating with the backend.		Enum: [http2 grpc grpc-web kubernetes.io/h2c kubernetes.io/ws]

StatsConfig

Configuration for the stats server.

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`enabled` boolean	Whether to expose metrics annotations and ports for scraping metrics.
`routePrefixRewrite` string	The Envoy stats endpoint to which the metrics are written
`enableStatsRoute` boolean	Enables an additional route to the stats cluster defaulting to /stats
`statsRoutePrefixRewrite` string	The Envoy stats endpoint with general metrics for the additional stats route

StatusCodeFilter

Underlying type: ComparisonFilter

StatusCodeFilter filters based on HTTP status code. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#envoy-v3-api-msg-config-accesslog-v3-statuscodefilter

Appears in:

FilterType

StringMatcher

Specifies the way to match a string.

Appears in:

CSRFPolicy

Field	Description	Default
`exact` string	The input string must match exactly the string specified here. Example: abc matches the value abc
`prefix` string	The input string must have the prefix specified here. Note: empty prefix is not allowed, please use regex instead. Example: abc matches the value abc.xyz
`suffix` string	The input string must have the suffix specified here. Note: empty prefix is not allowed, please use regex instead. Example: abc matches the value xyz.abc
`contains` string	The input string must contain the substring specified here. Example: abc matches the value xyz.abc.def
`safeRegex` string	The input string must match the Google RE2 regular expression specified here. See https://github.com/google/re2/wiki/Syntax for the syntax.
`ignoreCase` boolean	If true, indicates the exact/prefix/suffix/contains matching should be case insensitive. This has no effect on the regex match. For example, the matcher data will match both input string Data and data if this option is set to true.	false

TCPKeepalive

See Envoy documentation for more details.

Appears in:

BackendConfigPolicySpec

Field	Description	Validation
`keepAliveProbes` integer	Maximum number of keep-alive probes to send before dropping the connection.	Minimum: 0
`keepAliveTime` Duration	The number of seconds a connection needs to be idle before keep-alive probes start being sent.
`keepAliveInterval` Duration	The number of seconds between keep-alive probes.

TLS

Appears in:

BackendConfigPolicySpec

Field	Description	Validation
`secretRef` LocalObjectReference	Reference to the TLS secret containing the certificate, key, and optionally the root CA.
`files` TLSFiles	File paths to certificates local to the proxy.
`wellKnownCACertificates` WellKnownCACertificatesType	WellKnownCACertificates specifies whether to use a well-known set of CA certificates for validating the backend’s certificate chain. Currently, only the system certificate pool is supported via SDS.
`insecureSkipVerify` boolean	InsecureSkipVerify 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.
`sni` string	The SNI domains that should be considered for TLS connection	MinLength: 1
`verifySubjectAltNames` string array	Verify that the Subject Alternative Name in the peer certificate is one of the specified values. note that a root_ca must be provided if this option is used.
`parameters` TLSParameters	General TLS parameters. See the envoy docs for more information on the meaning of these values.
`alpnProtocols` string array	Set Application Level Protocol Negotiation If empty, defaults to [“h2”, “http/1.1”].
`allowRenegotiation` boolean	Allow Tls renegotiation, the default value is false. TLS renegotiation is considered insecure and shouldn’t be used unless absolutely necessary.
`simpleTLS` boolean	If the TLS config has the tls cert and key provided, kgateway uses it to perform mTLS by default. Set simpleTLS to true to disable mTLS in favor of server-only TLS (one-way TLS), even if kgateway has the client cert. If unset, defaults to false.

TLSFiles

Appears in:

Field	Description	Default	Validation
`tlsCertificate` string			MinLength: 1
`tlsKey` string			MinLength: 1
`rootCA` string			MinLength: 1

TLSParameters

Appears in:

Field	Description	Validation
`minVersion` TLSVersion	Minimum TLS version.	Enum: [AUTO 1.0 1.1 1.2 1.3]
`maxVersion` TLSVersion	Maximum TLS version.	Enum: [AUTO 1.0 1.1 1.2 1.3]
`cipherSuites` string array
`ecdhCurves` string array

TLSVersion

Underlying type: string

TLSVersion defines the TLS version.

Validation:

Enum: [AUTO 1.0 1.1 1.2 1.3]

Appears in:

TLSParameters

Field	Description
`AUTO`
`1.0`
`1.1`
`1.2`
`1.3`

Template

Underlying type: string

Appears in:

BodyTransformation
HeaderTransformation

Timeouts

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`request` Duration	Request specifies a timeout for an individual request from the gateway to a backend. This spans between the point at which the entire downstream request (i.e. end-of-stream) has been processed and when the backend response has been completely processed. A value of 0 effectively disables the timeout. It is specified as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “1s” or “500ms”.
`streamIdle` Duration	StreamIdle specifies a timeout for a requests’ idle streams. A value of 0 effectively disables the timeout.

TokenBucket

TokenBucket defines the configuration for a token bucket rate-limiting mechanism. It controls the rate at which tokens are generated and consumed for a specific operation.

Appears in:

LocalRateLimitPolicy

Field	Description	Default	Validation
`maxTokens` integer	MaxTokens specifies the maximum number of tokens that the bucket can hold. This value must be greater than or equal to 1. It determines the burst capacity of the rate limiter.		Minimum: 1
`tokensPerFill` integer	TokensPerFill specifies the number of tokens added to the bucket during each fill interval. If not specified, it defaults to 1. This controls the steady-state rate of token generation.	1	Minimum: 1
`fillInterval` Duration	FillInterval defines the time duration between consecutive token fills. This value must be a valid duration string (e.g., “1s”, “500ms”). It determines the frequency of token replenishment.

Tracing

Tracing represents the top-level Envoy’s tracer. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-tracing

Appears in:

HTTPListenerPolicySpec

Field	Description	Validation
`provider` TracingProvider	Provider defines the upstream to which envoy sends traces	MaxProperties: 1 MinProperties: 1
`clientSampling` integer	Target percentage of requests managed by this HTTP connection manager that will be force traced if the x-client-trace-id header is set. Defaults to 100%	Maximum: 100 Minimum: 0
`randomSampling` integer	Target percentage of requests managed by this HTTP connection manager that will be randomly selected for trace generation, if not requested by the client or not forced. Defaults to 100%	Maximum: 100 Minimum: 0
`overallSampling` integer	Target percentage of requests managed by this HTTP connection manager that will be traced after all other sampling checks have been applied (client-directed, force tracing, random sampling). Defaults to 100%	Maximum: 100 Minimum: 0
`verbose` boolean	Whether to annotate spans with additional data. If true, spans will include logs for stream events. Defaults to false
`maxPathTagLength` integer	Maximum length of the request path to extract and include in the HttpUrl tag. Used to truncate lengthy request paths to meet the needs of a tracing backend. Default: 256	Minimum: 1
`attributes` CustomAttribute array	A list of attributes with a unique name to create attributes for the active span.	MaxProperties: 2 MinProperties: 1
`spawnUpstreamSpan` boolean	Create separate tracing span for each upstream request if true. Defaults to false Link to envoy docs for more info

TracingProvider

TracingProvider defines the list of providers for tracing

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

Tracing

Field	Description	Default	Validation
`openTelemetry` OpenTelemetryTracingConfig	Tracing contains various settings for Envoy’s OTel tracer.

TrafficPolicy

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`TrafficPolicy`
`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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` TrafficPolicySpec
`status` PolicyStatus

TrafficPolicySpec

TrafficPolicySpec defines the desired state of a traffic policy. Note: Backend attachment is only supported for agentgateway.

Appears in:

TrafficPolicy

Field	Description	Validation
`targetRefs` LocalPolicyTargetReferenceWithSectionName array	TargetRefs specifies the target resources by reference to attach the policy to.	MaxItems: 16 MinItems: 1
`targetSelectors` LocalPolicyTargetSelectorWithSectionName array	TargetSelectors specifies the target selectors to select resources to attach the policy to.
`ai` AIPolicy	AI is used to configure AI-based policies for the policy.
`transformation` TransformationPolicy	Transformation is used to mutate and transform requests and responses before forwarding them to the destination.
`extProc` ExtProcPolicy	ExtProc specifies the external processing configuration for the policy.
`extAuth` ExtAuthPolicy	ExtAuth specifies the external authentication configuration for the policy. This controls what external server to send requests to for authentication.
`rateLimit` RateLimit	RateLimit specifies the rate limiting configuration for the policy. This controls the rate at which requests are allowed to be processed.
`cors` CorsPolicy	Cors specifies the CORS configuration for the policy.
`csrf` CSRFPolicy	Csrf specifies the Cross-Site Request Forgery (CSRF) policy for this traffic policy.
`headerModifiers` HeaderModifiers	HeaderModifiers defines the policy to modify request and response headers.
`autoHostRewrite` boolean	AutoHostRewrite rewrites the Host header to the DNS name of the selected upstream. NOTE: This field is only honoured for HTTPRoute targets. NOTE: If `autoHostRewrite` is set on a route that also has a URLRewrite filter configured to override the `hostname`, the `hostname` value will be used and `autoHostRewrite` will be ignored.
`buffer` Buffer	Buffer can be used to set the maximum request size that will be buffered. Requests exceeding this size will return a 413 response.
`timeouts` Timeouts	Timeouts defines the timeouts for requests It is applicable to HTTPRoutes and ignored for other targeted kinds.
`retry` Retry	Retry defines the policy for retrying requests. It is applicable to HTTPRoutes, Gateway listeners and XListenerSets, and ignored for other targeted kinds.
`rbac` RBAC	RBAC specifies the role-based access control configuration for the policy. This defines the rules for authorization based on roles and permissions. With an Envoy-based Gateway, RBAC policies applied at different attachment points in the configuration hierarchy are not cumulative, and only the most specific policy is enforced. In Envoy, this means an RBAC policy attached to a route will override any RBAC policies applied to the gateway or listener. In contrast, an Agentgateway-based Gateway supports cumulative RBAC policies across different attachment points, such that an RBAC policy attached to a route augments policies applied to the gateway or listener without overriding them.

Transform

Transform defines the operations to be performed by the transformation. These operations may include changing the actual request/response but may also cause side effects. Side effects may include setting info that can be used in future steps (e.g. dynamic metadata) and can cause envoy to buffer.

Appears in:

TransformationPolicy

Field	Description	Validation
`set` HeaderTransformation array	Set is a list of headers and the value they should be set to.	MaxItems: 16
`add` HeaderTransformation array	Add is a list of headers to add to the request and what that value should be set to. If there is already a header with these values then append the value as an extra entry.	MaxItems: 16
`remove` string array	Remove is a list of header names to remove from the request/response.	MaxItems: 16
`body` BodyTransformation	Body controls both how to parse the body and if needed how to set. If empty, body will not be buffered.

TransformationPolicy

TransformationPolicy config is used to modify envoy behavior at a route level. These modifications can be performed on the request and response paths.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`request` Transform	Request is used to modify the request path.
`response` Transform	Response is used to modify the response path.

UpgradeConfig

UpgradeConfig represents configuration for HTTP upgrades.

Appears in:

HTTPListenerPolicySpec

Field	Description	Default	Validation
`enabledUpgrades` string array	List of upgrade types to enable (e.g. “websocket”, “CONNECT”, etc.)		MinItems: 1

VertexAIConfig

VertexAIConfig settings for the Vertex AI LLM provider. To find the values for the project ID, project location, and publisher, you can check the fields of an API request, such as https://{LOCATION}-aiplatform.googleapis.com/{VERSION}/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/{PROVIDER}/<model-path>.

Appears in:

LLMProvider
NamedLLMProvider

Field	Description	Validation
`authToken` SingleAuthToken	The authorization token that the AI gateway uses to access the Vertex AI API. This token is automatically sent in the `key` header of the request.
`model` string	The Vertex AI model to use. For more information, see the Vertex AI model docs.	MinLength: 1
`apiVersion` string	The version of the Vertex AI API to use. For more information, see the Vertex AI API reference.	MinLength: 1
`projectId` string	The ID of the Google Cloud Project that you use for the Vertex AI.	MinLength: 1
`location` string	The location of the Google Cloud Project that you use for the Vertex AI.	MinLength: 1
`modelPath` string	Optional: The model path to route to. Defaults to the Gemini model path, `generateContent`.
`publisher` Publisher	The type of publisher model to use. Currently, only Google is supported.	Enum: [GOOGLE]

Webhook

Webhook configures a webhook to forward requests or responses to for prompt guarding.

Appears in:

PromptguardRequest
PromptguardResponse

Field	Description	Default	Validation
`host` Host	Host to send the traffic to. Note: TLS is not currently supported for webhook. Example: `yaml<br />host:<br /> host: example.com #The host name of the webhook endpoint.<br /> port: 443 #The port number on which the webhook is listening.<br />`
`forwardHeaderMatches` HTTPHeaderMatch array	ForwardHeaderMatches defines a list of HTTP header matches that will be 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.

XRateLimitHeadersStandard

Underlying type: string

XRateLimitHeadersStandard controls how XRateLimit headers will emitted.

Appears in:

RateLimitProvider

Field	Description
`Off`	XRateLimitHeaderOff disables emitting of XRateLimit headers.
`DraftVersion03`	XRateLimitHeaderDraftV03 outputs headers as described in draft RFC version 03.

Kgateway API

Packages link

gateway.kgateway.dev/v1alpha1 link

Resource Types link

AIBackend link

AIPolicy link

AIPromptEnrichment link

AIPromptGuard link

AWSGuardrailConfig link

AWSLambdaPayloadTransformMode link

AccessLog link

AccessLogFilter link

AccessLogGrpcService link

Action link

Agentgateway link

AiExtension link

AiExtensionStats link

AiExtensionTrace link

AlwaysOnConfig link

AnthropicConfig link

AnyValue link

AppProtocol link

AuthHeader link

AuthorizationPolicyAction link

AwsAuth link

AwsAuthType link

AwsBackend link

AwsLambda link

AzureOpenAIConfig link

Backend link

BackendConfigPolicy link

BackendConfigPolicySpec link

BackendSpec link

BackendStatus link

BackendType link

BedrockConfig link

BodyParseBehavior link

BodyTransformation link

Buffer link

BuiltIn link

CELFilter link

CSRFPolicy link

CommonAccessLogGrpcService link

CommonGrpcService link

CommonHttpProtocolOptions link

ComparisonFilter link

Cookie link

CorsPolicy link

CustomAttribute link

CustomAttributeEnvironment link

CustomAttributeHeader link

CustomAttributeLiteral link

CustomAttributeMetadata link

CustomLabel link

CustomResponse link

DirectResponse link

DirectResponseSpec link

DirectResponseStatus link

DurationFilter link

DynamicForwardProxyBackend link

EnvironmentResourceDetectorConfig link

EnvoyBootstrap link

EnvoyContainer link

EnvoyHealthCheck link

ExtAuthBufferSettings link

ExtAuthPolicy link

ExtAuthProvider link

ExtGrpcService link

ExtProcPolicy link

ExtProcProvider link

ExtProcRouteCacheAction link

FieldDefault link

FileSink link

FilterType link

GRPCRetryBackoff link

GRPCRetryPolicy link

GatewayExtension link

GatewayExtensionSpec link

GatewayExtensionStatus link

GatewayExtensionType link

Packages

gateway.kgateway.dev/v1alpha1

Resource Types

AIBackend

AIPolicy

AIPromptEnrichment

AIPromptGuard

AWSGuardrailConfig

AWSLambdaPayloadTransformMode

AccessLog

AccessLogFilter

AccessLogGrpcService

Action

Agentgateway

AiExtension

AiExtensionStats

AiExtensionTrace

AlwaysOnConfig

AnthropicConfig

AnyValue

AppProtocol

AuthHeader

AuthorizationPolicyAction

AwsAuth

AwsAuthType

AwsBackend

AwsLambda

AzureOpenAIConfig

Backend

BackendConfigPolicy

BackendConfigPolicySpec

BackendSpec

BackendStatus

BackendType

BedrockConfig

BodyParseBehavior

BodyTransformation

Buffer

BuiltIn

CELFilter

CSRFPolicy

CommonAccessLogGrpcService

CommonGrpcService

CommonHttpProtocolOptions

ComparisonFilter

Cookie

CorsPolicy

CustomAttribute

CustomAttributeEnvironment

CustomAttributeHeader

CustomAttributeLiteral

CustomAttributeMetadata

CustomLabel

CustomResponse

DirectResponse

DirectResponseSpec

DirectResponseStatus

DurationFilter

DynamicForwardProxyBackend

EnvironmentResourceDetectorConfig

EnvoyBootstrap

EnvoyContainer

EnvoyHealthCheck

ExtAuthBufferSettings

ExtAuthPolicy

ExtAuthProvider

ExtGrpcService

ExtProcPolicy

ExtProcProvider

ExtProcRouteCacheAction

FieldDefault

FileSink

FilterType

GRPCRetryBackoff

GRPCRetryPolicy

GatewayExtension

GatewayExtensionSpec

GatewayExtensionStatus

GatewayExtensionType

GatewayParameters