API reference

Review the API reference documentation for kgateway with the Envoy data plane.

Packages

gateway.kgateway.dev/v1alpha1

gateway.kgateway.dev/v1alpha1

Resource Types

Backend
BackendConfigPolicy
DirectResponse
GatewayExtension
GatewayParameters
HTTPListenerPolicy
ListenerPolicy
TrafficPolicy

APIKeyAuth

Appears in:

TrafficPolicySpec

Field	Description	Validation
`keySources` APIKeySource array	keySources specifies the list of key sources to extract the API key from. Key sources are processed in array order and the first one that successfully extracts a key is used. Within each key source, if multiple types (header, query, cookie) are specified, precedence is: header > query parameter > cookie. If empty, defaults to a single key source with header “api-key”. Example: keySources: - header: “X-API-KEY” - query: “api_key” - header: “Authorization” query: “token” cookie: “auth_token” In this example, the system will: 1. First try header “X-API-KEY” 2. If not found, try query parameter “api_key” 3. If not found, try header “Authorization” (then query “token”, then cookie “auth_token” within that key source)	MaxItems: 16 MinItems: 0
`forwardCredential` boolean	forwardCredential controls whether the API key is included in the request sent to the upstream. If false (default), the API key is removed from the request before sending to upstream. If true, the API key is included in the request sent to upstream. This applies to all configured key sources (header, query parameter, or cookie).
`clientIdHeader` string	clientIdHeader specifies the header name to forward the authenticated client identifier. If not specified, the client identifier will not be forwarded in any header. Example: “x-client-id”
`secretRef` SecretObjectReference	secretRef references a Kubernetes secret storing a set of API Keys. If there are many keys, ‘secretSelector’ can be used instead. Each entry in the Secret represents one API Key. The key is an arbitrary identifier. The value is a string, representing the API Key. Example: apiVersion: v1 kind: Secret metadata: name: api-key stringData: client1: “k-123” client2: “k-456”
`secretSelector` LabelSelector	secretSelector selects multiple secrets containing API Keys. If the same key is defined in multiple secrets, the behavior is undefined. Each entry in the Secret represents one API Key. The key is an arbitrary identifier. The value is a string, representing the API Key. Example: apiVersion: v1 kind: Secret metadata: name: api-key stringData: client1: “k-123” client2: “k-456”
`disable` PolicyDisable	Disable the API key authentication filter. Can be used to disable API key authentication policies applied at a higher level in the config hierarchy.

APIKeySource

APIKeySource defines where to extract the API key from within a single key source. Within a single key source, if multiple types are specified, precedence is: header > query parameter > cookie. The header is checked first, and only falls back to query parameter if the header is not present, then to cookie if both header and query are not present.

Appears in:

APIKeyAuth

Field	Description	Validation
`header` string	header specifies the name of the header that contains the API key.	MaxLength: 256 MinLength: 1
`query` string	query specifies the name of the query parameter that contains the API key.	MaxLength: 256 MinLength: 1
`cookie` string	cookie specifies the name of the cookie that contains the API key.	MaxLength: 256 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
HTTPSettings

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

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.

AuthorizationRequest

AuthorizationRequest configures the authorization request to the external service.

Appears in:

ExtHttpService

Field	Description	Default	Validation
`headersToAdd` object (keys:string, values:string)	HeadersToAdd specifies additional headers to add to the authorization request. These headers are sent to the authorization service in addition to the original request headers. Client request headers with the same key will be overridden. The keys are header names and values are envoy format specifiers, see https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto#envoy-v3-api-field-extensions-filters-http-ext-authz-v3-authorizationrequest-headers-to-add.

AuthorizationResponse

AuthorizationResponse configures the authorization response from the external service.

Appears in:

ExtHttpService

Field	Description	Default	Validation
`headersToBackend` string array	HeadersToBackend specifies which headers from the authorization response should be forwarded to the upstream service when the request is authorized. Common examples: [“x-current-user”, “x-user-id”, “x-auth-request-email”]

AwsAddressType

Underlying type: string

AwsAddressType defines which EC2 IP address to route to.

Validation:

Enum: [PrivateIP PublicIP]

Appears in:

AwsEc2

Field	Description
`PrivateIP`	AwsAddressTypePrivateIP routes to the instance private IP.
`PublicIP`	AwsAddressTypePublicIP routes to the instance public IP.

AwsAuth

AwsAuth specifies the authentication method to use for the backend.

Appears in:

AwsBackend

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.
`ec2` AwsEc2	Ec2 configures dynamic discovery of AWS EC2 instances.
`accountId` string	AccountId is the AWS account ID to use for the backend. Deprecated: Set accountId on spec.aws.lambda instead. This field is kept for backward compatibility. When both fields are set, spec.aws.lambda.accountId takes precedence.		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-]+$`

AwsEc2

AwsEc2 configures dynamic discovery of EC2 instances.

Appears in:

AwsBackend

Field	Description	Default	Validation
`port` integer	Port is the port to use for discovered instances. Defaults to 80.	80
`addressType` AwsAddressType	AddressType selects whether to route to the instance private or public IP. Defaults to PrivateIP.	PrivateIP	Enum: [PrivateIP PublicIP]
`roleArn` string	RoleArn is an optional IAM role to assume before listing instances.		Pattern: `^arn:aws[a-z-]*:iam::[0-9]\{12\}:role/.+$`
`filters` AwsTagFilter array	Filters select which instances should be associated with this backend. When multiple filters are provided, an instance must match all of them. If this list is omitted or empty, all running instances in the configured region are selected. Be careful: an accidentally empty filter list broadens the backend to the whole regional fleet rather than matching nothing.		MaxItems: 16

AwsLambda

AwsLambda configures the AWS Lambda service.

Appears in:

AwsBackend

Field	Description	Default	Validation
`accountId` string	AccountId is the AWS account ID to use for the backend. This is the preferred location for Lambda backends.		MaxLength: 12 MinLength: 1 Pattern: `^[0-9]\{12\}$`
`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]

AwsTagFilter

AwsTagFilter matches EC2 instances by tag.

Appears in:

AwsEc2

Field	Description	Default	Validation
`key` string	Key matches instances that contain the given tag key, regardless of value.		MaxLength: 128 MinLength: 1
`keyValue` AwsTagKeyValueFilter	KeyValue matches instances that contain the given tag key/value pair.

AwsTagKeyValueFilter

AwsTagKeyValueFilter matches EC2 instances by a tag key/value pair.

Appears in:

AwsTagFilter

Field	Description	Default	Validation
`key` string	Key is the tag key to match.		MaxLength: 128 MinLength: 1
`value` string	Value is the tag value to match.		MaxLength: 256 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.
`dns` DNS	DNS contains DNS configuration. Note that this only applies to backends that resolve to Envoy DNS clusters, i.e., Backends of type Static, AWS, or GCP.
`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.
`circuitBreakers` CircuitBreakers	CircuitBreakers contains the options necessary to configure circuit breaking. See Envoy documentation for more details.
`upstreamProxyProtocol` UpstreamProxyProtocol	UpstreamProxyProtocol configures the PROXY protocol for upstream connections to the backend. When enabled, the proxy protocol header is prepended to upstream connections, allowing backend services to see the original client connection information. See Envoy documentation for more details.

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. Deprecated: The Type field is deprecated and will be removed in a future release. The backend type is inferred from the configuration.	Enum: [AWS Static DynamicForwardProxy GCP]
`aws` AwsBackend	Aws is the AWS backend configuration.
`static` StaticBackend	Static is the static backend configuration.
`dynamicForwardProxy` DynamicForwardProxyBackend	DynamicForwardProxy is the dynamic forward proxy backend configuration.
`gcp` GcpBackend	Gcp is the GCP backend configuration.

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
`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.
`GCP`	BackendTypeGCP is the type for GCP backends.

BasicAuthPolicy

BasicAuthPolicy configures HTTP basic authentication using the Authorization header. Basic authentication validates requests against username/password pairs provided either inline or via a Kubernetes secret. The credentials must be in htpasswd SHA-1 format.

Appears in:

TrafficPolicySpec

Field	Description	Validation
`users` string array	Users provides an inline list of username/password pairs in htpasswd format. Each entry should be formatted as “username:hashed_password”. The only supported hash format is SHA-1 Example entries: - “user1:{SHA}d95o2uzYI7q7tY7bHI4U1xBug7s=”	MaxItems: 256 MinItems: 1
`secretRef` SecretReference	SecretRef references a Kubernetes secret containing htpasswd data. The secret must contain username/password pairs in htpasswd format.
`disable` PolicyDisable	Disable basic auth. Can be used to disable basic auth policies applied at a higher level in the config hierarchy.

BodyFormat

BodyFormat configures an Envoy response body using formatting. Either JSON or Text must be specified.

Appears in:

DirectResponseSpec

Field	Description	Validation
`contentType` string	ContentType defines the HTTP Content-Type header to be sent with the response. By default, `text/plain` is used for the Text format and `application/json` for the JSON format. Note: This setting does not currently take effect due to a bug in Envoy, a fix for which is pending release. The option is included for completeness and will become effective with a future version of Envoy.
`text` string	Text is a format string by which Envoy will format the response body. Mutually exclusive with JSON. See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/substitution_format_string.proto#envoy-v3-api-field-config-core-v3-substitutionformatstring-text-format for details.	MaxLength: 4096 MinLength: 1
`json` JSON	JSON is a format object by which Envoy will produce a JSON response body. Mutually exclusive with Text. See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/substitution_format_string.proto#envoy-v3-api-field-config-core-v3-substitutionformatstring-json-format for details. Setting a field to `null` in the JSON object requires the use of `kubectl apply --server-side` or equivalent. With the default client-side `kubectl apply`, null values are stripped by kubectl before reaching the API server.	Type: object

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 None]

Appears in:

BodyTransformation

Field	Description
`AsString`	BodyParseBehaviorAsString will parse the body as a string.
`AsJson`	BodyParseBehaviorAsJSON will parse the body as a json object.
`None`	BodyParseBehaviorNone will skip any body buffering and processing.

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. When set to None, it will not buffer the body and will skip all body processing. In addition, attempt to extract json variables from the body using inja template in the header will result in 400 response.	AsString	Enum: [AsString AsJson None]
`value` InjaTemplate	Value is the template to apply to generate the output value for the body. Only Inja templates are supported. If ParseAs field is set to None, this Value field is ignored and no body transformation will be done.

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.

CELFilter

Underlying type: struct

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

Appears in:

FilterType

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.

Appears in:

TrafficPolicySpec

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

CircuitBreakers

CircuitBreakers contains the options to configure circuit breaker thresholds for the default priority. See Envoy documentation for more details.

Appears in:

BackendConfigPolicySpec

Field	Description	Validation
`maxConnections` integer	MaxConnections is the maximum number of connections that will be made to the upstream cluster. If not specified, defaults to 1024.	Minimum: 1
`maxPendingRequests` integer	MaxPendingRequests is the maximum number of pending requests that are allowed to the upstream cluster. If not specified, defaults to 1024.	Minimum: 1
`maxRequests` integer	MaxRequests is the maximum number of parallel requests that are allowed to the upstream cluster. If not specified, defaults to 1024.	Minimum: 1
`maxRetries` integer	MaxRetries is the maximum number of parallel retries that are allowed to the upstream cluster. If not specified, defaults to 3.	Minimum: 0
`trackRemaining` boolean	TrackRemaining controls whether Envoy tracks the remaining resource gauges for this circuit breaker threshold group. When enabled, the remaining_cx, remaining_pending, remaining_rq, and remaining_retries statistics are populated. Enabling this has a performance cost. If not specified, defaults to false.

