From d13fc25d38c5295e5b8d6c1a9c1fec4a2c5e9eec Mon Sep 17 00:00:00 2001 From: chandler-solo <225927786+chandler-solo@users.noreply.github.com> Date: Wed, 12 Aug 2026 08:18:24 +0000 Subject: [PATCH] docs: Update API, Helm, and Metrics reference docs for all versions Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../pages/reference/helm/2.4.x/kgateway.md | 2 + .../snippets/main/metrics-control-plane.md | 4 + content/docs/envoy/main/reference/api.md | 722 +++++++++++------- 3 files changed, 445 insertions(+), 283 deletions(-) diff --git a/assets/kgw-docs/pages/reference/helm/2.4.x/kgateway.md b/assets/kgw-docs/pages/reference/helm/2.4.x/kgateway.md index 3c0082724..74082cbf4 100644 --- a/assets/kgw-docs/pages/reference/helm/2.4.x/kgateway.md +++ b/assets/kgw-docs/pages/reference/helm/2.4.x/kgateway.md @@ -64,6 +64,7 @@ | controller.xds.tls.enabled | bool | Enable TLS encryption for xDS communication. When enabled, the xDS server (port 9977) uses TLS. You must create a Secret named 'kgateway-xds-cert' in the kgateway installation namespace. The Secret must be of type 'kubernetes.io/tls' with 'tls.crt', 'tls.key', and 'ca.crt' data fields present. | `false` | | deploymentAnnotations | object | Add annotations to the kgateway deployment. | `{}` | | discoveryNamespaceSelectors | list | List of namespace selectors (OR'ed): each entry can use 'matchLabels' or 'matchExpressions' (AND'ed within each entry if used together). Kgateway includes the selected namespaces in config discovery. For more information, see the docs https://kgateway.dev/docs/envoy/latest/install/advanced/#namespace-discovery. | `[]` | +| enableRouteSourceMetadata | bool | Enable attaching dev.kgateway.route_source filter metadata to every Envoy route. This metadata includes the Kubernetes source object (kind, group, name, namespace, rule) for each route, which helps correlate Envoy routes with their originating Kubernetes resources. Default is false (disabled). Note: This feature is experimental and subject to breaking changes in future releases. | `false` | | fullnameOverride | string | Override the full name of resources created by the Helm chart, which is 'kgateway'. If you set 'fullnameOverride: "foo", the full name of the resources that the Helm release creates become 'foo', such as the deployment, service, and service account for the kgateway control plane in the kgateway-system namespace. | `""` | | gatewayClassParametersRefs | object | Map of GatewayClass names to GatewayParameters references that will be set on the default GatewayClasses managed by kgateway. Each entry must define both the name and namespace of the GatewayParameters resource. The default GatewayClasses managed by kgateway are: - kgateway - kgateway-waypoint Example: gatewayClassParametersRefs: kgateway: name: shared-gwp namespace: kgateway-system | `{}` | | image | object | Configure the default container image for the components that Helm deploys. You can override these settings for each particular component in that component's section, such as 'controller.image' for the kgateway control plane. If you use your own private registry, make sure to include the imagePullSecrets. | `{"pullPolicy":"IfNotPresent","registry":"cr.kgateway.dev/kgateway-dev","tag":""}` | @@ -76,6 +77,7 @@ | podAnnotations | object | Add annotations to the kgateway pods. This field is deprecated in favor of controller.podAnnotations and will be removed in v3.0. | `{}` | | podSecurityContext | object | Set the pod-level security context. For example, 'fsGroup: 2000' sets the filesystem group to 2000. This field is deprecated in favor of controller.podSecurityContext and will be removed in v3.0. | `{}` | | policyMerge | object | Policy merging settings. Currently, TrafficPolicy's extAuth, extProc, and transformation policies support deep merging. E.g., to enable deep merging of extProc policy in TrafficPolicy: policyMerge: trafficPolicy: extProc: DeepMerge | `{}` | +| rbac | object | Configure RBAC resources (ClusterRole and ClusterRoleBinding) for the deployment. | `{"create":true}` | | resources | object | Configure resource requests and limits for the container, such as 'limits.cpu: 100m' or 'requests.memory: 128Mi'. This field is deprecated in favor of controller.resources and will be removed in v3.0. | `{}` | | securityContext | object | Set the container-level security context, such as 'runAsNonRoot: true'. This field is deprecated in favor of controller.securityContext and will be removed in v3.0. | `{}` | | serviceAccount | object | Configure the service account for the deployment. | `{"annotations":{},"create":true,"name":""}` | diff --git a/assets/kgw-docs/snippets/main/metrics-control-plane.md b/assets/kgw-docs/snippets/main/metrics-control-plane.md index 1d61233b7..4ddef14f1 100644 --- a/assets/kgw-docs/snippets/main/metrics-control-plane.md +++ b/assets/kgw-docs/snippets/main/metrics-control-plane.md @@ -3,6 +3,10 @@ Name|Type|Labels|Help kgateway_controller_reconcile_duration_seconds|histogram|controller, name, namespace|Reconcile duration for controller kgateway_controller_reconciliations_running|gauge|controller, name, namespace|Number of reconciliations currently running kgateway_controller_reconciliations_total|counter|controller, name, namespace, result|Total number of controller reconciliations +kgateway_ec2_discovery_endpoints_active|gauge|namespace, name|Current number of active Envoy endpoints discovered for an EC2 Backend +kgateway_ec2_discovery_error_state|gauge|namespace, name|Whether the most recent EC2 discovery poll for a Backend failed (1) or succeeded (0) +kgateway_ec2_discovery_poll_duration_seconds|histogram|namespace, name, result|Duration of EC2 endpoint discovery polls per Backend +kgateway_ec2_discovery_poll_total|counter|namespace, name, result, reason|Total number of EC2 endpoint discovery refresh attempts per Backend kgateway_envoy_xds_rejects_active|gauge|gateway_namespace, gateway_name, type_url|Number of xDS responses currently rejected by envoy proxy kgateway_envoy_xds_rejects_total|counter|gateway_namespace, gateway_name, type_url|Total number of xDS responses rejected by envoy proxy kgateway_resources_managed|gauge|namespace, parent, resource|Current number of resources managed diff --git a/content/docs/envoy/main/reference/api.md b/content/docs/envoy/main/reference/api.md index 395e19274..230f1eaef 100644 --- a/content/docs/envoy/main/reference/api.md +++ b/content/docs/envoy/main/reference/api.md @@ -17,7 +17,6 @@ weight: 10 - [DirectResponse](#directresponse) - [GatewayExtension](#gatewayextension) - [GatewayParameters](#gatewayparameters) -- [HTTPListenerPolicy](#httplistenerpolicy) - [ListenerPolicy](#listenerpolicy) - [TrafficPolicy](#trafficpolicy) @@ -94,7 +93,6 @@ AccessLog represents the top-level access log configuration. _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -107,7 +105,7 @@ _Appears in:_ #### AccessLogFilter - +_Underlying type:_ _struct_ 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 @@ -118,17 +116,12 @@ _Validation:_ _Appears in:_ - [AccessLog](#accesslog) -- [LocalReplyMapper](#localreplymapper) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `andFilter` _[FilterType](#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](#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 - +_Underlying type:_ _struct_ 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 @@ -138,21 +131,19 @@ Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_logger _Appears in:_ - [AccessLog](#accesslog) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `backendRef` _[BackendRef](https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | The timeout for the gRPC request. This is the timeout for a specific request | | | -| `initialMetadata` _[HeaderValue](#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](#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 | | | +#### AlwaysOnConfig + + + +AlwaysOnConfig specified the AlwaysOn samplerc + + + +_Appears in:_ +- [Sampler](#sampler) + #### AnyValue @@ -227,6 +218,8 @@ _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"] | | | +| `headersToClient` _string array_ | HeadersToClient specifies which headers from the authorization response
should be forwarded back to the downstream client when the request is denied.
Maps to Envoy's allowed_client_headers. Required for redirect-based flows
(e.g. oauth2-proxy returning 302 + Location) so that the redirect Location
header reaches the browser on denial.
Common examples: ["location", "set-cookie", "www-authenticate"] | | | +| `headersToClientOnSuccess` _string array_ | HeadersToClientOnSuccess specifies which headers from the authorization response
should be forwarded back to the downstream client when the request is allowed.
Maps to Envoy's allowed_client_headers_on_success.
Common examples: ["set-cookie", "x-auth-token"] | | | #### AwsAddressType @@ -481,11 +474,12 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `type` _[BackendType](#backendtype)_ | Type indicates the type of the backend to be used.
Deprecated: The Type field is deprecated and will be removed in a future release.
The backend type is inferred from the configuration. | | Enum: [AWS Static DynamicForwardProxy GCP]
| +| `type` _[BackendType](#backendtype)_ | Type indicates the type of the backend to be used.
Deprecated: The Type field is deprecated and will be removed in a future release.
The backend type is inferred from the configuration. | | Enum: [AWS Static DynamicForwardProxy GCP PriorityGroups]
| | `aws` _[AwsBackend](#awsbackend)_ | Aws is the AWS backend configuration. | | | | `static` _[StaticBackend](#staticbackend)_ | Static is the static backend configuration. | | | | `dynamicForwardProxy` _[DynamicForwardProxyBackend](#dynamicforwardproxybackend)_ | DynamicForwardProxy is the dynamic forward proxy backend configuration. | | | | `gcp` _[GcpBackend](#gcpbackend)_ | Gcp is the GCP backend configuration. | | | +| `priorityGroups` _[PriorityGroup](#prioritygroup) array_ | PriorityGroups is an ordered list of backend groups used for failover.
Traffic is sent to the backends of the first group; each subsequent
group is only used when the backends of all preceding groups are
unhealthy. The health check can be configured via the BackendConfigPolicy
that targets this Backend

Note: This field is part of an experimental API and subject to breaking changes in future releases. | | MaxItems: 16
MinItems: 1
| #### BackendStatus @@ -521,8 +515,25 @@ _Appears in:_ | `Static` | BackendTypeStatic is the type for static backends.
| | `DynamicForwardProxy` | BackendTypeDynamicForwardProxy is the type for dynamic forward proxy backends.
| | `GCP` | BackendTypeGCP is the type for GCP backends.
| +| `PriorityGroups` | BackendTypePriorityGroups is the type for priority groups backends.
| +#### BackoffStrategy + + + +Configuration defining a jittered exponential back off strategy. +Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/backoff.proto#envoy-v3-api-msg-config-core-v3-backoffstrategy + + + +_Appears in:_ +- [RetryPolicy](#retrypolicy) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `baseInterval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | The base interval to be used for the next back off computation. It should be greater than zero and less than or equal to max_interval. | | | +| `maxInterval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | Specifies the maximum interval between retries. This parameter is optional, but must be greater than or equal to the base_interval if set. The default is 10 times the base_interval. | | | #### BasicAuthPolicy @@ -601,7 +612,7 @@ _Appears in:_ #### CELFilter -_Underlying type:_ _struct_ + CELFilter filters requests based on Common Expression Language (CEL). @@ -610,6 +621,9 @@ CELFilter filters requests based on Common Expression Language (CEL). _Appears in:_ - [FilterType](#filtertype) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `match` _string_ | The CEL expressions to evaluate. AccessLogs are only emitted when the CEL expressions evaluates to true.
see: https://www.envoyproxy.io/docs/envoy/v1.33.0/xds/type/v3/cel.proto.html#common-expression-language-cel-proto | | | #### CSRFPolicy @@ -687,29 +701,6 @@ _Appears in:_ | `Optional` | ClientCertificateValidationModeOptional allows connections without client certificates
but validates the certificate if one is presented. If validation fails, the connection is rejected.
| -#### CommonAccessLogGrpcService - - - -Common configuration for gRPC access logs. -Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto#envoy-v3-api-msg-extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - -_Appears in:_ -- [AccessLogGrpcService](#accessloggrpcservice) -- [OpenTelemetryAccessLogService](#opentelemetryaccesslogservice) - -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `backendRef` _[BackendRef](https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | The timeout for the gRPC request. This is the timeout for a specific request | | | -| `initialMetadata` _[HeaderValue](#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](#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 @@ -723,7 +714,6 @@ Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/grpc_serv _Appears in:_ -- [AccessLogGrpcService](#accessloggrpcservice) - [CommonAccessLogGrpcService](#commonaccessloggrpcservice) - [OpenTelemetryTracingConfig](#opentelemetrytracingconfig) @@ -758,156 +748,141 @@ _Appears in:_ | `maxRequestsPerConnection` _integer_ | Maximum requests for a single upstream connection.
If set to 0 or unspecified, defaults to unlimited. | | Minimum: 0
| - - -#### Compression +#### ComparisonFilter -Compression configures HTTP gzip compression and decompression behavior. +ComparisonFilter represents a filter based on a comparison. +Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-comparisonfilter _Appears in:_ -- [TrafficPolicySpec](#trafficpolicyspec) +- [DurationFilter](#durationfilter) +- [StatusCodeFilter](#statuscodefilter) | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `responseCompression` _[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)_ | RequestDecompression controls request decompression.
If set, gzip requests will be decompressed. | | | - +| `op` _[Op](#op)_ | | | Enum: [EQ GE LE]
| +| `value` _integer_ | Value to compare against. | | Format: uint32
Maximum: 4.294967295e+09
Minimum: 0
| -#### Cookie +#### Compression +Compression configures HTTP response compression and request decompression behavior. _Appears in:_ -- [HashPolicy](#hashpolicy) +- [TrafficPolicySpec](#trafficpolicyspec) | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | 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 - +| `responseCompression` _[ResponseCompression](#responsecompression)_ | ResponseCompression controls response compression to the downstream.
If set, responses with a matching `Accept-Encoding` header and certain textual content types will be compressed.
The compression codecs default to gzip and can be selected via `responseCompression.libraries`,
which Envoy negotiates against the request's `Accept-Encoding` header.
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)_ | RequestDecompression controls request decompression.
If set, request bodies in the configured codecs are decompressed before forwarding. | | | +#### CompressionLibrary +_Underlying type:_ _string_ +CompressionLibrary identifies a compression codec used to compress responses or decompress requests. +_Validation:_ +- Enum: [Gzip Brotli Zstd] _Appears in:_ -- [TrafficPolicySpec](#trafficpolicyspec) +- [RequestDecompression](#requestdecompression) +- [ResponseCompression](#responsecompression) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `disable` _[PolicyDisable](#policydisable)_ | Disable the CORS filter.
Can be used to disable CORS policies applied at a higher level in the config hierarchy. | | | +| Field | Description | +| --- | --- | +| `Gzip` | CompressionGzip selects the gzip compressor.
| +| `Brotli` | CompressionBrotli selects the brotli compressor.
| +| `Zstd` | CompressionZstd selects the zstd compressor.
| -#### CustomAttribute +#### ConnectionKeepalive -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 +ConnectionKeepalive configures HTTP/2 keepalive PINGs for upstream connections. +See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-msg-config-core-v3-keepalivesettings) for more details. + -_Validation:_ -- MaxProperties: 2 -- MinProperties: 1 _Appears in:_ -- [RouteTracing](#routetracing) -- [Tracing](#tracing) +- [Http2ProtocolOptions](#http2protocoloptions) | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `name` _string_ | The name of the attribute | | | -| `literal` _[CustomAttributeLiteral](#customattributeliteral)_ | A literal attribute value. | | | -| `environment` _[CustomAttributeEnvironment](#customattributeenvironment)_ | An environment attribute value. | | | -| `requestHeader` _[CustomAttributeHeader](#customattributeheader)_ | A request header attribute value. | | | -| `metadata` _[CustomAttributeMetadata](#customattributemetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | Timeout after which the connection is closed if no response to a keepalive
PING is received. A PING response is considered received if any frame
arrives on the connection while the PING is outstanding. | | | +| `interval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | Interval between keepalive PINGs. If unset, PINGs are only sent when
triggered by ConnectionIdleInterval. | | | +| `connectionIdleInterval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | If set, a PING is sent before dispatching new streams on a connection that
has been idle for at least this duration, verifying the connection is
still alive before reusing it. | | | -#### CustomAttributeEnvironment +#### Cookie + -Environment type attribute with environment name and default value. -Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#type-tracing-v3-customtag-environment _Appears in:_ -- [CustomAttribute](#customattribute) +- [HashPolicy](#hashpolicy) | 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. | | | +| `name` _string_ | Name of the cookie. | | MinLength: 1
| +| `path` _string_ | Path is the name of the path for the cookie. | | | +| `ttl` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | 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 -#### CustomAttributeHeader -Header type attribute with header name and default value. -https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#type-tracing-v3-customtag-header _Appears in:_ -- [CustomAttribute](#customattribute) +- [TrafficPolicySpec](#trafficpolicyspec) | 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 +| `disable` _[PolicyDisable](#policydisable)_ | Disable the CORS filter.
Can be used to disable CORS policies applied at a higher level in the config hierarchy. | | | +#### CustomAttribute -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 +_Underlying type:_ _struct_ +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:_ -- [CustomAttribute](#customattribute) - -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `value` _string_ | Static literal value to populate the attribute value. | | | +- [RouteTracing](#routetracing) +- [Tracing](#tracing) -#### CustomAttributeMetadata -Metadata type attribute using MetadataKey to retrieve the protobuf value from Metadata, and populate the attribute value with the canonical JSON representation of it. -Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#type-tracing-v3-customtag-metadata -_Appears in:_ -- [CustomAttribute](#customattribute) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `kind` _[MetadataKind](#metadatakind)_ | Specify what kind of metadata to obtain attribute value from | | Enum: [Request Route Cluster Host]
| -| `metadataKey` _[MetadataKey](#metadatakey)_ | Metadata key to define the path to retrieve the attribute value. | | | -| `defaultValue` _string_ | When no valid metadata is found, the attribute value would be populated with this default value if specified, otherwise no attribute would be populated. | | | #### DNS @@ -1013,6 +988,10 @@ Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v _Appears in:_ - [FilterType](#filtertype) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `op` _[Op](#op)_ | | | Enum: [EQ GE LE]
| +| `value` _integer_ | Value to compare against. | | Format: uint32
Maximum: 4.294967295e+09
Minimum: 0
| #### DynamicForwardProxyBackend @@ -1066,6 +1045,20 @@ _Appears in:_ | `stringValue` _[InjaTemplate](#injatemplate)_ | StringValue is an Inja template whose rendered output is stored as the metadata string value. | | MinLength: 1
| +#### EnvironmentResourceDetectorConfig + + + +EnvironmentResourceDetectorConfig specifies the EnvironmentResourceDetector configuration. + + + +_Appears in:_ +- [ResourceDetector](#resourcedetector) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `enable` _boolean_ | Enable controls whether the EnvironmentResourceDetector is used. | true | | #### EnvoyBootstrap @@ -1121,7 +1114,6 @@ The filter will be configured in No pass through mode, and will only match reque _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -1393,7 +1385,7 @@ _Appears in:_ #### FileSink - +_Underlying type:_ _struct_ FileSink represents the file sink configuration for access logs. @@ -1402,11 +1394,6 @@ FileSink represents the file sink configuration for access logs. _Appears in:_ - [AccessLog](#accesslog) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `path` _string_ | the file path to which the file access logging service will sink | | | -| `stringFormat` _string_ | the format string by which envoy will format the log lines
https://www.envoyproxy.io/docs/envoy/v1.33.0/configuration/observability/access_log/usage#format-strings | | | -| `jsonFormat` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#rawextension-runtime-pkg)_ | the format object by which to envoy will emit the logs in a structured way.
https://www.envoyproxy.io/docs/envoy/v1.33.0/configuration/observability/access_log/usage#format-dictionaries | | | #### FilterStage @@ -1468,31 +1455,6 @@ _Appears in:_ | `weight` _integer_ | Weight controls ordering among multiple filters at the same
stage and predicate. Higher weight places the filter earlier in the
chain. Defaults to 0. Filters with the same stage, predicate, and
weight are sorted alphabetically by filter name for consistency. | 0 | | -#### FilterType - - - -FilterType represents the type of filter to apply (only one of these should be set). -Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#envoy-v3-api-msg-config-accesslog-v3-accesslogfilter - -_Validation:_ -- MaxProperties: 1 -- MinProperties: 1 - -_Appears in:_ -- [AccessLogFilter](#accesslogfilter) - -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `statusCodeFilter` _[StatusCodeFilter](#statuscodefilter)_ | | | | -| `durationFilter` _[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](#headerfilter)_ | | | | -| `responseFlagFilter` _[ResponseFlagFilter](#responseflagfilter)_ | | | | -| `grpcStatusFilter` _[GrpcStatusFilter](#grpcstatusfilter)_ | | | | -| `celFilter` _[CELFilter](#celfilter)_ | | | | -| `runtimeFilter` _[RuntimeFilter](#runtimefilter)_ | Filters for random sampling of access logs.
Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-runtimefilter | | | #### ForwardClientCertDetails @@ -1505,7 +1467,6 @@ header forwarded to upstream backends. _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -1534,6 +1495,22 @@ _Appears in:_ | `AlwaysForwardOnly` | ForwardClientCertModeAlwaysForwardOnly always forwards the XFCC header, even for non-mTLS connections.
| +#### FractionalPercent + + + +FractionalPercent represents a fraction as a numerator and denominator. +Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/type/v3/percent.proto#envoy-v3-api-msg-type-v3-fractionalpercent + + + +_Appears in:_ +- [RuntimeFilter](#runtimefilter) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `numerator` _integer_ | Specifies the numerator. Defaults to 0. | | Minimum: 0
| +| `denominator` _[DenominatorType](#denominatortype)_ | Specifies the denominator. If the denominator specified is less than the numerator,
the final fractional percentage is capped at 1 (100%).
Defaults to HUNDRED. | | Enum: [HUNDRED TEN_THOUSAND MILLION]
| #### GatewayExtension @@ -1723,87 +1700,55 @@ _Appears in:_ | `sleepTimeSeconds` _integer_ | Time (in seconds) for the preStop hook to wait before allowing Envoy to terminate | | Maximum: 3.1536e+07
Minimum: 0
| +#### GrpcStatus +_Underlying type:_ _string_ -#### GrpcStatusFilter - -_Underlying type:_ _struct_ - -GrpcStatusFilter filters gRPC requests based on their response status. -Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#enum-config-accesslog-v3-grpcstatusfilter-status - +GrpcStatus represents possible gRPC statuses. +_Validation:_ +- Enum: [OK CANCELED UNKNOWN INVALID_ARGUMENT DEADLINE_EXCEEDED NOT_FOUND ALREADY_EXISTS PERMISSION_DENIED RESOURCE_EXHAUSTED FAILED_PRECONDITION ABORTED OUT_OF_RANGE UNIMPLEMENTED INTERNAL UNAVAILABLE DATA_LOSS UNAUTHENTICATED] _Appears in:_ -- [FilterType](#filtertype) +- [GrpcStatusFilter](#grpcstatusfilter) +| Field | Description | +| --- | --- | +| `OK` | | +| `CANCELED` | | +| `UNKNOWN` | | +| `INVALID_ARGUMENT` | | +| `DEADLINE_EXCEEDED` | | +| `NOT_FOUND` | | +| `ALREADY_EXISTS` | | +| `PERMISSION_DENIED` | | +| `RESOURCE_EXHAUSTED` | | +| `FAILED_PRECONDITION` | | +| `ABORTED` | | +| `OUT_OF_RANGE` | | +| `UNIMPLEMENTED` | | +| `INTERNAL` | | +| `UNAVAILABLE` | | +| `DATA_LOSS` | | +| `UNAUTHENTICATED` | | -#### 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | -| `spec` _[HTTPListenerPolicySpec](#httplistenerpolicyspec)_ | | | | -| `status` _[PolicyStatus](#policystatus)_ | | | | - - -#### HTTPListenerPolicySpec +#### GrpcStatusFilter -HTTPListenerPolicySpec defines the desired state of a HTTP listener policy. +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) +- [FilterType](#filtertype) | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `targetRefs` _[LocalPolicyTargetReference](#localpolicytargetreference) array_ | TargetRefs specifies the target resources by reference to attach the policy to. | | MaxItems: 16
MinItems: 1
| -| `targetSelectors` _[LocalPolicyTargetSelector](#localpolicytargetselector) array_ | TargetSelectors specifies the target selectors to select resources to attach the policy to. | | | -| `accessLog` _[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)_ | 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 | | | -| `localReplies` _[LocalReplyConfig](#localreplyconfig)_ | LocalReplies configures how Envoy's local replies are formatted etc. | | | -| `upgradeConfig` _[UpgradeConfig](#upgradeconfig)_ | UpgradeConfig contains configuration for HTTP upgrades like WebSocket.
See here for more information: https://www.envoyproxy.io/docs/envoy/v1.34.1/intro/arch_overview/http/upgrades.html | | | -| `useRemoteAddress` _boolean_ | UseRemoteAddress determines whether to use the remote address for the original client.
Note: If this field is omitted, it will fallback to the default value of 'true', which we set for all Envoy HCMs.
Thus, setting this explicitly to true is unnecessary (but will not cause any harm).
When true, Envoy will use the remote address of the connection as the client address.
When false, Envoy will use the X-Forwarded-For header to determine the client address. Furthermore, SkipXffAppend will implicitly be set to true unless explicitly configured.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address | | | -| `preserveExternalRequestId` _boolean_ | PreserveExternalRequestId determines whether the connection manager will keep the x-request-id header if passed for
a request that is edge (Edge request is the request from external clients to front Envoy) and not reset it, which is the current Envoy behaviour. This defaults to false.
See here for more information https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-preserve-external-request-id | | | -| `generateRequestId` _boolean_ | GenerateRequestId: Whether the connection manager will generate the x-request-id header if it does not exist.
This defaults to true. Generating a random UUID4 is expensive so in high throughput scenarios where this feature is not desired it can be disabled.
See here for more information https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-generate-request-id | | | -| `xffNumTrustedHops` _integer_ | XffNumTrustedHops is the number of additional ingress proxy hops from the right side of the X-Forwarded-For HTTP header to trust when determining the origin client's IP address.
This is mutually exclusive with XffTrustedCIDRs.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-xff-num-trusted-hops | | Minimum: 0
| -| `xffTrustedCIDRs` _CIDR array_ | XffTrustedCIDRs are ranges of IPs that may appear in the X-Forwarded-For HTTP header and are trusted when determining the origin client's IP address.
This is mutually exclusive with XffNumTrustedHops and requires UseRemoteAddress to be set to false.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/xff/v3/xff.proto#envoy-v3-api-field-extensions-http-original-ip-detection-xff-v3-xffconfig-xff-trusted-cidrs | | MinItems: 1
| -| `skipXFFAppend` _boolean_ | SkipXffAppend specifies whether to skip adding the downstream's remote IP address to the X-Forwarded-For HTTP header.
Note: If omitted, this effectively will default to true when UseRemoteAddress is false, such that Envoy acts as a "transparent proxy".
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-skip-xff-append | | | -| `serverHeaderTransformation` _[ServerHeaderTransformation](#serverheadertransformation)_ | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | IdleTimeout is the idle timeout for connections.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-msg-config-core-v3-httpprotocoloptions | | | -| `maxRequestsPerConnection` _integer_ | MaxRequestsPerConnection sets the maximum number of requests served over a single downstream
keepalive connection. When the limit is reached, Envoy closes the connection, which forces
clients to reconnect. This allows L4 load balancers like AWS NLB to rebalance long-lived
HTTP/2 and gRPC connections across gateway pods.
If set to 0 or unspecified, defaults to unlimited.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-requests-per-connection | | Minimum: 0
| -| `maxHeadersCount` _integer_ | MaxHeadersCount sets the maximum number of headers allowed in a request.
Downstream requests that exceed this limit will receive a 431 response for HTTP/1.x and a
stream reset for HTTP/2. If unset, defaults to Envoy's built-in default of 100.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-headers-count | | Minimum: 1
| -| `http2ProtocolOptions` _[ListenerHTTP2ProtocolOptions](#listenerhttp2protocoloptions)_ | Http2ProtocolOptions configures downstream HTTP/2 behavior on the listener's
HttpConnectionManager.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-http2protocoloptions | | | -| `healthCheck` _[EnvoyHealthCheck](#envoyhealthcheck)_ | HealthCheck configures [Envoy health checks](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/health_check/v3/health_check.proto) | | | -| `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](https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#httpheaderfilter)_ | EarlyRequestHeaderModifier defines header modifications to be applied early in the request processing,
before route selection.
For example, if you use ExternalAuthz to add a header, you may want to remove it here, to make
sure it did not come from the client. | | | -| `forwardClientCertDetails` _[ForwardClientCertDetails](#forwardclientcertdetails)_ | ForwardClientCertDetails configures how Envoy handles the x-forwarded-client-cert (XFCC)
header and which parts of the downstream client certificate are forwarded to upstream
backends. Most modes only have effect on listeners where mTLS is configured. The exceptions
are Sanitize, which strips XFCC unconditionally, and AlwaysForwardOnly, which forwards XFCC
unconditionally; on a non-mTLS listener under any other mode the setting is a no-op.
See: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forward-client-cert-details | | | -| `maxRequestHeadersKb` _integer_ | MaxRequestHeadersKb sets the maximum size of request headers that Envoy will accept.
If unset, the Envoy default is 60 KiB.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-max-request-headers-kb | | Maximum: 8192
Minimum: 1
| -| `uuidRequestIdConfig` _[UuidRequestIdConfig](#uuidrequestidconfig)_ | UuidRequestIdConfig configures the behavior of the UUID request ID extension.
This extension sets the x-request-id header to a UUID value. | | | -| `stripHostPortMode` _[StripHostPortMode](#striphostportmode)_ | StripHostPortMode determines whether, and under what conditions, Envoy will strip the port
from the Host/authority header. StripMatchingHostPort strips the port only if it matches
the listener's own port. StripAnyHostPort strips the port unconditionally.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-strip-matching-host-port
See also: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-strip-any-host-port | | Enum: [MatchingPort AnyPort]
| +| `statuses` _[GrpcStatus](#grpcstatus) array_ | | | Enum: [OK CANCELED UNKNOWN INVALID_ARGUMENT DEADLINE_EXCEEDED NOT_FOUND ALREADY_EXISTS PERMISSION_DENIED RESOURCE_EXHAUSTED FAILED_PRECONDITION ABORTED OUT_OF_RANGE UNIMPLEMENTED INTERNAL UNAVAILABLE DATA_LOSS UNAUTHENTICATED]
MinItems: 1
| +| `exclude` _boolean_ | | | | #### HTTPSettings @@ -1815,7 +1760,6 @@ _Appears in:_ _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [ListenerConfig](#listenerconfig) - [ListenerDefaultConfig](#listenerdefaultconfig) @@ -1828,10 +1772,12 @@ _Appears in:_ | `useRemoteAddress` _boolean_ | UseRemoteAddress determines whether to use the remote address for the original client.
Note: If this field is omitted, it will fallback to the default value of 'true', which we set for all Envoy HCMs.
Thus, setting this explicitly to true is unnecessary (but will not cause any harm).
When true, Envoy will use the remote address of the connection as the client address.
When false, Envoy will use the X-Forwarded-For header to determine the client address. Furthermore, SkipXffAppend will implicitly be set to true unless explicitly configured.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address | | | | `preserveExternalRequestId` _boolean_ | PreserveExternalRequestId determines whether the connection manager will keep the x-request-id header if passed for
a request that is edge (Edge request is the request from external clients to front Envoy) and not reset it, which is the current Envoy behaviour. This defaults to false.
See here for more information https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-preserve-external-request-id | | | | `generateRequestId` _boolean_ | GenerateRequestId: Whether the connection manager will generate the x-request-id header if it does not exist.
This defaults to true. Generating a random UUID4 is expensive so in high throughput scenarios where this feature is not desired it can be disabled.
See here for more information https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-generate-request-id | | | +| `proxy100Continue` _boolean_ | Proxy100Continue determines whether Envoy forwards requests with an
Expect: 100-continue header upstream and proxies upstream 100 Continue
responses downstream. When unset or false, Envoy handles the response locally. | | | | `xffNumTrustedHops` _integer_ | XffNumTrustedHops is the number of additional ingress proxy hops from the right side of the X-Forwarded-For HTTP header to trust when determining the origin client's IP address.
This is mutually exclusive with XffTrustedCIDRs.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-xff-num-trusted-hops | | Minimum: 0
| | `xffTrustedCIDRs` _CIDR array_ | XffTrustedCIDRs are ranges of IPs that may appear in the X-Forwarded-For HTTP header and are trusted when determining the origin client's IP address.
This is mutually exclusive with XffNumTrustedHops and requires UseRemoteAddress to be set to false.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/xff/v3/xff.proto#envoy-v3-api-field-extensions-http-original-ip-detection-xff-v3-xffconfig-xff-trusted-cidrs | | MinItems: 1
| | `skipXFFAppend` _boolean_ | SkipXffAppend specifies whether to skip adding the downstream's remote IP address to the X-Forwarded-For HTTP header.
Note: If omitted, this effectively will default to true when UseRemoteAddress is false, such that Envoy acts as a "transparent proxy".
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-skip-xff-append | | | | `serverHeaderTransformation` _[ServerHeaderTransformation](#serverheadertransformation)_ | 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]
| +| `serverName` _string_ | ServerName determines the value of the server header.
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-name | | MinLength: 1
| | `streamIdleTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | IdleTimeout is the idle timeout for connections.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-msg-config-core-v3-httpprotocoloptions | | | | `maxRequestsPerConnection` _integer_ | MaxRequestsPerConnection sets the maximum number of requests served over a single downstream
keepalive connection. When the limit is reached, Envoy closes the connection, which forces
clients to reconnect. This allows L4 load balancers like AWS NLB to rebalance long-lived
HTTP/2 and gRPC connections across gateway pods.
If set to 0 or unspecified, defaults to unlimited.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-requests-per-connection | | Minimum: 0
| @@ -1846,6 +1792,7 @@ _Appears in:_ | `maxRequestHeadersKb` _integer_ | MaxRequestHeadersKb sets the maximum size of request headers that Envoy will accept.
If unset, the Envoy default is 60 KiB.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-max-request-headers-kb | | Maximum: 8192
Minimum: 1
| | `uuidRequestIdConfig` _[UuidRequestIdConfig](#uuidrequestidconfig)_ | UuidRequestIdConfig configures the behavior of the UUID request ID extension.
This extension sets the x-request-id header to a UUID value. | | | | `stripHostPortMode` _[StripHostPortMode](#striphostportmode)_ | StripHostPortMode determines whether, and under what conditions, Envoy will strip the port
from the Host/authority header. StripMatchingHostPort strips the port only if it matches
the listener's own port. StripAnyHostPort strips the port unconditionally.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-strip-matching-host-port
See also: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-strip-any-host-port | | Enum: [MatchingPort AnyPort]
| +| `stripTrailingHostDot` _boolean_ | StripTrailingHostDot determines whether Envoy strips the trailing dot from the
Host/authority header before any filter processing or route matching. Without this,
a request whose host is a fully qualified domain name with a trailing dot (for example
"example.com.") does not match routes configured for the hostname "example.com".
The stripped value is also what gets forwarded upstream.
If unset, the trailing dot is kept (Envoy's default).
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-strip-trailing-host-dot | | | #### HashPolicy @@ -1886,7 +1833,7 @@ _Appears in:_ #### 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 @@ -1896,6 +1843,9 @@ Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v _Appears in:_ - [FilterType](#filtertype) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `header` _[HTTPHeaderMatch](https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#httpheadermatch)_ | | | | #### HeaderName @@ -1943,7 +1893,7 @@ _Appears in:_ #### 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 @@ -1951,10 +1901,13 @@ Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.prot _Appears in:_ -- [AccessLogGrpcService](#accessloggrpcservice) - [CommonAccessLogGrpcService](#commonaccessloggrpcservice) - [CommonGrpcService](#commongrpcservice) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `key` _string_ | Header name. | | | +| `value` _string_ | Header value. | | | #### HealthCheck @@ -2065,6 +2018,7 @@ _Appears in:_ | `initialConnectionWindowSize` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#quantity-resource-api)_ | InitialConnectionWindowSize is similar to InitialStreamWindowSize, but for the connection level.
Same range and default value as InitialStreamWindowSize.
Values can be specified with units like "64Ki". | | | | `maxConcurrentStreams` _integer_ | The maximum number of concurrent streams that the connection can have.
Envoy defaults to 1024. | | Maximum: 2.147483647e+09
Minimum: 1
| | `overrideStreamErrorOnInvalidHttpMessage` _boolean_ | Allows invalid HTTP messaging and headers. When disabled (default), then
the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame.
When enabled, only the offending stream is terminated. | | | +| `connectionKeepalive` _[ConnectionKeepalive](#connectionkeepalive)_ | ConnectionKeepalive enables HTTP/2 keepalive PINGs on upstream connections,
actively detecting half-dead connections: if a PING is not acknowledged
within the timeout, the connection is closed.
See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-msg-config-core-v3-keepalivesettings) for more details. | | | #### HttpsUri @@ -2404,6 +2358,7 @@ _Appears in:_ | `tcpKeepalive` _[TCPKeepalive](#tcpkeepalive)_ | TCPKeepalive configures OS-level TCP keepalive checks for downstream client connections accepted by this listener. | | | | `perConnectionBufferLimitBytes` _integer_ | PerConnectionBufferLimitBytes sets the per-connection buffer limit for all listeners on the gateway.
This controls the maximum size of read and write buffers for new connections.
When using Envoy as an edge proxy, configuring the listener buffer limit is important to guard against
potential attacks or misconfigured downstreams that could hog the proxy's resources.
If unspecified, an implementation-defined default is applied (1MiB).
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#envoy-v3-api-field-config-listener-v3-listener-per-connection-buffer-limit-bytes | | Minimum: 0
| | `httpSettings` _[HTTPSettings](#httpsettings)_ | HTTPSettings is intended to be used for configuring the Envoy `HttpConnectionManager` and any other config or policy
that should map 1-to-1 with a given HTTP listener, such as the Envoy health check HTTP filter. | | | +| `transportSocketConnectTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | TransportSocketConnectTimeout is the timeout for the transport socket to complete after a new connection is accepted.
If the timeout fires, the connection is closed. Setting this protects Envoy from clients that open connections and
then never complete the TLS handshake. Applied to every filter chain on the listener.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener_components.proto#envoy-v3-api-field-config-listener-v3-filterchain-transport-socket-connect-timeout | | | #### ListenerDefaultConfig @@ -2424,6 +2379,7 @@ _Appears in:_ | `tcpKeepalive` _[TCPKeepalive](#tcpkeepalive)_ | TCPKeepalive configures OS-level TCP keepalive checks for downstream client connections accepted by this listener. | | | | `perConnectionBufferLimitBytes` _integer_ | PerConnectionBufferLimitBytes sets the per-connection buffer limit for all listeners on the gateway.
This controls the maximum size of read and write buffers for new connections.
When using Envoy as an edge proxy, configuring the listener buffer limit is important to guard against
potential attacks or misconfigured downstreams that could hog the proxy's resources.
If unspecified, an implementation-defined default is applied (1MiB).
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#envoy-v3-api-field-config-listener-v3-listener-per-connection-buffer-limit-bytes | | Minimum: 0
| | `httpSettings` _[HTTPSettings](#httpsettings)_ | HTTPSettings is intended to be used for configuring the Envoy `HttpConnectionManager` and any other config or policy
that should map 1-to-1 with a given HTTP listener, such as the Envoy health check HTTP filter. | | | +| `transportSocketConnectTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | TransportSocketConnectTimeout is the timeout for the transport socket to complete after a new connection is accepted.
If the timeout fires, the connection is closed. Setting this protects Envoy from clients that open connections and
then never complete the TLS handshake. Applied to every filter chain on the listener.
See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener_components.proto#envoy-v3-api-field-config-listener-v3-filterchain-transport-socket-connect-timeout | | | #### ListenerHTTP2ProtocolOptions @@ -2437,7 +2393,6 @@ over Kubernetes' schema cost budget. _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -2445,6 +2400,7 @@ _Appears in:_ | `initialStreamWindowSize` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#quantity-resource-api)_ | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#quantity-resource-api)_ | InitialConnectionWindowSize is similar to InitialStreamWindowSize, but for the connection level.
Same range and default value as InitialStreamWindowSize.
Values can be specified with units like "64Ki". | | | | `maxConcurrentStreams` _integer_ | The maximum number of concurrent streams that the connection can have.
Envoy defaults to 1024. | | Maximum: 2.147483647e+09
Minimum: 1
| +| `allowConnect` _boolean_ | AllowConnect allows proxying of WebSocket and other upgrades over HTTP/2 by
enabling Envoy to handle Extended CONNECT requests (RFC 8441) on the downstream
connection. This is required for WebSocket-over-HTTP/2 when the listener advertises
h2 in its ALPN; otherwise user agents that use Extended CONNECT (e.g. Firefox) fail
to establish WebSocket connections.
Defaults to false. | | | #### ListenerPolicy @@ -2526,7 +2482,7 @@ _Appears in:_ | `maglev` _[LoadBalancerMaglevConfig](#loadbalancermaglevconfig)_ | Maglev configures the maglev load balancer type. | | | | `random` _[LoadBalancerRandomConfig](#loadbalancerrandomconfig)_ | Random configures the random load balancer type. | | | | `localityType` _[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]
| -| `zoneAware` _[ZoneAwareLoadBalancer](#zoneawareloadbalancer)_ | ZoneAware configures zone-aware routing behavior for the load balancer.
When enabled, traffic is preferentially routed to endpoints in the same
availability zone as the Envoy proxy.
This is mutually exclusive with localityType. | | | +| `zoneAware` _[ZoneAwareLoadBalancer](#zoneawareloadbalancer)_ | ZoneAware configures zone-aware routing behavior for the load balancer.
When enabled, traffic is preferentially routed to endpoints in the same
availability zone as the Envoy proxy.
This is mutually exclusive with localityType.

Note: This feature is experimental and subject to breaking changes in future releases. | | | | `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. | | | @@ -2658,7 +2614,6 @@ LocalReplyConfig represents the listener-wide options for local replies returned _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -2669,7 +2624,7 @@ _Appears in:_ #### LocalReplyMapper - +_Underlying type:_ _struct_ LocalReplyMapper may customize the local reply based on stream, request, and response properties such as status code. @@ -2678,13 +2633,6 @@ LocalReplyMapper may customize the local reply based on stream, request, and res _Appears in:_ - [LocalReplyConfig](#localreplyconfig) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `filter` _[AccessLogFilter](#accesslogfilter)_ | A filter that determines if this mapper should apply. | | MaxProperties: 1
MinProperties: 1
| -| `statusCode` _[uint32](#uint32)_ | New response status code for the reply if specified. | | Maximum: 599
Minimum: 100
| -| `body` _string_ | New body text for the reply if specified.
Available as `%LOCAL_REPLY_BODY%` in substitution strings. | | | -| `bodyFormatOverride` _[BodyFormat](#bodyformat)_ | Alternative body format for the reply if specified. Takes precedence over default body format. | | | -| `headers` _[HTTPHeaderFilter](#httpheaderfilter)_ | Headers to add or set for the reply if specified. | | | #### LocalityType @@ -2794,6 +2742,20 @@ _Appears in:_ | `forwarding` _[MetadataNamespaces](#metadatanamespaces)_ | Forwarding defines the typed or untyped dynamic metadata namespaces to forward to the external processing server. | | | +#### MetadataPathSegment + + + +Specifies a segment in a path for retrieving values from Metadata. + + + +_Appears in:_ +- [MetadataKey](#metadatakey) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `key` _string_ | The key used to retrieve the value in the struct | | | #### NamedJWTProvider @@ -3009,7 +2971,7 @@ _Appears in:_ #### OpenTelemetryAccessLogService - +_Underlying type:_ _struct_ 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 @@ -3019,33 +2981,10 @@ Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_logger _Appears in:_ - [AccessLog](#accesslog) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `grpcService` _[CommonAccessLogGrpcService](#commonaccessloggrpcservice)_ | Send access logs to gRPC service | | | -| `body` _string_ | OpenTelemetry LogResource fields, following Envoy access logging formatting. | | | -| `disableBuiltinLabels` _boolean_ | If specified, Envoy will not generate built-in resource labels like log_name, zone_name, cluster_name, node_name. | | | - - -#### OpenTelemetryTracingConfig - - -OpenTelemetryTracingConfig represents the top-level Envoy's OpenTelemetry tracer. -See here for more information: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/opentelemetry.proto.html -_Appears in:_ -- [TracingProvider](#tracingprovider) - -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `grpcService` _[CommonGrpcService](#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: `.` | | | -| `resourceDetectors` _[ResourceDetector](#resourcedetector) array_ | An ordered list of resource detectors. Currently supported values are `EnvironmentResourceDetector` | | MaxProperties: 1
MinProperties: 1
| -| `sampler` _[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 @@ -3060,6 +2999,10 @@ _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
| +| `enforcingConsecutive5xx` _integer_ | The percentage chance that a host is ejected when an outlier status is
detected through consecutive 5xx responses. This setting can be used to
disable ejection or to ramp it up slowly. Defaults to 100. | | Maximum: 100
Minimum: 0
| +| `splitExternalLocalOriginErrors` _boolean_ | Determines whether to distinguish locally originated failures from
externally generated errors. When true, consecutiveLocalOriginFailure and
enforcingConsecutiveLocalOriginFailure are used for locally originated
failures. Defaults to false. | | | +| `consecutiveLocalOriginFailure` _integer_ | The number of consecutive locally originated failures before an ejection
occurs. Defaults to 5. This setting takes effect only when
splitExternalLocalOriginErrors is true. If this is zero, consecutive local
origin failure ejection is disabled. | | Minimum: 0
| +| `enforcingConsecutiveLocalOriginFailure` _integer_ | The percentage chance that a host is ejected when an outlier status is
detected through consecutive locally originated failures. This setting can
be used to disable ejection or to ramp it up slowly. Defaults to 100 and
takes effect only when splitExternalLocalOriginErrors is true. | | Maximum: 100
Minimum: 0
| | `interval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | 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
| @@ -3129,6 +3072,25 @@ _Appears in:_ | `nodePort` _integer_ | The NodePort to be used for the service. If not specified, a random port
will be assigned by the Kubernetes API server. | | Maximum: 65535
Minimum: 1
| +#### PriorityGroup + + + +PriorityGroup defines one failover priority level of a priority groups backend. + + +Note: This struct is part of an experimental API and subject to breaking changes in future releases. + + + +_Appears in:_ +- [BackendSpec](#backendspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `backendRefs` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | BackendRefs references the Backends that make up this priority group.
Referenced Backends must be in the same namespace and must not be
priority groups backends themselves. | | MaxItems: 16
MinItems: 1
| + + #### ProcessingMode @@ -3340,7 +3302,7 @@ _Appears in:_ -RequestDecompression enables request gzip decompression. +RequestDecompression enables request decompression. @@ -3349,6 +3311,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | +| `libraries` _[CompressionLibrary](#compressionlibrary) array_ | Libraries lists the codecs to decompress on request bodies. Envoy selects the decompressor
by the request's `Content-Encoding` header, so the list order is not significant. Request
bodies encoded with a codec not in this list are passed through to the backend unchanged.
Defaults to [Gzip]. | [Gzip] | Enum: [Gzip Brotli Zstd]
MaxItems: 3
MinItems: 1
| | `disable` _[PolicyDisable](#policydisable)_ | Disables decompression. | | | @@ -3383,12 +3346,13 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | +| `libraries` _[CompressionLibrary](#compressionlibrary) array_ | Libraries lists the compression codecs to offer for responses.
Envoy negotiates the codec based on the downstream request's `Accept-Encoding` header,
picking the highest-quality codec the client accepts. On equal quality the client's
ordering decides. If the client accepts none of the offered codecs, the response is
sent uncompressed.
Defaults to [Gzip]. | [Gzip] | Enum: [Gzip Brotli Zstd]
MaxItems: 3
MinItems: 1
| | `disable` _[PolicyDisable](#policydisable)_ | Disables compression. | | | #### ResponseFlagFilter -_Underlying type:_ _struct_ + ResponseFlagFilter filters based on response flags. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-responseflagfilter @@ -3398,6 +3362,9 @@ Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v _Appears in:_ - [FilterType](#filtertype) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `flags` _string array_ | | | MinItems: 1
| #### Retry @@ -3453,7 +3420,7 @@ _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 @@ -3461,10 +3428,13 @@ Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.prot _Appears in:_ -- [AccessLogGrpcService](#accessloggrpcservice) - [CommonAccessLogGrpcService](#commonaccessloggrpcservice) - [CommonGrpcService](#commongrpcservice) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `retryBackOff` _[BackoffStrategy](#backoffstrategy)_ | Specifies parameters that control retry backoff strategy.
the default base interval is 1000 milliseconds and the default maximum interval is 10 times the base interval. | | | +| `numRetries` _integer_ | Specifies the allowed number of retries. Defaults to 1. | | Minimum: 1
| #### RouteTracing @@ -3494,7 +3464,7 @@ _Appears in:_ #### RuntimeFilter -_Underlying type:_ _struct_ + RuntimeFilter filters for random sampling of access logs. A request will be logged if the runtime key is set and the request's random value is less than the percent_sampled value. @@ -3505,6 +3475,11 @@ Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v _Appears in:_ - [FilterType](#filtertype) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `runtimeKey` _string_ | The runtime key to look up in the runtime implementation. This key determines whether
the access log is enabled. When the runtime key value is set, the filter checks this key
at runtime to decide whether to log each request. | | MinLength: 1
| +| `percentSampled` _[FractionalPercent](#fractionalpercent)_ | By default, the runtime filter will log on every request when the runtime key is set.
If this field is set, it additionally applies a fractional percent check so that only a
fraction of requests are logged. | | | +| `useIndependentRandomness` _boolean_ | If set to true, the filter uses Envoy's independent randomness source.
When false (the default), the filter uses the runtime key lookup. | | | #### Sampler @@ -3600,7 +3575,6 @@ ServerHeaderTransformation determines how the server header is transformed. _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | @@ -3652,7 +3626,7 @@ _Appears in:_ #### SetCurrentClientCertDetails - +_Underlying type:_ _struct_ SetCurrentClientCertDetails selects fields from the downstream client certificate to include in the XFCC header when Envoy sets or appends it. Fields default to false when unset. @@ -3663,13 +3637,6 @@ See: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/netwo _Appears in:_ - [ForwardClientCertDetails](#forwardclientcertdetails) -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `subject` _boolean_ | Subject forwards the certificate Subject in the XFCC header. | | | -| `cert` _boolean_ | Cert forwards the entire client certificate in URL-encoded PEM format in the XFCC header. | | | -| `chain` _boolean_ | Chain forwards the entire client certificate chain (including the leaf certificate) in
URL-encoded PEM format in the XFCC header. | | | -| `dns` _boolean_ | DNS forwards DNS-type Subject Alternative Names from the client certificate in the XFCC header. | | | -| `uri` _boolean_ | URI forwards the URI-type Subject Alternative Name from the client certificate in the XFCC header. | | | #### SlowStart @@ -3773,6 +3740,10 @@ Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v _Appears in:_ - [FilterType](#filtertype) +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `op` _[Op](#op)_ | | | Enum: [EQ GE LE]
| +| `value` _integer_ | Value to compare against. | | Format: uint32
Maximum: 4.294967295e+09
Minimum: 0
| #### StripHostPortMode @@ -3785,7 +3756,6 @@ Host/authority header. _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | @@ -3874,6 +3844,7 @@ _Appears in:_ | `maxVersion` _[TLSVersion](#tlsversion)_ | Maximum TLS version. | | Enum: [AUTO 1.0 1.1 1.2 1.3]
| | `cipherSuites` _string array_ | | | | | `ecdhCurves` _string array_ | | | | +| `signatureAlgorithms` _string array_ | | | | #### TLSVersion @@ -3926,7 +3897,6 @@ Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/netwo _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -4004,8 +3974,8 @@ _Appears in:_ | `headerModifiers` _[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](https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#httpurlrewritefilter)
configured to override the `hostname`, the `hostname` value will be used and `autoHostRewrite` will be ignored. | | | | `buffer` _[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)_ | Timeouts defines the timeouts for requests
It is applicable to HTTPRoutes and ignored for other targeted kinds. | | | -| `retry` _[Retry](#retry)_ | Retry defines the policy for retrying requests.
It is applicable to HTTPRoutes, Gateway listeners and ListenerSets, and ignored for other targeted kinds. | | | +| `timeouts` _[Timeouts](#timeouts)_ | Timeouts defines the timeouts for requests.
It is applicable to HTTPRoutes, GRPCRoutes, and Gateways (including individual
Gateway listeners via sectionName), and ignored for other targeted kinds.
When attached above the route level, the timeouts apply to all routes it
covers; a route-level timeout (from a more specific TrafficPolicy or the
built-in HTTPRoute timeouts) takes precedence. | | | +| `retry` _[Retry](#retry)_ | Retry defines the policy for retrying requests.
It is applicable to HTTPRoutes, GRPCRoutes, Gateways, Gateway listeners, and
ListenerSets, and ignored for other targeted kinds.
When attached above the route level, the retry policy applies to all routes it
covers; a route-level retry policy (from a more specific TrafficPolicy or the
built-in HTTPRoute retry) takes precedence. | | | | `internalRedirect` _[InternalRedirect](#internalredirect)_ | InternalRedirect handles upstream 3xx redirects inside the gateway.
Applies only to routes that forward traffic to a backend. | | | | `rbac` _[Authorization](#authorization)_ | RBAC specifies the role-based access control configuration for the policy.
This defines the rules for authorization based on roles and permissions.
RBAC policies applied at different attachment points in the configuration
hierarchy are not cumulative, and only the most specific policy is enforced. This means an RBAC policy
attached to a route will override any RBAC policies applied to the gateway or listener. | | | | `jwtAuth` _[JWTAuth](#jwtauth)_ | JWT specifies the JWT authentication configuration for the policy.
This defines the JWT providers and their configurations. | | | @@ -4017,6 +3987,7 @@ _Appears in:_ | `tracing` _[RouteTracing](#routetracing)_ | Tracing configures per-route tracing overrides.
These settings override the listener-level tracing configuration
(configured via ListenerPolicy) for matched routes.
The tracing provider (e.g., OpenTelemetry collector endpoint) must be
configured at the listener level via ListenerPolicy. Without a listener-level
tracing provider, route-level settings have no effect.
NOTE: This field is only honored for HTTPRoute and GRPCRoute targets. | | | | `faultInjection` _[FaultInjectionPolicy](#faultinjectionpolicy)_ | FaultInjection configures fault injection for chaos engineering and
resiliency testing. Supports delay injection, abort injection,
and response rate limiting. | | | | `acl` _[ACLPolicy](#aclpolicy)_ | ACL configures IP-based access control for HTTP requests.
Rules are evaluated using longest-prefix matching on the effictive client IP
from envoy base on settings. See the UseRemoteAddress, XffTrustedCIDRs,
XffNumTrustedHops settings under ListenerPolicy -> HttpSettings for details.

When multiple TrafficPolicy objects target the same route, their ACL fields are
deep-merged by default: rules are unioned (higher-priority policy's rules first),
and singleton fields (defaultAction, denyResponse) are taken from the higher-priority
policy. If singleton fields conflict between policies, the merge falls back to
shallow (higher-priority policy wins entirely). Gateway-level and route-level ACL
policies are kept in separate merge groups and are never combined with each other;
a route-level ACL completely replaces the gateway-level ACL for that route. | | | +| `statPrefix` _string_ | StatPrefix sets a custom prefix on the Envoy route so that per-route
statistics are emitted for the targeted routes. When set, Envoy emits stats under
`vhost..route..*`.

The value is composed of stat-safe literal characters (letters, digits,
and `_ % . -`) and/or `\{\{ ... \}\}` template tokens that are substituted at
translation time with metadata from the route the policy is applied to.
The supported template variables are:
- `\{\{route_name\}\}`: the name of the route resource (e.g. HTTPRoute).
- `\{\{route_namespace\}\}`: the namespace of the route resource.
- `\{\{rule_name\}\}`: the name of the matched route rule, or empty if the
rule is unnamed.

For example, `\{\{route_namespace\}\}.\{\{route_name\}\}` renders to
`my-ns.my-route`. Whitespace is permitted only inside the braces of a
template token; unmatched braces, unsupported variable names, and any
other characters are rejected.

Recommended value: `\{\{route_namespace\}\}.\{\{route_name\}\}.\{\{rule_name\}\}`,
which uniquely identifies each route rule.

NOTE: This field is only honored for HTTPRoute and GRPCRoute targets. | | MaxLength: 256
MinLength: 1
Pattern: `^([a-zA-Z0-9_%.-]\|\\{\\{\s*(route_name\|route_namespace\|rule_name)\s*\\}\\})+$`
| #### Transform @@ -4085,7 +4056,6 @@ UpgradeConfig represents configuration for HTTP upgrades. _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -4119,7 +4089,6 @@ Based on: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/request_ _Appears in:_ -- [HTTPListenerPolicySpec](#httplistenerpolicyspec) - [HTTPSettings](#httpsettings) | Field | Description | Default | Validation | @@ -4169,6 +4138,9 @@ _Appears in:_ ZoneAwareForce configures Envoy forceLocalZone behavior. +Note: This struct is part of an experimental API and subject to breaking changes in future releases. + + _Appears in:_ - [ZoneAwarePreferLocal](#zoneawarepreferlocal) @@ -4186,13 +4158,16 @@ ZoneAwareLoadBalancer configures zone-aware routing behavior. Currently, preferLocal must be specified. +Note: This struct is part of an experimental API and subject to breaking changes in future releases. + + _Appears in:_ - [LoadBalancer](#loadbalancer) | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `preferLocal` _[ZoneAwarePreferLocal](#zoneawarepreferlocal)_ | PreferLocal enables Envoy's zone-aware routing which prefers sending traffic
to local zone endpoints while maintaining overall traffic balance across zones.
This requires the Envoy proxy to be aware of its own zone, which can be configured
via the KGATEWAY_NODE_ZONE environment variable on the proxy pod.
See https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/zone_aware | | | +| `preferLocal` _[ZoneAwarePreferLocal](#zoneawarepreferlocal)_ | PreferLocal enables Envoy's zone-aware routing which prefers sending traffic
to local zone endpoints while maintaining overall traffic balance across zones.
On Kubernetes 1.35+, the zone is automatically derived from node label.
The KGATEWAY_NODE_* environment variables on the proxy pod can be set as an explicit override.
See https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/zone_aware | | | #### ZoneAwarePreferLocal @@ -4204,6 +4179,9 @@ Envoy will prefer sending traffic to endpoints in the same zone as the proxy, while still maintaining rough request balance across all upstream hosts. +Note: This struct is part of an experimental API and subject to breaking changes in future releases. + + _Appears in:_ - [ZoneAwareLoadBalancer](#zoneawareloadbalancer) @@ -4312,6 +4290,15 @@ _Underlying type:_ _string_ AuthorizationPolicyAction defines the action to take when the RBACPolicies matches. +#### BackoffStrategy + +Configuration defining a jittered exponential back off strategy. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/backoff.proto#envoy-v3-api-msg-config-core-v3-backoffstrategy + +| Field | Type | Description | +|-------|------|-------------| +| `baseInterval` | metav1.Duration | The base interval to be used for the next back off computation. It should be greater than zero and less than or equal to max_interval. **Required.** | +| `maxInterval` | *metav1.Duration | Specifies the maximum interval between retries. This parameter is optional, but must be greater than or equal to the base_interval if set. The default is 10 times the base_interval. | + #### BodyFormat BodyFormat configures an Envoy response body using formatting. Either JSON or Text must be specified. @@ -4335,14 +4322,45 @@ CELExpression represents a Common Expression Language (CEL) expression. - MinLength=1 - MaxLength=16384 -#### ComparisonFilter +#### CELFilter -ComparisonFilter represents a filter based on a comparison. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-comparisonfilter +CELFilter filters requests based on Common Expression Language (CEL). | Field | Type | Description | |-------|------|-------------| -| `op` | [Op](#op) | **Required.** | -| `value` | uint32 | Value to compare against. **Required.** | +| `match` | string | The CEL expressions to evaluate. AccessLogs are only emitted when the CEL expressions evaluates to true. see: https://www.envoyproxy.io/docs/envoy/v1.33.0/xds/type/v3/cel.proto.html#common-expression-language-cel-proto **Required.** | + +#### 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 + +| Field | Type | Description | +|-------|------|-------------| +| `logName` | string | name of log stream **Required.** | + +#### 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 + +| Field | Type | Description | +|-------|------|-------------| +| `backendRef` | gwv1.BackendRef | The backend gRPC service. Can be any type of supported backend (Kubernetes Service, kgateway Backend, etc..) **Required.** | +| `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` | *int32 | 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. | +| `skipEnvoyHeaders` | *bool | 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` | *metav1.Duration | The timeout for the gRPC request. This is the timeout for a specific request | +| `initialMetadata` | [][HeaderValue](#headervalue) | 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](#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 | + +#### 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 + +| Field | Type | Description | +|-------|------|-------------| +| `kind` | [MetadataKind](#metadatakind) | Specify what kind of metadata to obtain attribute value from **Required.** | +| `metadataKey` | [MetadataKey](#metadatakey) | Metadata key to define the path to retrieve the attribute value. **Required.** | +| `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. | #### DenominatorType @@ -4353,6 +4371,12 @@ DenominatorType defines the fraction percentages support several fixed denominat **Validation:** - enum=HUNDRED,TEN_THOUSAND,MILLION +#### 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 + #### EnvironmentResourceDetectorConfig EnvironmentResourceDetectorConfig specifies the EnvironmentResourceDetector configuration. @@ -4361,6 +4385,26 @@ EnvironmentResourceDetectorConfig specifies the EnvironmentResourceDetector conf |-------|------|-------------| | `enable` | *bool | Enable controls whether the EnvironmentResourceDetector is used. | +#### 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 + +| Field | Type | Description | +|-------|------|-------------| +| `statusCodeFilter` | *[StatusCodeFilter](#statuscodefilter) | | +| `durationFilter` | *[DurationFilter](#durationfilter) | | +| `notHealthCheckFilter` | *bool | 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` | *bool | 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](#headerfilter) | | +| `responseFlagFilter` | *[ResponseFlagFilter](#responseflagfilter) | | +| `grpcStatusFilter` | *[GrpcStatusFilter](#grpcstatusfilter) | | +| `celFilter` | *[CELFilter](#celfilter) | | +| `runtimeFilter` | *[RuntimeFilter](#runtimefilter) | Filters for random sampling of access logs. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-runtimefilter | + #### FractionalPercent FractionalPercent represents a fraction as a numerator and denominator. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/type/v3/percent.proto#envoy-v3-api-msg-type-v3-fractionalpercent @@ -4370,6 +4414,24 @@ FractionalPercent represents a fraction as a numerator and denominator. Based on | `numerator` | int32 | Specifies the numerator. Defaults to 0. **Required.** | | `denominator` | *[DenominatorType](#denominatortype) | Specifies the denominator. If the denominator specified is less than the numerator, the final fractional percentage is capped at 1 (100%). Defaults to HUNDRED. | +#### GrpcStatus + +_Underlying type:_ _string_ + +GrpcStatus represents possible gRPC statuses. + +**Validation:** +- Enum=OK;CANCELED;UNKNOWN;INVALID_ARGUMENT;DEADLINE_EXCEEDED;NOT_FOUND;ALREADY_EXISTS;PERMISSION_DENIED;RESOURCE_EXHAUSTED;FAILED_PRECONDITION;ABORTED;OUT_OF_RANGE;UNIMPLEMENTED;INTERNAL;UNAVAILABLE;DATA_LOSS;UNAUTHENTICATED + +#### GrpcStatusFilter + +GrpcStatusFilter filters gRPC requests based on their response status. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#enum-config-accesslog-v3-grpcstatusfilter-status + +| Field | Type | Description | +|-------|------|-------------| +| `statuses` | [][GrpcStatus](#grpcstatus) | | +| `exclude` | *bool | | + #### HTTPHeader HTTPHeader represents a single header name/value pair. Exactly one of value or secretRef must be set. When using secretRef, name and key interact as follows: - Both present: name is the header name, key is the Secret data key. - name absent, key present: the key is also used as the header name. - name present, key absent: the name is also used as the Secret data key. - Both absent: every entry in the Secret is injected as a header (data key -> header name). @@ -4397,6 +4459,14 @@ HTTPHeaderFilter defines a filter that modifies the headers of an HTTP request o | `add` | [][HTTPHeader](#httpheader) | Add adds the given header(s) (name, value) to the request before the action. It appends to any existing values associated with the header name. Input: GET /foo HTTP/1.1 my-header: foo Config: add: - name: "my-header" value: "bar,baz" Output: GET /foo HTTP/1.1 my-header: foo,bar,baz | | `remove` | []string | Remove the given header(s) from the HTTP request before the action. The value of Remove is a list of HTTP header names. Note that header names are case-insensitive (see [RFC 2616, Section 4.2](https://datatracker.ietf.org/doc/html/rfc2616#section-4.2)). Input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz Config: remove: ["my-header1", "my-header3"] Output: GET /foo HTTP/1.1 my-header2: bar | +#### HeaderFilter + +HeaderFilter filters requests based on headers. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-headerfilter + +| Field | Type | Description | +|-------|------|-------------| +| `header` | gwv1.HTTPHeaderMatch | **Required.** | + #### HeaderModifiers HeaderModifiers can be used to define the policy to modify request and response headers. @@ -4409,6 +4479,15 @@ HeaderModifiers can be used to define the policy to modify request and response | `request` | *[HTTPHeaderFilter](#httpheaderfilter) | Request modifies request headers. | | `response` | *[HTTPHeaderFilter](#httpheaderfilter) | Response modifies response headers. | +#### HeaderValue + +Header name/value pair. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-msg-config-core-v3-headervalue + +| Field | Type | Description | +|-------|------|-------------| +| `key` | string | Header name. **Required.** | +| `value` | *string | Header value. | + #### IPOrCIDR _Underlying type:_ _string_ @@ -4494,6 +4573,24 @@ LocalPolicyTargetSelector selects the object to attach the policy by Group, Kind | `kind` | gwv1.Kind | The API kind of the target resource, such as Gateway or HTTPRoute. **Required.** | | `matchLabels` | map[string]string | Label selector to select the target resource. **Required.** | +#### MetadataKey + +MetadataKey provides a way to retrieve values from Metadata using a key and a path. + +| Field | Type | Description | +|-------|------|-------------| +| `key` | string | The key name of the Metadata from which to retrieve the Struct **Required.** | +| `path` | [][MetadataPathSegment](#metadatapathsegment) | 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 **Required.** | + +#### 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 + #### MetadataPathSegment Specifies a segment in a path for retrieving values from Metadata. @@ -4520,14 +4617,16 @@ ObjectMetadata contains labels and annotations for metadata overlays. | `labels` | map[string]string | Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels | | `annotations` | map[string]string | Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations | -#### Op - -_Underlying type:_ _string_ +#### OpenTelemetryTracingConfig -Op represents comparison operators. +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 -**Validation:** -- Enum=EQ;GE;LE +| Field | Type | Description | +|-------|------|-------------| +| `grpcService` | [CommonGrpcService](#commongrpcservice) | Send traces to the gRPC service **Required.** | +| `serviceName` | *string | The name for the service. This will be populated in the ResourceSpan Resource attributes Defaults to the envoy cluster name. Ie: `.` | +| `resourceDetectors` | [][ResourceDetector](#resourcedetector) | An ordered list of resource detectors. Currently supported values are `EnvironmentResourceDetector` | +| `sampler` | *[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` | #### PolicyAncestorStatus @@ -4557,6 +4656,57 @@ RateLimitDescriptorEntryGeneric defines a generic key-value descriptor entry. | `key` | string | Key is the name of this descriptor entry. **Required.** | | `value` | string | Value is the static value for this descriptor entry. **Required.** | +#### ResourceDetector + +ResourceDetector defines the list of supported ResourceDetectors + +**Validation:** +- MaxProperties=1 +- MinProperties=1 + +| Field | Type | Description | +|-------|------|-------------| +| `environmentResourceDetector` | *[EnvironmentResourceDetectorConfig](#environmentresourcedetectorconfig) | EnvironmentResourceDetector sets OpenTelemetry resource attributes from the OTEL_RESOURCE_ATTRIBUTES environment variable in the Envoy container. Default enabled if not set. If multiple are set, the last will take precedence. | + +#### ResponseFlagFilter + +ResponseFlagFilter filters based on response flags. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-responseflagfilter + +| Field | Type | Description | +|-------|------|-------------| +| `flags` | []string | **Required.** | + +#### RetryPolicy + +Specifies the retry policy of remote data source when fetching fails. Ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-msg-config-core-v3-retrypolicy + +| Field | Type | Description | +|-------|------|-------------| +| `retryBackOff` | *[BackoffStrategy](#backoffstrategy) | Specifies parameters that control retry backoff strategy. the default base interval is 1000 milliseconds and the default maximum interval is 10 times the base interval. | +| `numRetries` | *int32 | Specifies the allowed number of retries. Defaults to 1. | + +#### RuntimeFilter + +RuntimeFilter filters for random sampling of access logs. A request will be logged if the runtime key is set and the request's random value is less than the percent_sampled value. Based on: https://www.envoyproxy.io/docs/envoy/v1.33.0/api-v3/config/accesslog/v3/accesslog.proto#config-accesslog-v3-runtimefilter + +| Field | Type | Description | +|-------|------|-------------| +| `runtimeKey` | string | The runtime key to look up in the runtime implementation. This key determines whether the access log is enabled. When the runtime key value is set, the filter checks this key at runtime to decide whether to log each request. **Required.** | +| `percentSampled` | *[FractionalPercent](#fractionalpercent) | By default, the runtime filter will log on every request when the runtime key is set. If this field is set, it additionally applies a fractional percent check so that only a fraction of requests are logged. | +| `useIndependentRandomness` | *bool | If set to true, the filter uses Envoy's independent randomness source. When false (the default), the filter uses the runtime key lookup. | + +#### Sampler + +Sampler defines the list of supported Samplers + +**Validation:** +- MaxProperties=1 +- MinProperties=1 + +| Field | Type | Description | +|-------|------|-------------| +| `alwaysOnConfig` | *[AlwaysOnConfig](#alwaysonconfig) | | + #### SecretRefWithKey SecretRefWithKey identifies a Kubernetes Secret and optionally a specific key within it. @@ -4567,6 +4717,12 @@ SecretRefWithKey identifies a Kubernetes Secret and optionally a specific key wi | `key` | *string | Key is the key within the Secret's data map to use as the header value. When omitted and the parent HTTPHeader.name is set, that name is used as the key. When both key and name are omitted, all entries in the Secret are injected as headers. | | `namespace` | *gwv1.Namespace | Namespace is the namespace of the Secret. If omitted, defaults to the namespace of the referencing policy. Cross-namespace references require a ReferenceGrant in the target namespace permitting access from the policy's namespace. | +#### 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 + #### Timeouts | Field | Type | Description |