Notice:
This is the "latest" release of Envoy Gateway, which contains the most recent commits from the main branch.
This release might not be stable.
Please refer to the /docs documentation for the most current information.

Gateway API Extensions

Envoy Gateway provides these extensions to support additional features not available in the Gateway API today

202 minute read

Packages

gateway.envoyproxy.io/v1alpha1

gateway.envoyproxy.io/v1alpha1

Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io API group.

Resource Types

ALPNProtocol

Underlying type: string

ALPNProtocol specifies the protocol to be negotiated using ALPN

Appears in:

Value	Description
`http/1.0`	HTTPProtocolVersion1_0 specifies that HTTP/1.0 should be negotiable with ALPN
`http/1.1`	HTTPProtocolVersion1_1 specifies that HTTP/1.1 should be negotiable with ALPN
`h2`	HTTPProtocolVersion2 specifies that HTTP/2 should be negotiable with ALPN

ALSEnvoyProxyAccessLog

ALSEnvoyProxyAccessLog defines the gRPC Access Log Service (ALS) sink. The service must implement the Envoy gRPC Access Log Service streaming API: https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/accesslog/v3/als.proto Access log format information is passed in the form of gRPC metadata when the stream is established.

Appears in:

ProxyAccessLogSink

Field	Type	Required	Description
`backendRef`	BackendObjectReference	false	BackendRef references a Kubernetes object that represents the backend server to which the authorization request will be sent. Deprecated: Use BackendRefs instead.
`backendRefs`	BackendRef array	false	BackendRefs references a Kubernetes object that represents the backend server to which the authorization request will be sent.
`backendSettings`	ClusterSettings	false	BackendSettings holds configuration for managing the connection to the backend.
`logName`	string	false	LogName defines the friendly name of the access log to be returned in StreamAccessLogsMessage.Identifier. This allows the access log server to differentiate between different access logs coming from the same Envoy.
`type`	ALSEnvoyProxyAccessLogType	true	Type defines the type of accesslog. Supported types are “HTTP” and “TCP”.
`http`	ALSEnvoyProxyHTTPAccessLogConfig	false	HTTP defines additional configuration specific to HTTP access logs.

ALSEnvoyProxyAccessLogType

Underlying type: string

Appears in:

ALSEnvoyProxyAccessLog

Value	Description
`HTTP`	ALSEnvoyProxyAccessLogTypeHTTP defines the HTTP access log type and will populate StreamAccessLogsMessage.http_logs.
`TCP`	ALSEnvoyProxyAccessLogTypeTCP defines the TCP access log type and will populate StreamAccessLogsMessage.tcp_logs.

ALSEnvoyProxyHTTPAccessLogConfig

Appears in:

ALSEnvoyProxyAccessLog

Field	Type	Required	Description
`requestHeaders`	string array	false	RequestHeaders defines request headers to include in log entries sent to the access log service.
`responseHeaders`	string array	false	ResponseHeaders defines response headers to include in log entries sent to the access log service.
`responseTrailers`	string array	false	ResponseTrailers defines response trailers to include in log entries sent to the access log service.

APIKeyAuth

APIKeyAuth defines the configuration for the API Key Authentication.

Appears in:

SecurityPolicySpec

Field	Type	Required	Description
`credentialRefs`	SecretObjectReference array	true	CredentialRefs is the Kubernetes secret which contains the API keys. This is an Opaque secret. Each API key is stored in the key representing the client id. If the secrets have a key for a duplicated client, the first one will be used.
`extractFrom`	ExtractFrom array	true	ExtractFrom is where to fetch the key from the coming request. The value from the first source that has a key will be used.
`forwardClientIDHeader`	string	false	ForwardClientIDHeader is the name of the header to forward the client identity to the backend service. The header will be added to the request with the client id as the value.
`sanitize`	boolean	false	Sanitize indicates whether to remove the API key from the request before forwarding it to the backend service.

ActiveHealthCheck

ActiveHealthCheck defines the active health check configuration. EG supports various types of active health checking including HTTP, TCP.

Appears in:

HealthCheck