ClientCertificateValidationConfig

ClientCertificateValidationConfig configures mutual TLS (mTLS) client certificate validation.

Appears in:

ListenerDefaultConfig

Field	Description	Default	Validation
`mode` ClientCertificateValidationMode	Mode specifies how the listener should enforce client certificate validation.		Enum: [Require Optional]
`caCertificateRefs` ObjectReference array	CACertificateRefs contains references to Kubernetes Secrets or ConfigMaps containing CA certificates. Multiple references will be combined into a single trusted CA pool for the listener. The referenced Secrets/ConfigMaps must have a ca.crt key containing the PEM data		MaxItems: 8 MinItems: 1

ClientCertificateValidationMode

Underlying type: string

ClientCertificateValidationMode specifies how client certificate validation is enforced.

Appears in:

ClientCertificateValidationConfig

Field	Description
`Require`	ClientCertificateValidationModeRequire requires the client to present a valid certificate. The connection will be rejected if no valid client certificate is presented.
`Optional`	ClientCertificateValidationModeOptional allows connections without client certificates but validates the certificate if one is presented. If validation fails, the connection is rejected.

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

Compression

Compression configures HTTP gzip compression and decompression behavior.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`responseCompression` ResponseCompression	ResponseCompression controls response compression to the downstream. If set, responses with the appropriate `Accept-Encoding` header with certain textual content types will be compressed using gzip. The content-types that will be compressed are: - `application/javascript` - `application/json` - `application/xhtml+xml` - `image/svg+xml` - `text/css` - `text/html` - `text/plain` - `text/xml`
`requestDecompression` RequestDecompression	RequestDecompression controls request decompression. If set, gzip requests will be decompressed.

Cookie

Appears in:

HashPolicy

Field	Description	Validation
`name` string	Name of the cookie.	MinLength: 1
`path` string	Path is the name of the path for the cookie.
`ttl` Duration	TTL specifies the time to live of the cookie. If specified, a cookie with the TTL will be generated if the cookie is not present. If the TTL is present and zero, the generated cookie will be a session cookie.
`secure` boolean	Secure specifies whether the cookie is secure. If true, the cookie will only be sent over HTTPS.
`httpOnly` boolean	HttpOnly specifies whether the cookie is HTTP only, i.e. not accessible to JavaScript.
`sameSite` string	SameSite controls cross-site sending of cookies. Supported values are Strict, Lax, and None.	Enum: [Strict Lax None]

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:

RouteTracing
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.

DNS

Appears in:

BackendConfigPolicySpec

Field	Description	Default	Validation
`refreshRate` Duration	RefreshRate controls how frequently Envoy polls DNS for this backend’s hostnames. Minimum value is 1ms. If unset, Envoy’s default of 5s is used. When Envoy respects DNS TTLs, lower TTL values effectively override this setting, so RefreshRate acts as the maximum polling interval. Recommended value for large-scale deployments is 60s or higher.
`jitter` Duration	Jitter adds a random delay of up to this duration before each DNS refresh, spreading query load over time and helping prevent thundering-herd spikes. Must be less than or equal to refreshRate when both are set.
`respectTTL` boolean	RespectTTL instructs Envoy to honor TTL values returned by DNS responses. When enabled, TTLs lower than RefreshRate effectively become the refresh interval.

DenominatorType

Underlying type: string

DenominatorType defines the fraction percentages support several fixed denominator values.

Appears in:

FractionalPercent

Field	Description
`HUNDRED`	100. Example: 1/100 = 1%.
`TEN_THOUSAND`	10,000. Example: 1/10000 = 0.01%.
`MILLION`	1,000,000. Example: 1/1000000 = 0.0001%.

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` PolicyStatus

DirectResponseSpec

DirectResponseSpec describes the desired state of a DirectResponse.

Appears in:

DirectResponse

Field	Description	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 and BodyFormat are both omitted, no body is included in the response. Mutually exclusive with BodyFormat.	MaxLength: 4096 MinLength: 1
`bodyFormat` BodyFormat	BodyFormat defines the content to be returned in the HTTP response body as an Envoy format string. If this field and Body are both omitted, no body is included in the response. Mutually exclusive with Body. See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-directresponseaction-body-format for details.

DnsResolver

DnsResolver configures the CARES DNS resolver for Envoy.

Appears in:

EnvoyBootstrap

Field	Description	Default	Validation
`udpMaxQueries` integer	Maximum number of UDP queries to be issued on a single UDP channel. This helps prevent DNS query pinning to a single resolver, addressing the issue described in https://github.com/istio/istio/issues/53577. Defaults to 100 if not specified. Set to 0 to disable this limit. See https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto#extensions-network-dns-resolver-cares-v3-caresdnsresolverconfig		Minimum: 0

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.

DynamicMetadataTransformation

DynamicMetadataTransformation defines a single dynamic metadata entry to set.

Appears in:

Transform

Field	Description	Validation
`namespace` string	Namespace is the dynamic metadata namespace.	MaxLength: 256 MinLength: 1
`key` string	Key is the metadata key within the namespace.	MaxLength: 256 MinLength: 1
`value` DynamicMetadataValue	Value is the value to set in dynamic metadata.

DynamicMetadataValue

DynamicMetadataValue defines the value to set in dynamic metadata. Exactly one field must be set.

Appears in:

DynamicMetadataTransformation

Field	Description	Default	Validation
`stringValue` InjaTemplate	StringValue is an Inja template whose rendered output is stored as the metadata string value.		MinLength: 1

EnvoyBootstrap

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

Appears in:

EnvoyContainer

Field	Description	Default	Validation
`logFormat` LogFormat	Envoy application log format. Does not affect access logs. Can be JSON or custom text format. Defaults to text with default format string as defined in Envoy documentation. See https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-log-format for format flag options.
`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. componentLogLevels: upstream: debug connection: trace 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.
`dnsResolver` DnsResolver	DNS resolver configuration for Envoy’s CARES DNS resolver. This configuration applies to all clusters and affects DNS query behavior. See https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto for more information.
`enableReadinessProbeProxyProtocol` boolean	EnableReadinessProbeProxyProtocol enables the PROXY protocol listener filter on the kgateway readiness listener (port 8082). Set this to true if and only if the load balancer in front of the gateway prepends PROXY protocol headers to incoming TCP connections targeting the readiness port. For example, when using an AWS NLB with proxy protocol v2 enabled at the target group level (`service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"`). Defaults to false.

EnvoyContainer

EnvoyContainer configures the container running Envoy.

Appears in:

KubernetesProxyConfig

Field	Description	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.
`extraArgs` string array	Additional arguments to pass to the Envoy binary. Similar to Kubernetes container args, variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference is left unchanged. Double $$ are reduced to a single $, which allows escaping the $(VAR_NAME) syntax. The following Envoy flags are already managed by kgateway and must not be set here: `--disable-hot-restart`, `--service-node`, `--log-level`, and `--component-log-level`. Consider using a DeploymentOverlay to override these values if desired.	MaxItems: 32 MinItems: 1
`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
HTTPSettings

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:

ExtAuthPolicy
ExtAuthProvider

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. Mutually exclusive with HttpService.
`httpService` ExtHttpService	HttpService is the HTTP service that will handle the auth. Mutually exclusive with GrpcService.
`headersToForward` string array	HeadersToForward specifies which headers from the client request should be forwarded to the external authorization service. HTTP services by default have the following headers forwarded: Host, Method, Path, Content-Length, Authorization. If this field is omitted, gRPC services will have all client request headers forwarded, while HTTP services will only receive the default headers described above. Common examples: [“cookie”, “authorization”, “x-forwarded-for”] More info is available on the Envoy docs
`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` ExtSvcRetryPolicy	Retry specifies the retry policy for gRPC streams associated with the service.

ExtHttpService

ExtHttpService defines the HTTP service that will handle external authorization.

Appears in:

ExtAuthProvider

Field	Description	Default	Validation
`backendRef` BackendRef	BackendRef references the backend HTTP service.
`pathPrefix` string	PathPrefix specifies a prefix to the value of the authorization request’s path header. This allows customizing the path at which the authorization server expects to receive requests. For example, if the authorization server expects requests at “/verify”, set this to “/verify”. If not specified, the original request path is used.
`requestTimeout` Duration	RequestTimeout is the timeout for the HTTP request. Default timeout is 2 seconds.
`authorizationRequest` AuthorizationRequest	AuthorizationRequest configures the authorization request to the external service.
`authorizationResponse` AuthorizationResponse	AuthorizationResponse configures the authorization response from the external service.
`retry` ExtSvcRetryPolicy	Retry specifies the retry policy for HTTP requests to the authorization 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.
`allowProcessingModeOverride` boolean	AllowProcessingModeOverride determines if the processing mode can be overridden. Defaults to false, meaning the processing mode cannot be overridden.	false
`allowedProcessingModeOverrides` ProcessingMode array	AllowedProcessingModeOverrides specifies which processing modes are allowed to override the default. Empty or unspecified means all overrides are allowed (if AllowProcessingModeOverride is true). This is an allowlist; any processing mode in this list will allow the override to the specified mode. If AllowProcessingModeOverride is false, this field is ignored. See: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto#envoy-v3-api-field-extensions-filters-http-ext-proc-v3-externalprocessor-allowed-override-modes
`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.
`filterStage` FilterStageSpec	FilterStage specifies where in the HTTP filter chain the ExtProc filter should be placed. If not specified, the ExtProc filter defaults to running after the AuthZ stage.

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.

ExtSvcRetryPolicy

Appears in:

ExtGrpcService
ExtHttpService

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` RetryBackoff	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.

FaultAbort

FaultAbort configures request abort injection.

Appears in:

FaultInjectionPolicy

Field	Description	Default	Validation
`httpStatus` integer	HttpStatus is the HTTP status code to return when aborting a request.		Maximum: 599 Minimum: 200
`grpcStatus` integer	GrpcStatus is the gRPC status code to return when aborting a request.		Maximum: 16 Minimum: 0
`percentage` integer	Percentage of requests to abort. Defaults to 100.	100	Maximum: 100 Minimum: 0

FaultDelay

FaultDelay configures latency injection.

Appears in:

FaultInjectionPolicy

Field	Description	Default	Validation
`fixedDelay` Duration	FixedDelay is the duration to delay before forwarding the request.
`percentage` integer	Percentage of requests to inject the delay on. Defaults to 100.	100	Maximum: 100 Minimum: 0

FaultInjectionPolicy

FaultInjectionPolicy configures fault injection for testing service resiliency. At least one of delay, abort, responseRateLimit, or disable must be specified.

Appears in:

TrafficPolicySpec

Field	Description	Validation
`delay` FaultDelay	Delay injects latency into requests before forwarding upstream.
`abort` FaultAbort	Abort injects HTTP or gRPC errors to terminate requests early.
`responseRateLimit` FaultResponseRateLimit	ResponseRateLimit limits the response body data rate to simulate slow or degraded upstream connections.
`maxActiveFaults` integer	MaxActiveFaults limits the number of concurrent active faults. When this limit is reached, new requests will not have faults injected. If not specified, defaults to unlimited.	Minimum: 0
`disable` PolicyDisable	Disable the fault injection filter. Can be used to disable fault injection policies applied at a higher level in the config hierarchy.

FaultResponseRateLimit

FaultResponseRateLimit configures response body rate limiting to simulate slow upstream connections.

Appears in:

FaultInjectionPolicy

Field	Description	Default	Validation
`kbitsPerSecond` integer	KbitsPerSecond limits the response rate to the specified kilobits per second.		Minimum: 1
`percentage` integer	Percentage of requests to apply the rate limit on. Defaults to 100.	100	Maximum: 100 Minimum: 0

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

FilterStage

Underlying type: string

FilterStage represents well-known positions in the HTTP filter chain.

Validation:

Enum: [Fault AuthN AuthZ RateLimit Route]

Appears in:

FilterStageSpec

Field	Description
`Fault`	FilterStageFault is the earliest stage in the filter chain.
`AuthN`	FilterStageAuthN is the authentication stage.
`AuthZ`	FilterStageAuthZ is the authorization stage.
`RateLimit`	FilterStageRateLimit is the rate limiting stage.
`Route`	FilterStageRoute is the final processing stage before routing to upstream. The terminal Router filter always runs after this stage.

FilterStagePredicate

Underlying type: string

FilterStagePredicate specifies placement relative to a stage.

Validation:

Enum: [Before During After]

Appears in:

FilterStageSpec

Field	Description
`Before`	FilterStagePredicateBefore places the filter before the specified stage.
`During`	FilterStagePredicateDuring places the filter during the specified stage.
`After`	FilterStagePredicateAfter places the filter after the specified stage.

FilterStageSpec

FilterStageSpec specifies where in the HTTP filter chain a filter should be placed.

Appears in:

ExtProcProvider

Field	Description	Default	Validation
`stage` FilterStage	Stage selects the well-known position in the filter chain.		Enum: [Fault AuthN AuthZ RateLimit Route]
`predicate` FilterStagePredicate	Predicate specifies placement relative to the stage: Before, During, or After.	During	Enum: [Before During After]
`weight` integer	Weight controls ordering among multiple filters at the same stage and predicate. Higher weight places the filter earlier in the chain. Defaults to 0. Filters with the same stage, predicate, and weight are sorted alphabetically by filter name for consistency.	0

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
`runtimeFilter` RuntimeFilter	Filters for random sampling of access logs. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-runtimefilter

ForwardClientCertDetails

ForwardClientCertDetails configures how Envoy handles the x-forwarded-client-cert (XFCC) header forwarded to upstream backends.

Appears in:

HTTPListenerPolicySpec
HTTPSettings

Field	Description	Default	Validation
`mode` ForwardClientCertMode	Mode controls how Envoy handles the XFCC header on the request forwarded upstream. If unset and Details is provided, Mode defaults to SanitizeSet. If both Mode and Details are unset, this field has no effect. - Sanitize: do not send the XFCC header upstream. - ForwardOnly: forward the XFCC header in the request unchanged. - AppendForward: append the current client’s details to the XFCC header. - SanitizeSet: reset the XFCC header with the current client’s details, ignoring any client-supplied value. - AlwaysForwardOnly: always forward the XFCC header, even for non-mTLS connections.		Enum: [Sanitize ForwardOnly AppendForward SanitizeSet AlwaysForwardOnly]
`details` SetCurrentClientCertDetails	Details selects which fields from the downstream client certificate are written into the XFCC header that is sent upstream. These fields are only honored by Envoy when Mode is AppendForward or SanitizeSet.

ForwardClientCertMode

Underlying type: string

ForwardClientCertMode is the XFCC header forwarding mode for HTTP Connection Manager.

Appears in:

ForwardClientCertDetails

Field	Description
`Sanitize`	ForwardClientCertModeSanitize strips the XFCC header from requests forwarded upstream.
`ForwardOnly`	ForwardClientCertModeForwardOnly forwards the XFCC header from the request unchanged.
`AppendForward`	ForwardClientCertModeAppendForward appends the current client’s details to the XFCC header.
`SanitizeSet`	ForwardClientCertModeSanitizeSet resets the XFCC header with the current client’s details, ignoring any client-supplied value.
`AlwaysForwardOnly`	ForwardClientCertModeAlwaysForwardOnly always forwards the XFCC header, even for non-mTLS connections.

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	Deprecated: Setting this field has no effect. Type indicates the type of the GatewayExtension to be used.	Enum: [ExtAuth ExtProc RateLimit JWT OAuth2]
`extAuth` ExtAuthProvider	ExtAuth configuration for ExtAuth extension type.
`extProc` ExtProcProvider	ExtProc configuration for ExtProc extension type.
`rateLimit` RateLimitProvider	RateLimit configuration for RateLimit extension type.
`jwt` JWT	JWT configuration for JWT extension type.
`oauth2` OAuth2Provider	OAuth2 configuration for OAuth2 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.
`JWT`	GatewayExtensionTypeJWT is the type for the JWT extensions
`OAuth2`	GatewayExtensionTypeOAuth2 is the type for OAuth2 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

GatewayParametersOverlays

Appears in:

KubernetesProxyConfig

Field	Description	Default	Validation
`deploymentOverlay` KubernetesResourceOverlay	deploymentOverlay allows specifying overrides for the generated Deployment resource.
`serviceOverlay` KubernetesResourceOverlay	serviceOverlay allows specifying overrides for the generated Service resource.
`serviceAccountOverlay` KubernetesResourceOverlay	serviceAccountOverlay allows specifying overrides for the generated ServiceAccount resource.
`podDisruptionBudget` KubernetesResourceOverlay	podDisruptionBudget allows creating a PodDisruptionBudget for the proxy. If absent, no PDB is created. If present, a PDB is created with its selector automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated PDB.
`horizontalPodAutoscaler` KubernetesResourceOverlay	horizontalPodAutoscaler allows creating a HorizontalPodAutoscaler for the proxy. If absent, no HPA is created. If present, an HPA is created with its scaleTargetRef automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated HPA.
`verticalPodAutoscaler` KubernetesResourceOverlay	verticalPodAutoscaler allows creating a VerticalPodAutoscaler for the proxy. If absent, no VPA is created. If present, a VPA is created with its targetRef automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated VPA.

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. Overlays (fields named with the suffix ‘Overlay’) are applied after non-overlay configurations (“configs”). Configs on a GatewayClass (inside of GatewayParameters) are applied before configs on a Gateway (inside of GatewayParameters), which merge together. Overlays on a GatewayClass are then applied, and finally, overlays on a Gateway. It is recommended to use an overlay only if necessary (no config exists that can achieve the same goal) for smoother upgrades, readability, and earlier and improved validation.
`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

GcpBackend

GcpBackend is the GCP backend configuration.

Appears in:

BackendSpec

Field	Description	Default	Validation
`host` string	Host is the hostname of the GCP service to connect to. This will be used for SNI and as the target address.		MinLength: 1
`audience` string	Audience is the GCP service account audience URL. When omitted, defaults to “https://{host}”. This is used by the GCP authn filter to request the appropriate token.		MinLength: 1

GracefulShutdownSpec

Appears in:

Field	Description	Default	Validation
`enabled` boolean	Enable grace period before shutdown to finish current requests. When enabled, a preStop hook calls /healthcheck/fail on Envoy’s admin port, which causes the /ready endpoint to return 503 (DRAINING). This makes the Kubernetes readiness probe fail, removing the pod from Service endpoints so new traffic stops arriving (unless all endpoints are draining – see KEP-1669: Proxy Terminating Endpoints). The hook then sleeps for SleepTimeSeconds to allow in-flight requests to complete.
`sleepTimeSeconds` integer	Time (in seconds) for the preStop hook to wait before allowing Envoy to terminate		Maximum: 3.1536e+07 Minimum: 0

GrpcStatusFilter

