API reference

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

Looking for the agentgateway data plane APIs instead? See the kgateway with agentgateway API docs.

Packages

gateway.kgateway.dev/v1alpha1

Resource Types

APIKeyAuthentication

Appears in:

Field Description Default 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:

Field Description Default 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:

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:

Field Description Default 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:

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:

Field Description Default 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

Agentgateway

Agentgateway is obsolete and retained only for backwards compatibility. Use the agentgateway.dev AgentgatewayParameters API to configure agentgateway deployments.

Appears in:

Field Description Default Validation
enabled boolean Obsolete: This field is no longer used. The agentgateway dataplane is
automatically enabled when the Gateway references a GatewayClass with
controllerName: agentgateway.dev/agentgateway. Use the AgentgatewayParameters
API to configure agentgateway deployments. Any values specified here are ignored.
logLevel string Log level for the agentgateway. Defaults to info.
Levels include “trace”, “debug”, “info”, “error”, “warn”. See: https://docs.rs/tracing/latest/tracing/struct.Level.html
image Image The agentgateway container image. See
https://kubernetes.io/docs/concepts/containers/images
for details.

Default values, which may be overridden individually:

registry: cr.agentgateway.dev
repository: agentgateway
tag:
pullPolicy: IfNotPresent
securityContext SecurityContext The security context for this container. See
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#securitycontext-v1-core
for details.
resources ResourceRequirements The compute resources required by this container. See
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
for details.
env EnvVar array The container environment variables.
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.

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:

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:

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:

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:

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

AwsAuth

AwsAuth specifies the authentication method to use for the backend.

Appears in:

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:

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

AwsBackend

AwsBackend is the AWS backend configuration.

Appears in:

Field Description Default Validation
lambda AwsLambda Lambda configures the AWS lambda service.
accountId string AccountId is the AWS account ID to use for the backend. MaxLength: 12
MinLength: 1
Pattern: ^[0-9]\{12\}$
auth AwsAuth Auth specifies an explicit AWS authentication method for the backend.
When omitted, the following credential providers are tried in order, stopping when one
of them returns an access key ID and a secret access key (the session token is optional):
1. Environment variables: when the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN are set.
2. AssumeRoleWithWebIdentity API call: when the environment variables AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN are set.
3. EKS Pod Identity: when the environment variable AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE is set.

See the Envoy docs for more info:
https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_request_signing_filter#credentials
region string Region is the AWS region to use for the backend.
Defaults to us-east-1 if not specified.		 us-east-1 MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9-]+$

AwsLambda

AwsLambda configures the AWS lambda service.

Appears in:

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

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:

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

BackendSpec

BackendSpec defines the desired state of Backend.

Appears in:

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

BackendStatus

BackendStatus defines the observed state of Backend.

Appears in:

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:

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.

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:

Field Description Default 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.

BodyParseBehavior

Underlying type: string

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

Validation:

  • Enum: [AsString AsJson]

Appears in:

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

BodyTransformation

BodyTransformation controls how the body should be parsed and transformed.

Appears in:

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.		 AsString Enum: [AsString AsJson]
value InjaTemplate Value is the template to apply to generate the output value for the body.
Only Inja templates are supported.

Buffer

Appears in:

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:

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:

Field Description Default 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:

Field Description Default 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

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:

Field Description Default 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:

Field Description Default 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:

Field Description Default 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:

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:

Field Description Default 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:

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:

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:

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:

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:

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:

Field Description Default 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.

DirectResponse

DirectResponse contains configuration for defining direct response routes.

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

DirectResponseSpec

DirectResponseSpec describes the desired state of a DirectResponse.

Appears in:

Field Description Default Validation
status integer StatusCode defines the HTTP status code to return for this route. Maximum: 599
Minimum: 200
body string Body defines the content to be returned in the HTTP response body.
The maximum length of the body is restricted to prevent excessively large responses.
If this field is omitted, no body is included in the response.		 MaxLength: 4096
MinLength: 1

DirectResponseStatus

DirectResponseStatus defines the observed state of a DirectResponse.

Appears in:

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:

DynamicForwardProxyBackend

DynamicForwardProxyBackend is the dynamic forward proxy backend configuration.

Appears in:

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.

EnvoyBootstrap

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

Appears in:

Field Description Default Validation
logLevel string Envoy log level. Options include “trace”, “debug”, “info”, “warn”, “error”,
“critical” and “off”. Defaults to “info”. See
https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/run-envoy#debugging-envoy
for more information.
componentLogLevels object (keys:string, values:string) Envoy log levels for specific components. The keys are component names and
the values are one of “trace”, “debug”, “info”, “warn”, “error”,
“critical”, or “off”, e.g.

yaml<br /> componentLogLevels:<br /> upstream: debug<br /> connection: trace<br />