Field	Type	Required	Default	Description
`timeout`	Duration	false	1s	Timeout defines the time to wait for a health check response.
`interval`	Duration	false	3s	Interval defines the time between active health checks.
`initialJitter`	Duration	false		InitialJitter defines the maximum time Envoy will wait before the first health check. Envoy will randomly select a value between 0 and the initial jitter value.
`unhealthyThreshold`	integer	false	3	UnhealthyThreshold defines the number of unhealthy health checks required before a backend host is marked unhealthy. Without RetriableStatuses configured, any health check failure results in the host being immediately considered unhealthy. When RetriableStatuses is set, health checks returning those statuses are retried up to this threshold before the host is marked unhealthy.
`healthyThreshold`	integer	false	1	HealthyThreshold defines the number of healthy health checks required before a backend host is marked healthy.
`type`	ActiveHealthCheckerType	true		Type defines the type of health checker.
`http`	HTTPActiveHealthChecker	false		HTTP defines the configuration of http health checker. It’s required while the health checker type is HTTP.
`tcp`	TCPActiveHealthChecker	false		TCP defines the configuration of tcp health checker. It’s required while the health checker type is TCP.
`grpc`	GRPCActiveHealthChecker	false		GRPC defines the configuration of the GRPC health checker. It’s optional, and can only be used if the specified type is GRPC.
`overrides`	HealthCheckOverrides	false		Overrides defines the configuration of the overriding health check settings for all endpoints in the backend cluster. This allows customization of port and other settings that may differ from the main service configuration.
`healthCheckLog`	ProxyHealthCheckLog	false		HealthCheckLog defines health check event logging configuration for this cluster. When set, HC probe outcomes are logged to the configured sinks. Takes precedence over the gateway-level EnvoyProxy.spec.telemetry.healthCheckLog.

ActiveHealthCheckPayload

ActiveHealthCheckPayload defines the encoding of the payload bytes in the payload.

Appears in:

Field	Type	Required	Description
`type`	ActiveHealthCheckPayloadType	true	Type defines the type of the payload.
`text`	string	false	Text payload in plain text.
`binary`	integer array	false	Binary payload base64 encoded.

ActiveHealthCheckPayloadType

Underlying type: string

ActiveHealthCheckPayloadType is the type of the payload.

Appears in:

ActiveHealthCheckPayload

Value	Description
`Text`	ActiveHealthCheckPayloadTypeText defines the Text type payload.
`Binary`	ActiveHealthCheckPayloadTypeBinary defines the Binary type payload.

ActiveHealthCheckerType

Underlying type: string

ActiveHealthCheckerType is the type of health checker.

Appears in:

ActiveHealthCheck

Value	Description
`HTTP`	ActiveHealthCheckerTypeHTTP defines the HTTP type of health checking.
`TCP`	ActiveHealthCheckerTypeTCP defines the TCP type of health checking.
`GRPC`	ActiveHealthCheckerTypeGRPC defines the GRPC type of health checking.

AdmissionControl

AdmissionControl configures health-based load shedding for upstream backends.

Envoy tracks recent upstream responses over a sliding sampling window. When the observed success rate drops below the configured threshold, Envoy probabilistically rejects new requests before forwarding them upstream. This can reduce pressure on degraded backends and give them time to recover.

All fields are optional. When omitted, Envoy’s admission control defaults are used.

Appears in:

BackendTrafficPolicySpec

Field	Type	Required	Description
`samplingWindow`	Duration	false	SamplingWindow defines the time window over which request success rates are calculated. Must be at least 1s; Envoy truncates the window to whole seconds and uses it as the denominator in RPS calculations, so sub-second values would produce a zero denominator. Defaults to 30s if not specified.
`minSuccessRate`	integer	false	MinSuccessRate is the lowest request success rate, as a percentage in the range [1, 100], at which the filter will not reject requests. Defaults to 95 if not specified. Envoy rejects values below 1%, so values lower than 1 are not allowed.
`rejectionAggression`	integer	false	RejectionAggression controls how steeply the rejection probability rises as the observed success rate falls below MinSuccessRate. A value of 1 produces a linear curve; higher values reject more aggressively for a given drop in success rate. Must be greater than 0; values below 1 are clamped to 1. Defaults to 1.
`minRequestRate`	integer	false	MinRequestRate defines the minimum requests per second below which requests will pass through the filter without rejection. Defaults to 0 if not specified.
`maxRejectionPercent`	integer	false	MaxRejectionPercent represents the upper limit of the rejection probability, expressed as a percentage in the range [0, 100]. Defaults to 80 if not specified.
`successCriteria`	AdmissionControlSuccessCriteria	false	SuccessCriteria defines what constitutes a successful request for both HTTP and gRPC.