Underlying type: struct

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

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. Deprecated: Use the httpSettings field on ListenerPolicy instead.

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. Furthermore, SkipXffAppend will implicitly be set to true unless explicitly configured. 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
`preserveExternalRequestId` boolean	PreserveExternalRequestId determines whether the connection manager will keep the x-request-id header if passed for a request that is edge (Edge request is the request from external clients to front Envoy) and not reset it, which is the current Envoy behaviour. This defaults to false. 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-preserve-external-request-id
`generateRequestId` boolean	GenerateRequestId: Whether the connection manager will generate the x-request-id header if it does not exist. This defaults to true. Generating a random UUID4 is expensive so in high throughput scenarios where this feature is not desired it can be disabled. 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-generate-request-id
`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. This is mutually exclusive with XffTrustedCIDRs. 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
`xffTrustedCIDRs` CIDR array	XffTrustedCIDRs are ranges of IPs that may appear in the X-Forwarded-For HTTP header and are trusted when determining the origin client’s IP address. This is mutually exclusive with XffNumTrustedHops and requires UseRemoteAddress to be set to false. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/xff/v3/xff.proto#envoy-v3-api-field-extensions-http-original-ip-detection-xff-v3-xffconfig-xff-trusted-cidrs	MinItems: 1
`skipXFFAppend` boolean	SkipXffAppend specifies whether to skip adding the downstream’s remote IP address to the X-Forwarded-For HTTP header. Note: If omitted, this effectively will default to true when UseRemoteAddress is false, such that Envoy acts as a “transparent proxy”. 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-skip-xff-append
`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 connections. 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
`maxRequestsPerConnection` integer	MaxRequestsPerConnection sets the maximum number of requests served over a single downstream keepalive connection. When the limit is reached, Envoy closes the connection, which forces clients to reconnect. This allows L4 load balancers like AWS NLB to rebalance long-lived HTTP/2 and gRPC connections across gateway pods. If set to 0 or unspecified, defaults to unlimited. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-requests-per-connection	Minimum: 0
`maxHeadersCount` integer	MaxHeadersCount sets the maximum number of headers allowed in a request. Downstream requests that exceed this limit will receive a 431 response for HTTP/1.x and a stream reset for HTTP/2. If unset, defaults to Envoy’s built-in default of 100. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-headers-count	Minimum: 1
`http2ProtocolOptions` ListenerHTTP2ProtocolOptions	Http2ProtocolOptions configures downstream HTTP/2 behavior on the listener’s HttpConnectionManager. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-http2protocoloptions
`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
`earlyRequestHeaderModifier` HTTPHeaderFilter	EarlyRequestHeaderModifier defines header modifications to be applied early in the request processing, before route selection. For example, if you use ExternalAuthz to add a header, you may want to remove it here, to make sure it did not come from the client.
`forwardClientCertDetails` ForwardClientCertDetails	ForwardClientCertDetails configures how Envoy handles the x-forwarded-client-cert (XFCC) header and which parts of the downstream client certificate are forwarded to upstream backends. Most modes only have effect on listeners where mTLS is configured. The exceptions are Sanitize, which strips XFCC unconditionally, and AlwaysForwardOnly, which forwards XFCC unconditionally; on a non-mTLS listener under any other mode the setting is a no-op. See: 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-forward-client-cert-details
`maxRequestHeadersKb` integer	MaxRequestHeadersKb sets the maximum size of request headers that Envoy will accept. If unset, the Envoy default is 60 KiB. 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-max-request-headers-kb	Maximum: 8192 Minimum: 1
`uuidRequestIdConfig` UuidRequestIdConfig	UuidRequestIdConfig configures the behavior of the UUID request ID extension. This extension sets the x-request-id header to a UUID value.
`stripHostPortMode` StripHostPortMode	StripHostPortMode determines whether, and under what conditions, Envoy will strip the port from the Host/authority header. StripMatchingHostPort strips the port only if it matches the listener’s own port. StripAnyHostPort strips the port unconditionally. 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-strip-matching-host-port See also: 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-strip-any-host-port	Enum: [MatchingPort AnyPort]

HTTPSettings

Appears in:

HTTPListenerPolicySpec
ListenerConfig
ListenerDefaultConfig

Field	Description	Validation
`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. Furthermore, SkipXffAppend will implicitly be set to true unless explicitly configured. 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
`preserveExternalRequestId` boolean	PreserveExternalRequestId determines whether the connection manager will keep the x-request-id header if passed for a request that is edge (Edge request is the request from external clients to front Envoy) and not reset it, which is the current Envoy behaviour. This defaults to false. 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-preserve-external-request-id
`generateRequestId` boolean	GenerateRequestId: Whether the connection manager will generate the x-request-id header if it does not exist. This defaults to true. Generating a random UUID4 is expensive so in high throughput scenarios where this feature is not desired it can be disabled. 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-generate-request-id
`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. This is mutually exclusive with XffTrustedCIDRs. 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
`xffTrustedCIDRs` CIDR array	XffTrustedCIDRs are ranges of IPs that may appear in the X-Forwarded-For HTTP header and are trusted when determining the origin client’s IP address. This is mutually exclusive with XffNumTrustedHops and requires UseRemoteAddress to be set to false. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/xff/v3/xff.proto#envoy-v3-api-field-extensions-http-original-ip-detection-xff-v3-xffconfig-xff-trusted-cidrs	MinItems: 1
`skipXFFAppend` boolean	SkipXffAppend specifies whether to skip adding the downstream’s remote IP address to the X-Forwarded-For HTTP header. Note: If omitted, this effectively will default to true when UseRemoteAddress is false, such that Envoy acts as a “transparent proxy”. 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-skip-xff-append
`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 connections. 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
`maxRequestsPerConnection` integer	MaxRequestsPerConnection sets the maximum number of requests served over a single downstream keepalive connection. When the limit is reached, Envoy closes the connection, which forces clients to reconnect. This allows L4 load balancers like AWS NLB to rebalance long-lived HTTP/2 and gRPC connections across gateway pods. If set to 0 or unspecified, defaults to unlimited. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-requests-per-connection	Minimum: 0
`maxHeadersCount` integer	MaxHeadersCount sets the maximum number of headers allowed in a request. Downstream requests that exceed this limit will receive a 431 response for HTTP/1.x and a stream reset for HTTP/2. If unset, defaults to Envoy’s built-in default of 100. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-headers-count	Minimum: 1
`http2ProtocolOptions` ListenerHTTP2ProtocolOptions	Http2ProtocolOptions configures downstream HTTP/2 behavior on the listener’s HttpConnectionManager. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-http2protocoloptions
`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
`earlyRequestHeaderModifier` HTTPHeaderFilter	EarlyRequestHeaderModifier defines header modifications to be applied early in the request processing, before route selection. For example, if you use ExternalAuthz to add a header, you may want to remove it here, to make sure it did not come from the client.
`forwardClientCertDetails` ForwardClientCertDetails	ForwardClientCertDetails configures how Envoy handles the x-forwarded-client-cert (XFCC) header and which parts of the downstream client certificate are forwarded to upstream backends. Most modes only have effect on listeners where mTLS is configured. The exceptions are Sanitize, which strips XFCC unconditionally, and AlwaysForwardOnly, which forwards XFCC unconditionally; on a non-mTLS listener under any other mode the setting is a no-op. See: 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-forward-client-cert-details
`maxRequestHeadersKb` integer	MaxRequestHeadersKb sets the maximum size of request headers that Envoy will accept. If unset, the Envoy default is 60 KiB. 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-max-request-headers-kb	Maximum: 8192 Minimum: 1
`uuidRequestIdConfig` UuidRequestIdConfig	UuidRequestIdConfig configures the behavior of the UUID request ID extension. This extension sets the x-request-id header to a UUID value.
`stripHostPortMode` StripHostPortMode	StripHostPortMode determines whether, and under what conditions, Envoy will strip the port from the Host/authority header. StripMatchingHostPort strips the port only if it matches the listener’s own port. StripAnyHostPort strips the port unconditionally. 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-strip-matching-host-port See also: 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-strip-any-host-port	Enum: [MatchingPort AnyPort]

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.

Header

Appears in:

HashPolicy

Field	Description	Default	Validation
`name` string	Name is the name of the header to use as a component of the hash key.		MinLength: 1

HeaderFilter

Underlying type: struct

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

HeaderName

Underlying type: string

Appears in:

HeaderTransformation

HeaderSource

Underlying type: struct

HeaderSource configures how to retrieve a JWT from a header

Appears in:

JWTTokenSource

HeaderTransformation

Appears in:

Transform

Field	Description	Default	Validation
`name` HeaderName	Name is the name of the header to interact with.
`value` InjaTemplate	Value is the Inja template to apply to generate the output value for the header.

HeaderValue

Underlying type: struct

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

HealthCheck

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

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. Envoy defaults to 1024.	Maximum: 2.147483647e+09 Minimum: 1
`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.

HttpsUri

Underlying type: string

HttpsUri specifies an HTTPS URI

Validation:

Pattern: ^https://([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(:[0-9]{1,5})?(/[a-zA-Z0-9\-._~!$&'()*+,;=:@%]*)*/?(\?[a-zA-Z0-9\-._~!$&'()*+,;=:@%/?]*)?$

Appears in:

OAuth2JWTConfig
OAuth2Provider

Image

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

Appears in:

EnvoyContainer
IstioContainer
SdsContainer

Field	Description	Default	Validation
`registry` string	The image registry.
`repository` string	The image repository (name).
`tag` string	The image tag. Tag and Digest are coupled at merge time: specifying a non-empty Tag without also specifying a Digest clears any inherited Digest, so the rendered image reference is `repo:tag`. To keep both an inherited (or overridden) tag and digest, specify non-empty values for both fields. To clear an inherited Tag while keeping an inherited Digest, set Tag to the empty string.
`digest` string	The hash digest of the image, e.g. `sha256:12345...` Tag and Digest are coupled at merge time: specifying a non-empty Digest without also specifying a Tag clears any inherited Tag, so the rendered image reference is `repo@digest`. To keep both an inherited (or overridden) tag and digest, specify non-empty values for both fields. To clear an inherited Digest while keeping an inherited Tag, set Digest to the empty string.
`pullPolicy` PullPolicy	The image pull policy for the container. See https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy for details.

InjaTemplate

Underlying type: string

Appears in:

BodyTransformation
DynamicMetadataValue
HeaderTransformation

IstioContainer

IstioContainer configures the container running the istio-proxy.

Appears in:

IstioIntegration

Field	Description	Default	Validation
`image` Image	The 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 kgateway’s data plane

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	Deprecated: This field was never implemented in v2 and will be deleted. If you need custom TLS certificate handling, use the built-in SDS (Secret Discovery Service) container via the sdsContainer field instead. For other sidecar needs, use a deployment overlay. Example overlay that adds a sidecar: spec: kube: deploymentOverlay: spec: template: spec: containers: - name: my-sidecar image: my-sidecar:latest

JWKS

JWKS (JSON Web Key Set) configures the source for the JWKS Exactly one of LocalJWKS or RemoteJWKS must be specified.

Appears in:

JWTProvider
NamedJWTProvider

Field	Description	Default	Validation
`local` LocalJWKS	LocalJWKS configures getting the public keys to validate the JWT from a Kubernetes configmap, or inline (raw string) JWKS.
`remote` RemoteJWKS	RemoteJWKS configures getting the public keys to validate the JWT from a remote JWKS server.

JWT

Appears in:

GatewayExtensionSpec

Field	Description	Default	Validation
`validationMode` ValidationMode	ValidationMode configures how JWT validation behaves. If unset or empty, Strict mode is used (JWT is required). If set to AllowMissing, unauthenticated requests without a JWT are allowed through. If using this mode, make sure to consider the security implications and consider using an `RBAC` policy to enforce authorization.		Enum: [Strict AllowMissing]
`providers` NamedJWTProvider array	Providers configures named JWT providers. If multiple providers are specified for a given JWT policy, the providers will be `OR`-ed together and will allow validation to any of the providers.		MaxItems: 32

JWTAuth

JWTAuth defines the providers used to configure JWT authentication

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`extensionRef` NamespacedObjectReference	ExtensionRef references a GatewayExtension that provides the jwt providers
`disable` PolicyDisable	Disable all JWT filters. Can be used to disable JWT policies applied at a higher level in the config hierarchy.

JWTClaimToHeader

JWTClaimToHeader allows copying verified claims to headers sent upstream

Appears in:

JWTProvider
NamedJWTProvider
OAuth2JWTProcessingConfig

Field	Description	Default	Validation
`name` string	Name is the JWT claim name, for example, “sub”.		MaxLength: 2048 MinLength: 1
`header` string	Header is the header the claim will be copied to, for example, “x-sub”.		MaxLength: 2048 MinLength: 1

JWTProvider

JWTProvider configures the JWT Provider If multiple providers are specified for a given JWT policy, the providers will be OR-ed together and will allow validation to any of the providers.

Appears in:

NamedJWTProvider

Field	Description	Validation
`issuer` string	Issuer of the JWT. the ‘iss’ claim of the JWT must match this.	MaxLength: 2048
`audiences` string array	Audiences is the list of audiences to be used for the JWT provider. If specified an incoming JWT must have an ‘aud’ claim, and it must be in this list. If not specified, the audiences will not be checked in the token.	MaxItems: 32 MinItems: 1
`tokenSource` JWTTokenSource	TokenSource configures where to find the JWT of the current provider.
`claimsToHeaders` JWTClaimToHeader array	ClaimsToHeaders is the list of claims to headers to be used for the JWT provider. Optionally set the claims from the JWT payload that you want to extract and add as headers to the request before the request is forwarded to the upstream destination. Note: if ClaimsToHeaders is set, the Envoy route cache will be cleared. This allows the JWT filter to correctly affect routing decisions.	MaxItems: 32 MinItems: 1
`jwks` JWKS	JWKS is the source for the JSON Web Keys to be used to validate the JWT.
`forwardToken` boolean	ForwardToken configures if the JWT token is forwarded to the upstream backend. If true, the header containing the token will be forwarded upstream. If false or not set, the header containing the token will be removed.

JWTTokenSource

JWTTokenSource configures the source for the JWTToken Exactly one of HeaderSource or QueryParameter must be specified.

Appears in:

JWTProvider
NamedJWTProvider

Field	Description	Default	Validation
`header` HeaderSource	HeaderSource configures retrieving token from a header
`queryParameter` string	QueryParameter configures retrieving token from the query parameter

KubernetesProxyConfig