These will be converted to the --component-log-level Envoy argument
value. See
https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/run-envoy#debugging-envoy
for more information.

Note: the keys and values cannot be empty, but they are not otherwise validated.

EnvoyContainer

EnvoyContainer configures the container running Envoy.

Appears in:

Field Description Default Validation
bootstrap EnvoyBootstrap Initial envoy configuration.
image Image The envoy container image. See
https://kubernetes.io/docs/concepts/containers/images
for details.

Default values, which may be overridden individually:

registry: quay.io/solo-io
repository: envoy-wrapper
tag:
pullPolicy: IfNotPresent
securityContext SecurityContext The security context for this container. See
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#securitycontext-v1-core
for details.
resources ResourceRequirements The compute resources required by this container. See
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
for details.
env EnvVar array The container environment variables.
extraVolumeMounts VolumeMount array Additional volume mounts to add to the container. See
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#volumemount-v1-core
for details.

EnvoyHealthCheck

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

Appears in:

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

ExtAuthBufferSettings

ExtAuthBufferSettings configures how the request body should be buffered.

Appears in:

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

ExtAuthPolicy

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

Appears in:

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:

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:

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:

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:

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:

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

ExtProcRouteCacheAction

Underlying type: string

Appears in:

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:

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.

FileSink

FileSink represents the file sink configuration for access logs.

Appears in:

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

FilterType

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

Validation:

  • MaxProperties: 1
  • MinProperties: 1

Appears in:

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

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:

Field Description Default 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:

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:

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 or agentgateway proxy instance), based on a Kubernetes Gateway.

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

GatewayParametersSpec

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

Appears in:

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

GatewayParametersStatus

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

Appears in:

GracefulShutdownSpec

Appears in:

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

GrpcStatusFilter

Underlying type: struct{Statuses []GrpcStatus “json:"statuses,omitempty"”; Exclude *bool “json:"exclude,omitempty"”}

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:

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:

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

HTTPSettings

Appears in:

Field Description Default 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.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address
xffNumTrustedHops integer XffNumTrustedHops is the number of additional ingress proxy hops from the right side of the X-Forwarded-For HTTP header to trust when determining the origin client’s IP address.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-xff-num-trusted-hops		 Minimum: 0
serverHeaderTransformation ServerHeaderTransformation ServerHeaderTransformation determines how the server header is transformed.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-server-header-transformation		 Enum: [Overwrite AppendIfAbsent PassThrough]
streamIdleTimeout Duration StreamIdleTimeout is the idle timeout for HTTP streams.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-stream-idle-timeout
idleTimeout Duration IdleTimeout is the idle timeout for connnections.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-msg-config-core-v3-httpprotocoloptions
healthCheck EnvoyHealthCheck HealthCheck configures Envoy health checks
preserveHttp1HeaderCase boolean PreserveHttp1HeaderCase determines whether to preserve the case of HTTP1 request headers.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing
acceptHttp10 boolean AcceptHTTP10 determines whether to accept incoming HTTP/1.0 and HTTP 0.9 requests.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-http1protocoloptions
defaultHostForHttp10 string DefaultHostForHttp10 specifies a default host for HTTP/1.0 requests. This is highly suggested if acceptHttp10 is true and a no-op if acceptHttp10 is false.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-http1protocoloptions		 MinLength: 1
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.
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

HashPolicy

Appears in:

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:

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:

HeaderName

Underlying type: string

Appears in:

HeaderSource

Underlying type: struct

HeaderSource configures how to retrieve a JWT from a header

Appears in:

HeaderTransformation

Appears in:

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:

HealthCheck

Appears in:

Field Description Default 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:

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:

Field Description Default 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:

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:

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:

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

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:

Image

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

Appears in:

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

InjaTemplate

Underlying type: string

Appears in:

IstioContainer

IstioContainer configures the container running the istio-proxy.

Appears in:

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:

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

JWKS

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

Appears in:

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:

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

JWTAuthentication

JWTAuthentication defines the providers used to configure JWT authentication

Appears in:

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:

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:

Field Description Default 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:

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.

Appears in:

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.
agentgateway Agentgateway Obsolete: This field is no longer used. Agentgateway configuration is now
determined automatically based on the GatewayClass controllerName
(agentgateway.dev/agentgateway). Use the AgentgatewayParameters API to
configure agentgateway deployments. Any values specified here are ignored.
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.

LabelSelector

LabelSelector selects resources using label selectors.

Appears in:

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

ListenerConfig

Appears in:

Field Description Default Validation
proxyProtocol ProxyProtocolConfig ProxyProtocol configures the PROXY protocol listener filter.
When set, Envoy will expect connections to include 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
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 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.

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:

Field Description Default Validation
targetRefs LocalPolicyTargetReference array TargetRefs specifies the target resources by reference to attach the policy to.
Only supports Gateway resources		 MaxItems: 16
MinItems: 1
targetSelectors LocalPolicyTargetSelector array TargetSelectors specifies the target selectors to select Gateway resources to attach the policy to.
default ListenerConfig 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:

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:

Field Description Default 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:

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:

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:

LoadBalancerRingHashConfig

LoadBalancerRingHashConfig configures the ring hash load balancer type.

Appears in:

Field Description Default 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:

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:

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:

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

LocalityType

Underlying type: string

Appears in:

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.

MetadataKey

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

Appears in:

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:

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:

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:

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 Default 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:

Field Description Default 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]

OAuth2CookieNames

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

Appears in:

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:

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:

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:

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

OAuth2Policy

OAuth2Policy specifies the OAuth2 policy to apply to requests.

Appears in:

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:

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.
Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-3.1 for more details.		 Pattern: `^https:
tokenEndpoint HttpsUri TokenEndpoint specifies the endpoint on the authorization server to retrieve the access token from.
Refer to https://datatracker.ietf.org/doc/html/rfc6749#section-3.2 for more details.		 Pattern: `^https:
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, and endSessionEndpoint if specified in the discovery response.
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:
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.
Refer to https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout for more details.		 Pattern: `^https:
cookies OAuth2CookieConfig Cookies specifies the configuration for the OAuth2 cookies.
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:

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:

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:

Field Description Default 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:

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:

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:

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

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:

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:

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:

RateLimit

RateLimit defines a rate limiting policy.

Appears in:

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:

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:

Field Description Default 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:

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:

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:

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:

Field Description Default 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:

Field Description Default Validation
disable PolicyDisable Disables decompression.

ResourceDetector

ResourceDetector defines the list of supported ResourceDetectors

Validation:

  • MaxProperties: 1
  • MinProperties: 1

Appears in:

Field Description Default Validation
environmentResourceDetector EnvironmentResourceDetectorConfig

ResponseCompression

ResponseCompression configures response compression.

Appears in:

Field Description Default Validation
disable PolicyDisable Disables compression.

ResponseFlagFilter

Underlying type: struct{Flags []string “json:"flags"”}

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:

Retry

Retry defines the retry policy

Appears in:

Field Description Default Validation
retryOn RetryOnCondition array RetryOn specifies the conditions under which a retry should be attempted. Enum: [5xx gateway-error reset reset-before-request connect-failure envoy-ratelimited retriable-4xx refused-stream retriable-status-codes http3-post-connect-failure cancelled deadline-exceeded internal resource-exhausted unavailable]
MinItems: 1
attempts integer Attempts specifies the number of retry attempts for a request.
Defaults to 1 attempt if not set.
A value of 0 effectively disables retries.		 1 Minimum: 0
perTryTimeout Duration PerTryTimeout specifies the timeout per retry attempt (incliding the initial attempt).
If a global timeout is configured on a route, this timeout must be less than the global
route timeout.
It is specified as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “1s” or “500ms”.
statusCodes HTTPRouteRetryStatusCode array StatusCodes specifies the HTTP status codes in the range 400-599 that should be retried in addition
to the conditions specified in RetryOn.		 Maximum: 599
MinItems: 1
Minimum: 400
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:

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:

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:

Sampler

Sampler defines the list of supported Samplers

Validation:

  • MaxProperties: 1
  • MinProperties: 1

Appears in:

Field Description Default Validation
alwaysOnConfig AlwaysOnConfig

SdsBootstrap

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

Appears in:

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:

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:

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:

ServerHeaderTransformation

Underlying type: string

ServerHeaderTransformation determines how the server header is transformed.

Appears in:

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:

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

ServiceAccount

Appears in:

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.

SlowStart

Appears in:

Field Description Default 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:

StaticBackend

StaticBackend references a static list of hosts.

Appears in:

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:

Field Description Default Validation
enabled boolean Whether to expose metrics annotations and ports for scraping metrics.
routePrefixRewrite string The Envoy stats endpoint to which the metrics are written
enableStatsRoute boolean Enables an additional route to the stats cluster defaulting to /stats
statsRoutePrefixRewrite string The Envoy stats endpoint with general metrics for the additional stats route
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:

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:

TCPKeepalive

See Envoy documentation for more details.

Appears in:

Field Description Default 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:

Field Description Default 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 Default 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:

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:

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:

Field Description Default 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:

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:

Field Description Default 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 XListenerSets, 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.
jwt JWTAuthentication 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.
apiKeyAuthentication APIKeyAuthentication APIKeyAuthentication 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.

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:

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

TransformationPolicy

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

Appears in:

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:

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

UpgradeConfig

UpgradeConfig represents configuration for HTTP upgrades.

Appears in:

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

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:

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