AdmissionControlSuccessCriteria

AdmissionControlSuccessCriteria defines the criteria for determining successful requests.

Appears in:

AdmissionControl

Field	Type	Required	Default	Description
`http`	HTTPSuccessCriteria	false		HTTP defines success criteria for HTTP requests.
`grpc`	GRPCSuccessCriteria	false		GRPC defines success criteria for gRPC requests.

AppProtocolType

Underlying type: string

AppProtocolType defines various backend applications protocols supported by Envoy Gateway

Appears in:

BackendSpec

Value	Description
`gateway.envoyproxy.io/h2c`	AppProtocolTypeH2C defines the HTTP/2 application protocol.
`gateway.envoyproxy.io/ws`	AppProtocolTypeWS defines the WebSocket over HTTP protocol.
`gateway.envoyproxy.io/wss`	AppProtocolTypeWSS defines the WebSocket over HTTPS protocol.

Authorization

Authorization defines the authorization configuration.

Note: if neither Rules nor DefaultAction is specified, the default action is to deny all requests.

Appears in:

SecurityPolicySpec

Field	Type	Required	Default	Description
`rules`	AuthorizationRule array	false		Rules defines a list of authorization rules. These rules are evaluated in order, the first matching rule will be applied, and the rest will be skipped. For example, if there are two rules: the first rule allows the request and the second rule denies it, when a request matches both rules, it will be allowed.
`defaultAction`	AuthorizationAction	false		DefaultAction defines the default action to be taken if no rules match. If not specified, the default action is Deny.

AuthorizationAction

Underlying type: string

AuthorizationAction defines the action to be taken if a rule matches.

Appears in:

Value	Description
`Allow`	AuthorizationActionAllow is the action to allow the request.
`Deny`	AuthorizationActionDeny is the action to deny the request.

AuthorizationHeaderMatch

AuthorizationHeaderMatch specifies how to match against the value of an HTTP header within a authorization rule.

Appears in:

Principal

Field	Type	Required	Default	Description
`name`	string	true		Name of the HTTP header. The header name is case-insensitive unless PreserveHeaderCase is set to true. For example, “Foo” and “foo” are considered the same header.
`values`	string array	true		Values are the values that the header must match. If multiple values are specified, the rule will match if any of the values match.

AuthorizationRule

AuthorizationRule defines a single authorization rule.

Appears in:

Authorization

Field	Type	Required	Description
`name`	string	false	Name is a user-friendly name for the rule. If not specified, Envoy Gateway will generate a unique name for the rule.
`action`	AuthorizationAction	true	Action defines the action to be taken if the rule matches.
`operation`	Operation	false	Operation specifies the operation of a request, such as HTTP methods. If not specified, all operations are matched on.
`principal`	Principal	false	Principal specifies the client identity of a request. If there are multiple principal types, all principals must match for the rule to match. For example, if there are two principals: one for client IP and one for JWT claim, the rule will match only if both the client IP and the JWT claim match.
`cel`	CELExpression	false	CEL specifies a Common Expression Language expression to evaluate for the request. If specified, the expression must evaluate to true for the rule to match. The expression can use Envoy attributes exposed to the CEL runtime. Request attributes, such as request.path, request.url_path, request.host, request.scheme, request.method, request.headers, and request.query, are generally available during authorization. Connection attributes, such as source.address, source.port, destination.address, destination.port, connection.mtls, and connection.requested_server_name, may also be used. Dynamic metadata and filter state produced by earlier filters may also be available through attributes such as metadata and filter_state. Response attributes are only available after the request completes and should not be used for authorization decisions. For more details, see: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/advanced/attributes The rule matches only when the expression evaluates to a boolean true. Non-boolean results, false, null, and CEL evaluation errors are treated as no match. Examples: `request.headers['x-tenant'] == 'team-a'` `request.method == 'POST' && request.path.startsWith('/admin')`