KubernetesProxyConfig configures the set of Kubernetes resources that will be provisioned for a given Gateway. Overlays (fields named with the suffix ‘Overlay’) are applied after non-overlay configurations (“configs”). Configs on a GatewayClass (inside of GatewayParameters) are applied before configs on a Gateway (inside of GatewayParameters), which merge together. Overlays on a GatewayClass are then applied, and finally, overlays on a Gateway. It is recommended to use an overlay only if necessary (no config exists that can achieve the same goal) for smoother upgrades, readability, and earlier and improved validation.

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.
`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 proxy over the network.
`serviceAccount` ServiceAccount	Configuration for the Kubernetes ServiceAccount used by the proxy pods.
`istio` IstioIntegration	Configuration for the Istio integration.
`stats` StatsConfig	Configuration for the stats server.
`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.
`deploymentOverlay` KubernetesResourceOverlay	deploymentOverlay allows specifying overrides for the generated Deployment resource.
`serviceOverlay` KubernetesResourceOverlay	serviceOverlay allows specifying overrides for the generated Service resource.
`serviceAccountOverlay` KubernetesResourceOverlay	serviceAccountOverlay allows specifying overrides for the generated ServiceAccount resource.
`podDisruptionBudget` KubernetesResourceOverlay	podDisruptionBudget allows creating a PodDisruptionBudget for the proxy. If absent, no PDB is created. If present, a PDB is created with its selector automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated PDB.
`horizontalPodAutoscaler` KubernetesResourceOverlay	horizontalPodAutoscaler allows creating a HorizontalPodAutoscaler for the proxy. If absent, no HPA is created. If present, an HPA is created with its scaleTargetRef automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated HPA.
`verticalPodAutoscaler` KubernetesResourceOverlay	verticalPodAutoscaler allows creating a VerticalPodAutoscaler for the proxy. If absent, no VPA is created. If present, a VPA is created with its targetRef automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated VPA.

LabelSelector

LabelSelector selects resources using label selectors.

Appears in:

APIKeyAuth

Field	Description	Default	Validation
`matchLabels` object (keys:string, values:string)	Label selector to select the target resource.

ListenerConfig

Appears in:

ListenerDefaultConfig
ListenerPortConfig

Field	Description	Validation
`proxyProtocol` ProxyProtocolConfig	ProxyProtocol configures the PROXY protocol listener filter. By default, when set, Envoy will require connections to include the PROXY protocol header. This behavior can be relaxed by setting allowRequestsWithoutProxyProtocol to true, which allows the listener to also accept connections without the PROXY protocol header. This is commonly used when kgateway is behind a load balancer that preserves client IP information. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/listener/proxy_protocol/v3/proxy_protocol.proto
`tcpKeepalive` TCPKeepalive	TCPKeepalive configures OS-level TCP keepalive checks for downstream client connections accepted by this listener.
`perConnectionBufferLimitBytes` integer	PerConnectionBufferLimitBytes sets the per-connection buffer limit for all listeners on the gateway. This controls the maximum size of read and write buffers for new connections. When using Envoy as an edge proxy, configuring the listener buffer limit is important to guard against potential attacks or misconfigured downstreams that could hog the proxy’s resources. If unspecified, an implementation-defined default is applied (1MiB). See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#envoy-v3-api-field-config-listener-v3-listener-per-connection-buffer-limit-bytes	Minimum: 0
`httpSettings` HTTPSettings	HTTPSettings 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.

ListenerDefaultConfig

Appears in:

ListenerPolicySpec

Field	Description	Validation
`clientCertificateValidation` ClientCertificateValidationConfig	ClientCertificateValidation configures mutual TLS (mTLS) client certificate validation for the listener. This enables per-listener configuration of CA certificates for client certificate validation, allowing different listeners on the same port to enforce different mTLS trust boundaries. When configured on a ListenerPolicy targeting a specific listener (via sectionName), it overrides any Gateway-level mTLS configuration for that listener. Security Note: Per-listener CA certificate validation can be bypassed in scenarios where wildcard listeners (e.g., *.example.com) overlap with more specific hostnames on the same port, due to TLS connection coalescing. For deployments with non-overlapping hostnames per listener, this security concern does not apply. See GEP-91 and GEP-3567 for more details. Reference: https://gateway-api.sigs.k8s.io/geps/gep-91/ Reference: https://github.com/kubernetes-sigs/gateway-api/issues/3567
`proxyProtocol` ProxyProtocolConfig	ProxyProtocol configures the PROXY protocol listener filter. By default, when set, Envoy will require connections to include the PROXY protocol header. This behavior can be relaxed by setting allowRequestsWithoutProxyProtocol to true, which allows the listener to also accept connections without the PROXY protocol header. This is commonly used when kgateway is behind a load balancer that preserves client IP information. See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/listener/proxy_protocol/v3/proxy_protocol.proto
`tcpKeepalive` TCPKeepalive	TCPKeepalive configures OS-level TCP keepalive checks for downstream client connections accepted by this listener.
`perConnectionBufferLimitBytes` integer	PerConnectionBufferLimitBytes sets the per-connection buffer limit for all listeners on the gateway. This controls the maximum size of read and write buffers for new connections. When using Envoy as an edge proxy, configuring the listener buffer limit is important to guard against potential attacks or misconfigured downstreams that could hog the proxy’s resources. If unspecified, an implementation-defined default is applied (1MiB). See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#envoy-v3-api-field-config-listener-v3-listener-per-connection-buffer-limit-bytes	Minimum: 0
`httpSettings` HTTPSettings	HTTPSettings 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.

ListenerHTTP2ProtocolOptions

ListenerHTTP2ProtocolOptions mirrors Http2ProtocolOptions for listener-facing policies, but avoids the expensive CEL validations that push the listener CRDs over Kubernetes’ schema cost budget.

Appears in:

HTTPListenerPolicySpec
HTTPSettings

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. Envoy defaults to 1024.	Maximum: 2.147483647e+09 Minimum: 1

ListenerPolicy

ListenerPolicy is used for configuring Envoy listener-level settings that apply to all protocol types (HTTP, HTTPS, TCP, TLS). These policies can only target Gateway objects.

Field	Description	Default	Validation
`apiVersion` string	`gateway.kgateway.dev/v1alpha1`
`kind` string	`ListenerPolicy`
`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` ListenerPolicySpec
`status` PolicyStatus

ListenerPolicySpec

ListenerPolicySpec defines the desired state of a listener policy.

Appears in:

ListenerPolicy

Field	Description	Validation
`targetRefs` LocalPolicyTargetReferenceWithSectionName array	TargetRefs specifies the target resources by reference to attach the policy to. Only supports `Gateway` resources	MaxItems: 16 MinItems: 1
`targetSelectors` LocalPolicyTargetSelectorWithSectionName array	TargetSelectors specifies the target selectors to select `Gateway` resources to attach the policy to.
`default` ListenerDefaultConfig	Default specifies default listener configuration for all Listeners, unless a per-port configuration is defined.
`perPort` ListenerPortConfig array	Per port configuration allows overriding the listener config per port. Once set, this configuration completely replaces the default configuration for all listeners handling traffic that match this port. Unspecified fields in per-port configuration will not inherit values from default.	MaxItems: 64

ListenerPortConfig

Appears in:

ListenerPolicySpec

Field	Description	Default	Validation
`port` integer	The Port indicates the Port Number to which the Listener configuration will be applied. This configuration will be applied to all Listeners handling traffic that match this port.		Maximum: 65535 Minimum: 1
`listener` ListenerConfig	Listener stores the configuration that will be applied to all Listeners handling matching the given port.

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.	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.

LocalJWKS

LocalJWKS configures getting the public keys to validate the JWT from a Kubernetes ConfigMap, or inline (raw string) JWKS.

Appears in:

JWKS

Field	Description	Default	Validation
`inline` string	Inline is the JWKS as the raw, inline JWKS string This can be an individual key, a key set or a pem block public key		MaxLength: 16384 MinLength: 1
`configMapRef` LocalObjectReference	ConfigMapRef configures storing the JWK in a Kubernetes ConfigMap in the same namespace as the GatewayExtension. The ConfigMap must have a data key named ‘jwks’ that contains the JWKS.

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	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.
`percentEnabled` integer	PercentEnabled specifies the percentage of requests for which the rate limiter is enabled.	Maximum: 100 Minimum: 0
`percentEnforced` integer	PercentEnforced specifies the percentage of requests for which the rate limiter is enforced.	Maximum: 100 Minimum: 0

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.

LogFormat

LogFormat configures Envoy’s application log format. Either JSON or Text must be specified.

Appears in:

EnvoyBootstrap

Field	Description	Default	Validation
`json` RawExtension	The format object by which Envoy will emit logs in a structured way. Mutually exclusive with Text. See https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/application_logging#printing-logs-in-json-format.
`text` string	The format string by which Envoy will format log lines. Mutually exclusive with JSON. See https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-log-format.

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.

NamedJWTProvider

NamedJWTProvider is a named JWT provider entry.

Appears in:

Field	Description	Validation
`name` string	Name is the unique name of the JWT provider.	MaxLength: 253 MinLength: 1
`issuer` string	Issuer of the JWT. the ‘iss’ claim of the JWT must match this.	MaxLength: 2048
`audiences` string array	Audiences is the list of audiences to be used for the JWT provider. If specified an incoming JWT must have an ‘aud’ claim, and it must be in this list. If not specified, the audiences will not be checked in the token.	MaxItems: 32 MinItems: 1
`tokenSource` JWTTokenSource	TokenSource configures where to find the JWT of the current provider.
`claimsToHeaders` JWTClaimToHeader array	ClaimsToHeaders is the list of claims to headers to be used for the JWT provider. Optionally set the claims from the JWT payload that you want to extract and add as headers to the request before the request is forwarded to the upstream destination. Note: if ClaimsToHeaders is set, the Envoy route cache will be cleared. This allows the JWT filter to correctly affect routing decisions.	MaxItems: 32 MinItems: 1
`jwks` JWKS	JWKS is the source for the JSON Web Keys to be used to validate the JWT.
`forwardToken` boolean	ForwardToken configures if the JWT token is forwarded to the upstream backend. If true, the header containing the token will be forwarded upstream. If false or not set, the header containing the token will be removed.

OAuth2CookieConfig

Appears in:

OAuth2Provider

Field	Description	Validation
`domain` string	CookieDomain specifies the domain to set on the access and ID token cookies. If set, the cookies will be set for the specified domain and all its subdomains. This is useful when requests to subdomains are not required to be re-authenticated after the user has logged into the parent domain. If not set, the cookies will default to the host of the request, not including the subdomains.	MaxLength: 253 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9]))*$`
`names` OAuth2CookieNames	Names specifies the names of the cookies used to store the tokens. If not set, the default names will be used.
`sameSite` OAuth2CookieSameSite	SameSite specifies the SameSite attribute for the OAuth2 cookies. If not set, the default is Lax.	Enum: [Lax Strict None]
`disableAccessTokenSetCookie` boolean	DisableAccessTokenSetCookie specifies whether to disable setting the access token cookie. This can be used when the access token is too large to fit in a cookie. When true, the set-cookie response header for the access token will be omitted.
`disableIDTokenSetCookie` boolean	DisableIDTokenSetCookie specifies whether to disable setting the ID token cookie. This can be used when the ID token is too large to fit in a cookie. When true, the set-cookie response header for the ID token will be omitted.
`disableRefreshTokenSetCookie` boolean	DisableRefreshTokenSetCookie specifies whether to disable setting the refresh token cookie. This can be used when the refresh token is too large to fit in a cookie. When true, the set-cookie response header for the refresh token will be omitted.

OAuth2CookieNames

OAuth2CookieNames specifies the names of the cookies used to store the tokens.

Appears in:

OAuth2CookieConfig

Field	Description	Default	Validation
`accessToken` string	AccessToken specifies the name of the cookie used to store the access token.		MinLength: 1
`idToken` string	IDToken specifies the name of the cookie used to store the ID token.		MinLength: 1

OAuth2CookieSameSite

Underlying type: string

OAuth2CookieSameSite specifies the SameSite attribute for OAuth2 cookies

Validation:

Enum: [Lax Strict None]

Appears in:

OAuth2CookieConfig

Field	Description
`Lax`	OAuth2CookieSameSiteLax specifies the Lax SameSite attribute for OAuth2 cookies
`Strict`	OAuth2CookieSameSiteStrict specifies the Strict SameSite attribute for OAuth2 cookies
`None`	OAuth2CookieSameSiteNone specifies the None SameSite attribute for OAuth2 cookies

OAuth2Credentials

OAuth2Credentials specifies the Oauth2 client credentials.

Appears in:

OAuth2Provider

Field	Description	Default	Validation
`clientID` string	ClientID specifies the client ID issued to the client during the registration process. Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1 for more details.		MinLength: 1
`clientSecretRef` LocalObjectReference	ClientSecretRef specifies a Secret that contains the client secret stored in the key ‘client-secret’ to use in the authentication request to obtain the access token. Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1 for more details.

OAuth2DenyRedirectMatcher

OAuth2DenyRedirectMatcher specifies the matcher to match requests that should be denied redirects to the authorization endpoint.

Appears in:

OAuth2Provider

Field	Description	Default	Validation
`headers` HTTPHeaderMatch array	Headers specifies the list of HTTP headers to match on requests that should be denied redirects.		MaxItems: 16 MinItems: 1

OAuth2JWTConfig

OAuth2JWTConfig specifies how retrieved tokens are to be parsed and verified as JWT if at all.

Appears in:

OAuth2Provider

Field	Description	Validation
`jwksURI` HttpsUri	JWKSURI specifies the URL that public keys for validating JWTs should be retrieved from. This must be set if the retrieved access or ID token need to be parsed and IssuerURI is not set for discovery. If both IssuerURI and this value are specified, the value discovered from the issuer will not be used and this takes precedence. The URL must point to a valid JWKS definition. Refer to https://datatracker.ietf.org/doc/html/rfc7517#section-5 for more details.	Pattern: `^https://([a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?\.)[a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?(:[0-9]\{1,5\})?(/[a-zA-Z0-9\-._~!$&'()+,;=:@%])/?(\?[a-zA-Z0-9\-._~!$&'()+,;=:@%/?])?$`
`jwksBackendRef` BackendObjectReference	JWKSBackendRef specifies the backend to use for fetching the JWKS. If not set, the parent OAuth2Provider’s BackendRef is used.
`accessToken` OAuth2JWTProcessingConfig	AccessToken specifies how to process the retrieved access token. This requires the access token cookie to be enabled. Requests missing the token will be rejected. The token will be verified against the provided JWKS. Successfully processed tokens have their payload made available as the ‘accessToken’ dynamic metadata in the ’envoy.filters.http.jwt_authn’ namespace. If omitted, the token will not be attempted to be parsed and verified at all.
`idToken` OAuth2JWTProcessingConfig	IDToken specifies how to process the retrieved ID token. This requires the ID token cookie to be enabled. Requests missing the token will be rejected. The token will be verified against the provided JWKS. Successfully processed tokens have their payload made available as the ‘idToken’ dynamic metadata in the ’envoy.filters.http.jwt_authn’ namespace. If omitted, the token will not be attempted to be parsed and verified at all.

OAuth2JWTProcessingConfig

OAuth2JWTProcessingConfig specifies how individual JWTs are to be processed further.

Appears in:

OAuth2JWTConfig

Field	Description	Default	Validation
`audiences` string array	Audiences is the list of audiences to be used for the processed token. If specified the token must have an ‘aud’ claim, and it must be in this list. If not specified, the audiences will not be checked in the token.		MaxItems: 32 MinItems: 1
`claimsToHeaders` JWTClaimToHeader array	ClaimsToHeaders is a list of claims from the token that should be forwarded upstream as a header. Optionally set the claims from the JWT payload that you want to extract and add as headers to the request before the request is forwarded to the upstream destination. Note: if ClaimsToHeaders is set, the Envoy route cache will be cleared. This allows the JWT filter to correctly affect routing decisions.		MaxItems: 32 MinItems: 1

OAuth2Policy

OAuth2Policy specifies the OAuth2 policy to apply to requests.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`extensionRef` NamespacedObjectReference	ExtensionRef specifies the GatewayExtension that should be used for OAuth2.

OAuth2Provider

OAuth2Provider specifies the configuration for OAuth2 extension provider.

Appears in:

GatewayExtensionSpec

Field	Description	Default	Validation
`backendRef` BackendRef	BackendRef specifies the Backend to use for the OAuth2 provider.
`authorizationEndpoint` HttpsUri	AuthorizationEndpoint specifies the endpoint to redirect to for authorization in response to unauthorized requests. If both IssuerURI and this value are specified, the value discovered from the issuer will not be used and this takes precedence. Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-3.1 for more details.		Pattern: `^https://([a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?\.)[a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?(:[0-9]\{1,5\})?(/[a-zA-Z0-9\-._~!$&'()+,;=:@%])/?(\?[a-zA-Z0-9\-._~!$&'()+,;=:@%/?])?$`
`tokenEndpoint` HttpsUri	TokenEndpoint specifies the endpoint on the authorization server to retrieve the access token from. If both IssuerURI and this value are specified, the value discovered from the issuer will not be used and this takes precedence. Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-3.2 for more details.		Pattern: `^https://([a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?\.)[a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?(:[0-9]\{1,5\})?(/[a-zA-Z0-9\-._~!$&'()+,;=:@%])/?(\?[a-zA-Z0-9\-._~!$&'()+,;=:@%/?])?$`
`redirectURI` string	RedirectURI specifies the URL passed to the authorization endpoint. Defaults to :///oauth2/redirect, where the URL scheme and host are derived from the original request. Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more details.
`logoutPath` string	LogoutPath specifies the path to log out a user, clearing their credential cookies. Defaults to /logout.	/logout	MinLength: 1
`forwardAccessToken` boolean	ForwardAccessToken specifies whether to forward the access token to the backend service. If set to true, the token is forwarded over a cookie named BearerToken and is also set in the Authorization header. Defaults to false.
`scopes` string array	List of OAuth scopes to be claimed in the authentication request. Defaults to “user” scope if not specified. When using OpenID, the “openid” scope must be included. Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-3.3 for more details.
`credentials` OAuth2Credentials	Credentials specifies the Oauth2 client credentials to use for authentication.
`issuerURI` string	IssuerURI specifies the OpenID provider’s issuer URL to discover the OpenID provider’s configuration. The Issuer must be a URI RFC 3986 [RFC3986] with a scheme component that must be https, a host component, and optionally, port and path components and no query or fragment components. It discovers the authorizationEndpoint, tokenEndpoint, endSessionEndpoint, and jwksURI if specified in the discovery response. Explicit configuration of these options will take precedence over the discovered values. Refer to https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig for more details. Note that the OpenID provider configuration is cached and only refreshed periodically when the GatewayExtension object is reprocessed.		Pattern: `^https://([a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?\.)[a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?(:[0-9]\{1,5\})?(/[a-zA-Z0-9\-._~!$&'()+,;=:@%])/?$`
`endSessionEndpoint` HttpsUri	EndSessionEndpoint specifies the URL that redirects a user’s browser to in order to initiate a single logout across all applications and the OpenID provider. Users are directed to this endpoint when they access the logout path. This should only be set when the OpenID provider supports RP-Initiated Logout and “openid” is included in the list of scopes. If both IssuerURI and this value are specified, the value discovered from the issuer will not be used and this takes precedence. Refer to https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout for more details.		Pattern: `^https://([a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?\.)[a-zA-Z0-9]([a-zA-Z0-9\-]\{0,61\}[a-zA-Z0-9])?(:[0-9]\{1,5\})?(/[a-zA-Z0-9\-._~!$&'()+,;=:@%])/?(\?[a-zA-Z0-9\-._~!$&'()+,;=:@%/?])?$`
`cookies` OAuth2CookieConfig	Cookies specifies the configuration for the OAuth2 cookies.
`jwt` OAuth2JWTConfig	JWT specifies the configuration for whether and how to process the retrieved access and ID tokens as JSON Web Token.
`denyRedirect` OAuth2DenyRedirectMatcher	DenyRedirectMatcher specifies the matcher to match requests that should be denied redirects to the authorization endpoint. Matching requests will receive a 401 Unauthorized response instead of being redirected. This is useful for AJAX requests where redirects should be avoided.

Op

Underlying type: string

Op represents comparison operators.

Validation:

Enum: [EQ GE LE]

Appears in:

ComparisonFilter

Field	Description
`EQ`
`GE`
`LE`

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

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

PathRegexRewrite

PathRegexRewrite specifies how to rewrite the URL path.

Appears in:

URLRewrite

Field	Description	Default	Validation
`pattern` string	Pattern is the regex pattern that matches the URL path. The pattern must be a valid RE2 regular expression. If the HTTPRoute uses a RegularExpression path match, this field can use capture groups from that match.		MaxLength: 1024 MinLength: 1
`substitution` string	Substitution is the replacement string for the matched pattern. It can include backreferences to captured groups from the pattern (e.g., \1, \2) or named groups (e.g., \g).		MaxLength: 1024 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/scheduling-eviction/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.
`priorityClassName` string	If specified, the pod’s PriorityClass. See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podspec-v1-core for details

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

ProcessingMode

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

Appears in:

ExtProcPolicy
ExtProcProvider

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]

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%

ProxyProtocolConfig

ProxyProtocolConfig configures the PROXY protocol listener filter. The presence of this configuration enables PROXY protocol support.

Appears in:

ListenerConfig
ListenerDefaultConfig

Field	Description	Default	Validation
`allowRequestsWithoutProxyProtocol` boolean	AllowRequestsWithoutProxyProtocol, when true, configures the PROXY protocol listener filter to accept connections that do not include a PROXY protocol header in addition to those that do. This allows a single listener to serve mixed traffic, e.g. PROXY-preserving load balancer traffic plus direct in-cluster traffic on the same port. Security: accepting connections without a PROXY header is non-conformant with the PROXY protocol spec and allows clients to spoof the perceived source address. Only enable this when every source that can reach the listener is trusted. See https://www.haproxy.org/download/2.1/doc/proxy-protocol.txt. Defaults to false.

ProxyProtocolVersion

Underlying type: string

ProxyProtocolVersion defines the PROXY protocol version.

Validation:

Enum: [V1 V2]

Appears in:

UpstreamProxyProtocol

Field	Description
`V1`	ProxyProtocolVersionV1 is the human-readable PROXY protocol version 1.
`V2`	ProxyProtocolVersionV2 is the binary PROXY protocol version 2.

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]

RemoteJWKS

Appears in:

JWKS

Field	Description	Validation
`url` string	URL is the URL of the remote JWKS server, it must be a full FQDN with protocol, host and path. For example, https://example.com/keys	MaxLength: 2048 MinLength: 1
`backendRef` BackendObjectReference	BackendRef is reference to the backend of the JWKS server.
`cacheDuration` Duration	Duration after which the cached JWKS expires. If unspecified, the default cache duration is 5 minutes.