BackOffPolicy

Appears in:

PerRetryPolicy

Field	Type	Required	Default	Description
`baseInterval`	Duration	false		BaseInterval is the base interval between retries.
`maxInterval`	Duration	false		MaxInterval is 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

Backend

Backend allows the user to configure the endpoints of a backend and the behavior of the connection from Envoy Proxy to the backend.

Field	Type	Required	Default	Description
`apiVersion`	string		`gateway.envoyproxy.io/v1alpha1`
`kind`	string		`Backend`
`metadata`	ObjectMeta	true		Refer to Kubernetes API documentation for fields of `metadata`.
`spec`	BackendSpec	true		Spec defines the desired state of Backend.
`status`	BackendStatus	true		Status defines the current status of Backend.

BackendCluster

BackendCluster contains all the configuration required for configuring access to a backend. This can include multiple endpoints, and settings that apply for managing the connection to all these endpoints.

Appears in:

Field	Type	Required	Description
`backendRef`	BackendObjectReference	false	BackendRef references a Kubernetes object that represents the backend server to which the authorization request will be sent. Deprecated: Use BackendRefs instead.
`backendRefs`	BackendRef array	false	BackendRefs references a Kubernetes object that represents the backend server to which the authorization request will be sent.
`backendSettings`	ClusterSettings	false	BackendSettings holds configuration for managing the connection to the backend.

BackendConnection

BackendConnection allows users to configure connection-level settings of backend

Appears in:

Field	Type	Required	Default	Description
`bufferLimit`	Quantity	false		BufferLimit Soft limit on size of the cluster’s connections read and write buffers. BufferLimit applies to connection streaming (maybe non-streaming) channel between processes, it’s in user space. If unspecified, an implementation defined default is applied (32768 bytes). For example, 20Mi, 1Gi, 256Ki etc. Note: that when the suffix is not provided, the value is interpreted as bytes.
`preconnect`	PreconnectPolicy	false		Preconnect configures proactive upstream connections to reduce latency by establishing connections before they’re needed and avoiding connection establishment overhead. If unset, Envoy will fetch connections as needed to serve in-flight requests.

BackendEndpoint

BackendEndpoint describes a backend endpoint, which can be either a fully-qualified domain name, IP address or unix domain socket corresponding to Envoy’s Address: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-address

Appears in:

Field	Type	Required	Description
`hostname`	string	false	Hostname defines an optional hostname for the backend endpoint.
`fqdn`	FQDNEndpoint	false	FQDN defines a FQDN endpoint
`ip`	IPEndpoint	false	IP defines an IP endpoint. Supports both IPv4 and IPv6 addresses.
`unix`	UnixSocket	false	Unix defines the unix domain socket endpoint
`zone`	string	false	Zone defines the service zone of the backend endpoint.

BackendMetrics

Appears in:

BackendTelemetry

Field	Type	Required	Default	Description
`routeStatName`	string	false		RouteStatName defines the value of the Route stat_prefix, determining how the route stats are named. For more details, see envoy docs: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-route The supported operators for this pattern are: %ROUTE_NAME%: name of Gateway API xRoute resource %ROUTE_NAMESPACE%: namespace of Gateway API xRoute resource %ROUTE_KIND%: kind of Gateway API xRoute resource Example: %ROUTE_KIND%/%ROUTE_NAMESPACE%/%ROUTE_NAME% => httproute/my-ns/my-route Disabled by default.

BackendRef

BackendRef defines how an ObjectReference that is specific to BackendRef.

Appears in:

Field	Type	Required	Default	Description
`group`	Group	false		Group is the group of the referent. For example, “gateway.networking.k8s.io”. When unspecified or empty string, core API group is inferred.
`kind`	Kind	false	Service	Kind is the Kubernetes resource kind of the referent. For example “Service”. Defaults to “Service” when not specified. ExternalName services can refer to CNAME DNS records that may live outside of the cluster and as such are difficult to reason about in terms of conformance. They also may not be safe to forward to (see CVE-2021-25740 for more information). Implementations SHOULD NOT support ExternalName Services. Support: Core (Services with a type other than ExternalName) Support: Implementation-specific (Services with type ExternalName)
`name`	ObjectName	true		Name is the name of the referent.
`namespace`	Namespace	false		Namespace is the namespace of the backend. When unspecified, the local namespace is inferred. Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace’s owner to accept the reference. See the ReferenceGrant documentation for details. Support: Core
`port`	PortNumber	false		Port specifies the destination port number to use for this resource. Port is required when the referent is a Kubernetes Service. In this case, the port number is the service port number, not the target port. For other resources, destination port might be derived from the referent resource or this field.
`weight`	integer	false	1	Weight specifies the proportion of requests forwarded to the referenced backend. This is computed as weight/(sum of all weights in this BackendRefs list). For non-zero values, there may be some epsilon from the exact proportion defined here depending on the precision an implementation supports. Weight is not a percentage and the sum of weights does not need to equal 100. If only one backend is specified and it has a weight greater than 0, 100% of the traffic is forwarded to that backend. If weight is set to 0, no traffic should be forwarded for this entry. If unspecified, weight defaults to 1. Support for this field varies based on the context where used.
`fallback`	boolean	false		Fallback indicates whether the backend is designated as a fallback. Multiple fallback backends can be configured. It is highly recommended to configure active or passive health checks to ensure that failover can be detected when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again. The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when the health of the active backends falls below 72%.

BackendSpec

BackendSpec describes the desired state of BackendSpec.

Appears in:

Backend

Field	Type	Required	Default	Description
`type`	BackendType	false	Endpoints	Type defines the type of the backend. Defaults to “Endpoints”
`endpoints`	BackendEndpoint array	true		Endpoints defines the endpoints to be used when connecting to the backend.
`appProtocols`	AppProtocolType array	false		AppProtocols defines the application protocols to be supported when connecting to the backend.
`fallback`	boolean	false		Fallback indicates whether the backend is designated as a fallback. It is highly recommended to configure active or passive health checks to ensure that failover can be detected when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again. The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when the health of the active backends falls below 72%.
`tls`	BackendTLSSettings	false		TLS defines the TLS settings for the backend. If TLS is specified here and a BackendTLSPolicy is also configured for the backend, the final TLS settings will be a merge of both configurations. In case of overlapping fields, the values defined in the BackendTLSPolicy will take precedence.

BackendStatus

BackendStatus defines the state of Backend

Appears in:

Backend

Field	Type	Required	Default	Description
`conditions`	Condition array	false		Conditions describe the current conditions of the Backend.

BackendTLSConfig

BackendTLSConfig describes the BackendTLS configuration for Envoy Proxy.

Appears in:

Field	Type	Required	Description
`clientCertificateRef`	SecretObjectReference	false	ClientCertificateRef defines the reference to a Kubernetes Secret that contains the client certificate and private key for Envoy to use when connecting to backend services and external services, such as ExtAuth, ALS, OpenTelemetry, etc. This secret should be located within the same namespace as the Envoy proxy resource that references it.
`minVersion`	TLSVersion	false	Min specifies the minimal TLS protocol version to allow. The default is TLS 1.2 if this is not specified.
`maxVersion`	TLSVersion	false	Max specifies the maximal TLS protocol version to allow The default is TLS 1.3 if this is not specified.
`ciphers`	string array	false	Ciphers specifies the set of cipher suites supported when negotiating TLS 1.0 - 1.2. This setting has no effect for TLS 1.3. For Envoy TLS cipher suite configuration semantics and default cipher lists, see the Envoy documentation: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlsparameters Supported cipher suite names: - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - ECDHE-ECDSA-AES128-SHA - ECDHE-RSA-AES128-SHA - AES128-GCM-SHA256 - AES128-SHA - ECDHE-ECDSA-AES256-SHA - ECDHE-RSA-AES256-SHA - AES256-GCM-SHA384 - AES256-SHA Supported IANA/RFC aliases: - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA - TLS_RSA_WITH_AES_128_GCM_SHA256 - TLS_RSA_WITH_AES_128_CBC_SHA - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA - TLS_RSA_WITH_AES_256_GCM_SHA384 - TLS_RSA_WITH_AES_256_CBC_SHA In non-FIPS Envoy Proxy builds the default cipher list is: - [ECDHE-ECDSA-AES128-GCM-SHA256\|ECDHE-ECDSA-CHACHA20-POLY1305] - [ECDHE-RSA-AES128-GCM-SHA256\|ECDHE-RSA-CHACHA20-POLY1305] - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 In builds using BoringSSL FIPS the default cipher list is: - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384
`ecdhCurves`	string array	false	ECDHCurves specifies the set of supported ECDH curves. In non-FIPS Envoy Proxy builds the default curves are: - X25519 - P-256 In builds using BoringSSL FIPS the default curve is: - P-256
`signatureAlgorithms`	string array	false	SignatureAlgorithms specifies which signature algorithms the listener should support.
`alpnProtocols`	ALPNProtocol array	false	ALPNProtocols supplies the list of ALPN protocols that should be exposed by the listener or used by the proxy to connect to the backend. Defaults: 1. HTTPS Routes: h2 and http/1.1 are enabled in listener context. 2. Other Routes: ALPN is disabled. 3. Backends: proxy uses the appropriate ALPN options for the backend protocol. When an empty list is provided, the ALPN TLS extension is disabled. Defaults to [h2, http/1.1] if not specified. Typical Supported values are: - http/1.0 - http/1.1 - h2
`fingerprints`	TLSFingerprintType array	false	Fingerprints specifies TLS client fingerprinting. When specified, a JAX fingerprint derived from the client’s TLS handshake is generated. The fingerprint can be logged in access logs or forwarded to upstream services using request headers. Fingerprinting is disabled if not specified. Supported values are: - JA3 - JA4