RequestDecompression

RequestDecompression enables request gzip decompression.

Appears in:

Compression

Field	Description	Default	Validation
`disable` PolicyDisable	Disables decompression.

ResourceDetector

ResourceDetector defines the list of supported ResourceDetectors

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

OpenTelemetryTracingConfig

Field	Description	Default	Validation
`environmentResourceDetector` EnvironmentResourceDetectorConfig	EnvironmentResourceDetector sets OpenTelemetry resource attributes from the OTEL_RESOURCE_ATTRIBUTES environment variable in the Envoy container. Default enabled if not set. If multiple are set, the last will take precedence.

ResponseCompression

ResponseCompression configures response compression.

Appears in:

Compression

Field	Description	Default	Validation
`disable` PolicyDisable	Disables compression.

ResponseFlagFilter

Underlying type: struct

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

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 (including 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

RetryBackoff

Appears in:

ExtSvcRetryPolicy

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.

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

Underlying type: struct

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

RouteTracing

RouteTracing configures per-route tracing overrides. These settings override the listener-level tracing configuration for matched routes. The tracing provider (e.g., OpenTelemetry collector endpoint) must still be configured at the listener level via ListenerPolicy. Without a listener-level tracing provider, route-level settings have no effect. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-tracing

Appears in:

TrafficPolicySpec

Field	Description	Validation
`clientSampling` integer	Target percentage of requests that will be force traced if the x-client-trace-id header is set. Overrides the listener-level setting.	Maximum: 100 Minimum: 0
`randomSampling` integer	Target percentage of requests that will be randomly selected for trace generation. Overrides the listener-level setting.	Maximum: 100 Minimum: 0
`overallSampling` integer	Target percentage of requests that will be traced after all other sampling checks have been applied. This acts as an upper limit on the total configured sampling rate. Overrides the listener-level setting.	Maximum: 100 Minimum: 0
`attributes` CustomAttribute array	Additional attributes to add to active spans for this route. These are merged with listener-level attributes configured via ListenerPolicy. On name collision, route-level attributes take priority.	MaxItems: 16 MaxProperties: 2 MinProperties: 1
`disable` PolicyDisable	Disable tracing for this route. Can be used to disable tracing for specific routes when listener-level tracing is configured via ListenerPolicy.

RuntimeFilter

Underlying type: struct

RuntimeFilter filters for random sampling of access logs. A request will be logged if the runtime key is set and the request’s random value is less than the percent_sampled value. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-runtimefilter

Appears in:

FilterType

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.

SecretReference

SecretReference identifies a Kubernetes secret containing authentication data.

Appears in:

BasicAuthPolicy

Field	Description	Default	Validation
`name` ObjectName	Name of the secret containing htpasswd data.
`namespace` Namespace	Namespace of the secret. If not specified, defaults to the namespace of the TrafficPolicy. Note that a secret in a different namespace requires a ReferenceGrant to be accessible.		MaxLength: 63 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`key` string	Key in the secret that contains the htpasswd data. Defaults to “.htpasswd” if not specified.	.htpasswd	MinLength: 1

SelfManagedGateway

Appears in:

GatewayParametersSpec

ServerHeaderTransformation

Underlying type: string

ServerHeaderTransformation determines how the server header is transformed.

Appears in:

HTTPListenerPolicySpec
HTTPSettings

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.
`loadBalancerClass` string	LoadBalancerClass is the class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix. This field can only be set when the Service type is ‘LoadBalancer’. If not set, the default load balancer implementation is used. See https://kubernetes.io/docs/concepts/services-networking/service/#load-balancer-class
`loadBalancerSourceRanges` string array	LoadBalancerSourceRanges restricts traffic through the cloud-provider load-balancer to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature. More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/

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.

SetCurrentClientCertDetails

SetCurrentClientCertDetails selects fields from the downstream client certificate to include in the XFCC header when Envoy sets or appends it. Fields default to false when unset. See: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-msg-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails

Appears in:

ForwardClientCertDetails

Field	Description	Default	Validation
`subject` boolean	Subject forwards the certificate Subject in the XFCC header.
`cert` boolean	Cert forwards the entire client certificate in URL-encoded PEM format in the XFCC header.
`chain` boolean	Chain forwards the entire client certificate chain (including the leaf certificate) in URL-encoded PEM format in the XFCC header.
`dns` boolean	DNS forwards DNS-type Subject Alternative Names from the client certificate in the XFCC header.
`uri` boolean	URI forwards the URI-type Subject Alternative Name from the client certificate in the XFCC 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

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	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
`matcher` StatsMatcher	Matcher configures inclusion or exclusion lists for Envoy stats. Only one of inclusionList or exclusionList may be set. If unset, Envoy’s default stats emission behavior applies.	MaxProperties: 1 MinProperties: 1

StatsMatcher

StatsMatcher specifies either an inclusion or exclusion list for Envoy stats. See Envoy’s envoy.config.metrics.v3.StatsMatcher for details.

Validation:

MaxProperties: 1
MinProperties: 1

Appears in:

StatsConfig

Field	Description	Default	Validation
`inclusionList` StringMatcher array	inclusionList specifies which stats to include, using string matchers.		MaxItems: 16
`exclusionList` StringMatcher array	exclusionList specifies which stats to exclude, using string matchers.		MaxItems: 16

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

StripHostPortMode

Underlying type: string

StripHostPortMode determines whether or not Envoy strips the port component from the Host/authority header.

Appears in:

HTTPListenerPolicySpec
HTTPSettings

Field	Description
`MatchingPort`	StripMatchingHostPortMode strips the port from the header if and only if it matches the listener’s own port.
`AnyPort`	StripAnyHostPortMode strips any port from the header, regardless of its value.

TCPKeepalive

See Envoy documentation for more details.

Appears in:

BackendConfigPolicySpec
ListenerConfig
ListenerDefaultConfig

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`

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
HTTPSettings

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.

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.
`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 honored 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 ListenerSets, and ignored for other targeted kinds.
`rbac` Authorization	RBAC specifies the role-based access control configuration for the policy. This defines the rules for authorization based on roles and permissions. RBAC policies applied at different attachment points in the configuration hierarchy are not cumulative, and only the most specific policy is enforced. This means an RBAC policy attached to a route will override any RBAC policies applied to the gateway or listener.
`jwtAuth` JWTAuth	JWT specifies the JWT authentication configuration for the policy. This defines the JWT providers and their configurations.
`urlRewrite` URLRewrite	UrlRewrite specifies URL rewrite rules for matching requests. NOTE: This field is only honored for HTTPRoute targets.
`compression` Compression	Compression configures response compression (per-route) and request/response decompression (listener-level insertion triggered by route enable). The response compression configuration is only honored for HTTPRoute targets.
`basicAuth` BasicAuthPolicy	BasicAuth specifies the HTTP basic authentication configuration for the policy. This controls authentication using username/password credentials in the Authorization header.
`apiKeyAuth` APIKeyAuth	APIKeyAuth authenticates users based on a configured API Key.
`oauth2` OAuth2Policy	OAuth2 specifies the configuration to use for OAuth2/OIDC. Note: the OAuth2 filter does not protect against Cross-Site-Request-Forgery attacks on domains with cached authentication (in the form of cookies). It is recommended to pair this with the CSRF policy to prevent malicious social engineering.
`tracing` RouteTracing	Tracing configures per-route tracing overrides. These settings override the listener-level tracing configuration (configured via ListenerPolicy) for matched routes. The tracing provider (e.g., OpenTelemetry collector endpoint) must be configured at the listener level via ListenerPolicy. Without a listener-level tracing provider, route-level settings have no effect. NOTE: This field is only honored for HTTPRoute and GRPCRoute targets.
`faultInjection` FaultInjectionPolicy	FaultInjection configures fault injection for chaos engineering and resiliency testing. Supports delay injection, abort injection, and response rate limiting.
`acl` ACLPolicy	ACL configures IP-based access control for HTTP requests. Rules are evaluated using longest-prefix matching on the effictive client IP from envoy base on settings. See the UseRemoteAddress, XffTrustedCIDRs, XffNumTrustedHops settings under ListenerPolicy -> HttpSettings for details. When multiple TrafficPolicy objects target the same route, their ACL fields are deep-merged by default: rules are unioned (higher-priority policy’s rules first), and singleton fields (defaultAction, denyResponse) are taken from the higher-priority policy. If singleton fields conflict between policies, the merge falls back to shallow (higher-priority policy wins entirely). Gateway-level and route-level ACL policies are kept in separate merge groups and are never combined with each other; a route-level ACL completely replaces the gateway-level ACL for that route.

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. Add is not supported on arm64 build, see docs/guides/transformation.md for details	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.
`dynamicMetadata` DynamicMetadataTransformation array	DynamicMetadata is a list of dynamic metadata entries to set. The values are stored in Envoy dynamic metadata and can be used in access log templates or consumed by other filters down the chain.	MaxItems: 16

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.

URLRewrite

URLRewrite specifies URL rewrite rules using regular expressions. This allows more flexible and advanced path rewriting based on regex patterns.

Appears in:

TrafficPolicySpec

Field	Description	Default	Validation
`pathRegex` PathRegexRewrite	Path specifies the path rewrite configuration.

UpgradeConfig

UpgradeConfig represents configuration for HTTP upgrades.

Appears in:

HTTPListenerPolicySpec
HTTPSettings

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

UpstreamProxyProtocol

UpstreamProxyProtocol configures the PROXY protocol for upstream connections.

Appears in:

BackendConfigPolicySpec

Field	Description	Default	Validation
`version` ProxyProtocolVersion	Version is the PROXY protocol version to use.	V1	Enum: [V1 V2]

UuidRequestIdConfig

UuidRequestIdConfig configures the UUID request ID extension. Based on: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/request_id/uuid/v3/uuid.proto

Appears in:

HTTPListenerPolicySpec
HTTPSettings

Field	Description	Default	Validation
`packTraceReason` boolean	PackTraceReason determines if the trace sampling decision is embedded into the UUID. Defaults to true. Set to false to prevent Envoy from mutating the Request ID, which is useful when preserving exact UUIDs from external systems.
`useRequestIdForTraceSampling` boolean	UseRequestIDForTraceSampling determines if the Request ID is used to calculate the trace sampling decision. Defaults to true. This ensures consistent sampling decisions for a given Request ID across the mesh.

ValidationMode

Underlying type: string

Appears in:

Field	Description
`Strict`	A valid token, issued by a configured issuer, must be present. This is the default option.
`AllowMissing`	If a token exists, validate it. Warning: this allows requests without a JWT token.

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.

Shared Types

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

ACLAction

Underlying type: string

ACLAction defines whether to allow or deny traffic.

Validation:

Enum=allow;deny

ACLDenyResponse

ACLDenyResponse customizes the response sent when a request is denied.

Validation:

AtLeastOneOf=statusCode;headers;blockedByHeaderName

Field	Type	Description
`statusCode`	*int32	StatusCode is the HTTP status code returned on deny. Defaults to 403.
`headers`	[]ACLResponseHeader	Headers are additional response headers to attach on every deny.
`blockedByHeaderName`	*string	BlockedByHeaderName, when set, adds a response header with this name on every deny. The header value mirrors the blocked-by dynamic metadata: the matched rule’s name, “rule” for an unnamed rule, or “default” for a default-action deny.

ACLPolicy

ACLPolicy defines IP-based access control rules evaluated on every HTTP request. The filter uses longest-prefix matching so rule order does not matter.

Field	Type	Description
`defaultAction`	ACLAction	DefaultAction is the action to take when no rule matches the client IP. Required.
`rules`	[]ACLRule	Rules is a list of IP/CIDR-based rules. Longest-prefix match wins regardless of rule order.
`denyResponse`	*ACLDenyResponse	DenyResponse customizes the HTTP response sent when a request is denied.

ACLResponseHeader

ACLResponseHeader defines a response header to include in deny responses.

Field	Type	Description
`name`	string	Name is the header name. Required.
`value`	string	Value is the header value. Required.

ACLRule

ACLRule defines an IP/CIDR-based ACL rule.

Field	Type	Description
`name`	*string	Name is an optional rule identifier emitted as blocked-by dynamic metadata on deny.
`cidrs`	[]IPOrCIDR	CIDRs is a list of IP addresses or CIDR ranges (e.g. “10.0.0.0/8”, “2001:db8::/32”, “192.168.1.1”, “::1”). Bare IPs without a prefix are treated as /32 for IPv4 and /128 for IPv6. All entries share the same name and action. Required.
`action`	ACLAction	Action determines what to do when a client IP matches this rule. Required.

AlwaysOnConfig

AlwaysOnConfig specified the AlwaysOn samplerc

AnyValue

Validation:

MaxProperties=1
MinProperties=1

Field	Type	Description
`stringValue`	*string
`arrayValue`	[]AnyValue	TODO: Add support for ArrayValue && KvListValue
`kvListValue`	*KeyAnyValueList

Authorization

Authorization defines the configuration for role-based access control.

Field	Type	Description
`policy`	AuthorizationPolicy	Policy specifies the Authorization rule to evaluate. A policy matches when any of the conditions evaluates to true. Required.
`action`	AuthorizationPolicyAction	Action defines whether the rule allows or denies the request if matched. If unspecified, the default is “Allow”.

AuthorizationPolicy

AuthorizationPolicy defines a single Authorization rule.

Field	Type	Description
`matchExpressions`	[]CELExpression	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. Required.

AuthorizationPolicyAction

Underlying type: string

AuthorizationPolicyAction defines the action to take when the RBACPolicies matches.

CELExpression

Underlying type: string

CELExpression represents a Common Expression Language (CEL) expression.

Validation:

MinLength=1
MaxLength=16384

ComparisonFilter

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

Field	Type	Description
`op`	Op	Required.
`value`	int32	Value to compare against. Required.

DenominatorType

Underlying type: string

DenominatorType defines the fraction percentages support several fixed denominator values.

Validation:

enum=HUNDRED,TEN_THOUSAND,MILLION

EnvironmentResourceDetectorConfig

EnvironmentResourceDetectorConfig specifies the EnvironmentResourceDetector configuration.

Field	Type	Description
`enable`	*bool	Enable controls whether the EnvironmentResourceDetector is used.

FractionalPercent

FractionalPercent represents a fraction as a numerator and denominator. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/type/v3/percent.proto#envoy-v3-api-msg-type-v3-fractionalpercent

Field	Type	Description
`numerator`	int32	Specifies the numerator. Defaults to 0. Required.
`denominator`	*DenominatorType	Specifies the denominator. If the denominator specified is less than the numerator, the final fractional percentage is capped at 1 (100%). Defaults to HUNDRED.

HTTPHeader

HTTPHeader represents a single header name/value pair. Exactly one of value or secretRef must be set. When using secretRef, name and key interact as follows: - Both present: name is the header name, key is the Secret data key. - name absent, key present: the key is also used as the header name. - name present, key absent: the name is also used as the Secret data key. - Both absent: every entry in the Secret is injected as a header (data key -> header name).

Validation:

ExactlyOneOf=value;secretRef
XValidation:rule=“has(self.value) ? has(self.name) : true”,message=“name is required when using an inline value”

Field	Type	Description
`name`	*gwv1.HTTPHeaderName	Name is the HTTP header field name. Name matching is case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2.) Required when value is set. When secretRef is used, if omitted the Secret data key is used as the header name; if both name and key are omitted every Secret entry is injected as a header.
`value`	*string	Value is an inline string value for the header. Mutually exclusive with secretRef. Must consist of printable US-ASCII characters. (See https://tools.ietf.org/html/rfc7230#section-3.2.)
`secretRef`	*SecretRefWithKey	SecretRef sources the header value from a key in a Kubernetes Secret. Mutually exclusive with value.

HTTPHeaderFilter

HTTPHeaderFilter defines a filter that modifies the headers of an HTTP request or response. Only one action for a given header name is permitted. Filters specifying multiple actions of the same or different type for any one header name are invalid and will be rejected by CRD validation. Configuration to set or add multiple values for a header must use RFC 7230 header value formatting, separating each value with a comma. Unlike the Gateway API HTTPHeaderFilter, each entry also supports sourcing the value from a Kubernetes Secret via secretRef.

Validation:

AtLeastOneOf=set;add;remove

Field	Type	Description
`set`	[]HTTPHeader	Set overwrites the request with the given header (name, value) before the action. Input: GET /foo HTTP/1.1 my-header: foo Config: set: - name: “my-header” value: “bar” Output: GET /foo HTTP/1.1 my-header: bar
`add`	[]HTTPHeader	Add adds the given header(s) (name, value) to the request before the action. It appends to any existing values associated with the header name. Input: GET /foo HTTP/1.1 my-header: foo Config: add: - name: “my-header” value: “bar,baz” Output: GET /foo HTTP/1.1 my-header: foo,bar,baz
`remove`	[]string	Remove the given header(s) from the HTTP request before the action. The value of Remove is a list of HTTP header names. Note that header names are case-insensitive (see https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). Input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz Config: remove: [“my-header1”, “my-header3”] Output: GET /foo HTTP/1.1 my-header2: bar

HeaderModifiers

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

Validation:

AtLeastOneOf=request;response

Field	Type	Description
`request`	*HTTPHeaderFilter	Request modifies request headers.
`response`	*HTTPHeaderFilter	Response modifies response headers.

IPOrCIDR

Underlying type: string

IPOrCIDR accepts either a bare IP address or an address range in CIDR notation. A bare IP without a prefix length is treated as /32 for IPv4 and /128 for IPv6. Note: The regex for the IP validation patterns was taken from https://www.ditig.com/validating-ipv4-and-ipv6-addresses-with-regexp

Validation:

Pattern=^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}(\/([0-9]|[1-2][0-9]|3[0-2]))?$|^((?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,7}:|:(?::[0-9A-Fa-f]{1,4}){1,7}|(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,5}(?::[0-9A-Fa-f]{1,4}){1,2}|(?:[0-9A-Fa-f]{1,4}:){1,4}(?::[0-9A-Fa-f]{1,4}){1,3}|(?:[0-9A-Fa-f]{1,4}:){1,3}(?::[0-9A-Fa-f]{1,4}){1,4}|(?:[0-9A-Fa-f]{1,4}:){1,2}(?::[0-9A-Fa-f]{1,4}){1,5}|[0-9A-Fa-f]{1,4}:(?:(?::[0-9A-Fa-f]{1,4}){1,6})|:(?:(?::[0-9A-Fa-f]{1,4}){1,6}))(\/(12[0-8]|1[0-1][0-9]|[1-9][0-9]|[0-9]))?$

KeyAnyValue

KeyValue is a key-value pair that is used to store Span attributes, Link attributes, etc.

Field	Type	Description
`key`	string	Attribute keys must be unique Required.
`value`	AnyValue	Value 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. Required.

KeyAnyValueList

A list of key-value pair that is used to store Span attributes, Link attributes, etc.

Field	Type	Description
`values`	[]KeyAnyValue	A collection of key/value pairs of key-value pairs.

KubernetesResourceOverlay

KubernetesResourceOverlay provides a mechanism to customize generated Kubernetes resources using Strategic Merge Patch semantics. # Overlay Application Order Overlays are applied after all typed configuration fields have been processed. The full merge order is: 1. GatewayClass typed configuration fields (e.g., replicas, image settings from parametersRef) 2. Gateway typed configuration fields (from infrastructure.parametersRef) 3. GatewayClass overlays are applied 4. Gateway overlays are applied This ordering means Gateway-level configuration overrides GatewayClass-level configuration at each stage. For example, if both levels set the same label, the Gateway value wins.

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

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.

Field	Type	Description
`group`	gwv1.Group	The API group of the target resource. For Kubernetes Gateway API resources, the group is `gateway.networking.k8s.io`. Required.
`kind`	gwv1.Kind	The API kind of the target resource, such as Gateway or HTTPRoute. Required.
`name`	gwv1.ObjectName	The name of the target resource. Required.

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.

Field	Type	Description
`group`	gwv1.Group	The API group of the target resource. For Kubernetes Gateway API resources, the group is `gateway.networking.k8s.io`. Required.
`kind`	gwv1.Kind	The API kind of the target resource, such as Gateway or HTTPRoute. Required.
`matchLabels`	map[string]string	Label selector to select the target resource. Required.

MetadataPathSegment

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

Field	Type	Description
`key`	string	The key used to retrieve the value in the struct Required.

NamespacedObjectReference

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

Field	Type	Description
`name`	gwv1.ObjectName	The name of the target resource. Required.
`namespace`	*gwv1.Namespace	The namespace of the target resource. If not set, defaults to the namespace of the parent object.

ObjectMetadata

ObjectMetadata contains labels and annotations for metadata overlays.

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

Op

Underlying type: string

Op represents comparison operators.

Validation:

Enum=EQ;GE;LE

PolicyAncestorStatus

Field	Type	Description
`ancestorRef`	gwv1.ParentReference	AncestorRef corresponds with a ParentRef in the spec that this PolicyAncestorStatus struct describes the status of. Required.
`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. Required.
`conditions`	[]metav1.Condition	Conditions describes the status of the Policy with respect to the given Ancestor.

PolicyDisable

PolicyDisable is used to disable a policy.

PolicyStatus

Field	Type	Description
`conditions`	[]metav1.Condition
`ancestors`	[]PolicyAncestorStatus	Required.

RateLimitDescriptorEntryGeneric

RateLimitDescriptorEntryGeneric defines a generic key-value descriptor entry.

Field	Type	Description
`key`	string	Key is the name of this descriptor entry. Required.
`value`	string	Value is the static value for this descriptor entry. Required.

SecretRefWithKey

SecretRefWithKey identifies a Kubernetes Secret and optionally a specific key within it.

Field	Type	Description
`name`	gwv1.ObjectName	Name is the name of the Kubernetes Secret. Required.
`key`	*string	Key is the key within the Secret’s data map to use as the header value. When omitted and the parent HTTPHeader.name is set, that name is used as the key. When both key and name are omitted, all entries in the Secret are injected as headers.
`namespace`	*gwv1.Namespace	Namespace is the namespace of the Secret. If omitted, defaults to the namespace of the referencing policy. Cross-namespace references require a ReferenceGrant in the target namespace permitting access from the policy’s namespace.

Timeouts

Field	Type	Description
`request`	*metav1.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`	*metav1.Duration	StreamIdle specifies a timeout for a requests’ idle streams. A value of 0 effectively disables the timeout.

Helm value reference

Was this page helpful?