BackendTLSSettings

BackendTLSSettings holds the TLS settings for the backend.

Appears in:

BackendSpec

Field	Type	Required	Default	Description
`caCertificateRefs`	LocalObjectReference array	false		CACertificateRefs contains one or more references to Kubernetes objects that contain TLS certificates of the Certificate Authorities that can be used as a trust anchor to validate the certificates presented by the backend. A single reference to a Kubernetes ConfigMap or a Kubernetes Secret, with the CA certificate in a key named `ca.crt` is currently supported. If CACertificateRefs is empty or unspecified, then WellKnownCACertificates must be specified. Only one of CACertificateRefs or WellKnownCACertificates may be specified, not both.
`wellKnownCACertificates`	WellKnownCACertificatesType	false		WellKnownCACertificates specifies whether system CA certificates may be used in the TLS handshake between the gateway and backend pod. If WellKnownCACertificates is unspecified or empty (""), then CACertificateRefs must be specified with at least one entry for a valid configuration. Only one of CACertificateRefs or WellKnownCACertificates may be specified, not both.
`insecureSkipVerify`	boolean	false	false	InsecureSkipVerify indicates whether the upstream’s certificate verification should be skipped. Defaults to “false”.
`sni`	PreciseHostname	false		SNI specifies the fixed SNI value used when establishing an upstream TLS connection to the backend. Envoy Gateway will use the HTTP host header value for SNI, when all resources referenced in BackendRefs are: 1. Backend resources that do not set SNI, or 2. Service/ServiceImport resources that do not have a BackendTLSPolicy attached to them If a BackendTLSPolicy is attached to the Backend resource, the BackendTLSPolicy’s validation.hostname value takes precedence over this field. If no BackendTLSPolicy validation.hostname applies and both this field and AutoSNIFromEndpointHostname are unset, Envoy Gateway configures Envoy to set the upstream SNI from the downstream HTTP host/authority header.
`autoSNIFromEndpointHostname`	boolean	false		AutoSNIFromEndpointHostname indicates whether the upstream endpoint’s hostname should be used as the SNI value when establishing a TLS connection to the backend. This uses the resolved hostname of the upstream endpoint (e.g., from the Backend Endpoints list), rather than a static value. Mutually exclusive with SNI. When a BackendTLSPolicy is attached, its Hostname value takes precedence and AutoSNIFromEndpointHostname is ignored.

BackendTelemetry

Appears in:

BackendTrafficPolicySpec

Field	Type	Required	Default	Description
`tracing`	Tracing	false		Tracing configures the tracing settings for the backend or HTTPRoute. This takes precedence over EnvoyProxy tracing when set.
`metrics`	BackendMetrics	false		Metrics defines metrics configuration for the backend or Route.

BackendTrafficPolicy

BackendTrafficPolicy allows the user to configure the behavior of the connection between the Envoy Proxy listener and the backend service.

Field	Type	Required	Default	Description
`apiVersion`	string		`gateway.envoyproxy.io/v1alpha1`
`kind`	string		`BackendTrafficPolicy`
`metadata`	ObjectMeta	true		Refer to Kubernetes API documentation for fields of `metadata`.
`spec`	BackendTrafficPolicySpec	true		spec defines the desired state of BackendTrafficPolicy.
`status`	PolicyStatus	true		status defines the current status of BackendTrafficPolicy.

BackendTrafficPolicySpec

BackendTrafficPolicySpec defines the desired state of BackendTrafficPolicy.

Appears in:

BackendTrafficPolicy

Field	Type	Required	Description
`targetRef`	LocalPolicyTargetReferenceWithSectionName	true	TargetRef is the name of the resource this policy is being attached to. This policy and the TargetRef MUST be in the same namespace for this Policy to have effect Deprecated: use targetRefs/targetSelectors instead
`targetRefs`	LocalPolicyTargetReferenceWithSectionName array	true	TargetRefs are the names of the Gateway resources this policy is being attached to.
`targetSelectors`	TargetSelector array	true	TargetSelectors allow targeting resources for this policy based on labels
`loadBalancer`	LoadBalancer	false	LoadBalancer policy to apply when routing traffic from the gateway to the backend endpoints. Defaults to `LeastRequest`.
`retry`	Retry	false	Retry provides more advanced usage, allowing users to customize the number of retries, retry fallback strategy, and retry triggering conditions. If not set, retry will be disabled.
`proxyProtocol`	ProxyProtocol	false	ProxyProtocol enables the Proxy Protocol when communicating with the backend.
`tcpKeepalive`	TCPKeepalive	false	TcpKeepalive settings associated with the upstream client connection. Disabled by default.
`healthCheck`	HealthCheck	false	HealthCheck allows gateway to perform active health checking on backends.
`circuitBreaker`	CircuitBreaker	false	Circuit Breaker settings for the upstream connections and requests. If not set, circuit breakers will be enabled with the default thresholds
`timeout`	Timeout	false	Timeout settings for the backend connections.
`connection`	BackendConnection	false	Connection includes backend connection settings.
`dns`	DNS	false	DNS includes dns resolution settings.
`http2`	HTTP2Settings	false	HTTP2 provides HTTP/2 configuration for backend connections.
`mergeType`	MergeType	false	MergeType determines how this configuration is merged with existing BackendTrafficPolicy configurations targeting a parent resource. When set, this configuration will be merged into the closest parent BackendTrafficPolicy in the route’s attachment hierarchy (for example, one targeting a Gateway, Gateway listener, ListenerSet, or ListenerSet listener). Currently, this field can only be set when targeting xRoute resources. If unset, no merging occurs, and only the most specific configuration takes effect.
`rateLimit`	RateLimitSpec	false	RateLimit allows the user to limit the number of incoming requests to a predefined value based on attributes within the traffic flow.
`bandwidthLimit`	BandwidthLimitSpec	false	BandwidthLimit allows the user to limit the bandwidth of traffic sent to and received from the backend.
`faultInjection`	FaultInjection	false	FaultInjection defines the fault injection policy to be applied. This configuration can be used to inject delays and abort requests to mimic failure scenarios such as service failures and overloads
`admissionControl`	AdmissionControl	false	AdmissionControl defines the admission control policy to be applied. This configuration probabilistically rejects requests based on the success rate of previous requests in a configurable sliding time window.
`useClientProtocol`	boolean	false	UseClientProtocol configures Envoy to prefer sending requests to backends using the same HTTP protocol that the incoming request used. Defaults to false, which means that Envoy will use the protocol indicated by the attached BackendRef.
`compression`	Compression array	false	The compression config for the http streams. Deprecated: Use Compressor instead.
`compressor`	Compression array	false	The compressor config for the http streams. This provides more granular control over compression configuration. Order matters: The first compressor in the list is preferred when q-values in Accept-Encoding are equal.
`responseOverride`	Re