API Reference

Packages

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:

ValueDescription
http/1.0HTTPProtocolVersion1_0 specifies that HTTP/1.0 should be negotiable with ALPN
http/1.1HTTPProtocolVersion1_1 specifies that HTTP/1.1 should be negotiable with ALPN
h2HTTPProtocolVersion2 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. Specifically, the following metadata is passed:

  • x-accesslog-text - The access log format string when a Text format is used.
  • x-accesslog-attr - JSON encoded key/value pairs when a JSON format is used.

Appears in:

FieldTypeRequiredDescription
backendRefsBackendRef arraytrueBackendRefs references a Kubernetes object that represents the gRPC service to which
the access logs will be sent. Currently only Service is supported.
logNamestringfalseLogName 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.
typeALSEnvoyProxyAccessLogTypetrueType defines the type of accesslog. Supported types are “HTTP” and “TCP”.
httpALSEnvoyProxyHTTPAccessLogConfigfalseHTTP defines additional configuration specific to HTTP access logs.

ALSEnvoyProxyAccessLogType

Underlying type: string

Appears in:

ValueDescription
HTTPALSEnvoyProxyAccessLogTypeHTTP defines the HTTP access log type and will populate StreamAccessLogsMessage.http_logs.
TCPALSEnvoyProxyAccessLogTypeTCP defines the TCP access log type and will populate StreamAccessLogsMessage.tcp_logs.

ALSEnvoyProxyHTTPAccessLogConfig

Appears in:

FieldTypeRequiredDescription
requestHeadersstring arrayfalseRequestHeaders defines request headers to include in log entries sent to the access log service.
responseHeadersstring arrayfalseResponseHeaders defines response headers to include in log entries sent to the access log service.
responseTrailersstring arrayfalseResponseTrailers defines response trailers to include in log entries sent to the access log service.

ActiveHealthCheck

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

Appears in:

FieldTypeRequiredDescription
timeoutDurationfalseTimeout defines the time to wait for a health check response.
intervalDurationfalseInterval defines the time between active health checks.
unhealthyThresholdintegerfalseUnhealthyThreshold defines the number of unhealthy health checks required before a backend host is marked unhealthy.
healthyThresholdintegerfalseHealthyThreshold defines the number of healthy health checks required before a backend host is marked healthy.
typeActiveHealthCheckerTypetrueType defines the type of health checker.
httpHTTPActiveHealthCheckerfalseHTTP defines the configuration of http health checker.
It’s required while the health checker type is HTTP.
tcpTCPActiveHealthCheckerfalseTCP defines the configuration of tcp health checker.
It’s required while the health checker type is TCP.

ActiveHealthCheckPayload

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

Appears in:

FieldTypeRequiredDescription
typeActiveHealthCheckPayloadTypetrueType defines the type of the payload.
textstringfalseText payload in plain text.
binaryinteger arrayfalseBinary payload base64 encoded.

ActiveHealthCheckPayloadType

Underlying type: string

ActiveHealthCheckPayloadType is the type of the payload.

Appears in:

ValueDescription
TextActiveHealthCheckPayloadTypeText defines the Text type payload.
BinaryActiveHealthCheckPayloadTypeBinary defines the Binary type payload.

ActiveHealthCheckerType

Underlying type: string

ActiveHealthCheckerType is the type of health checker.

Appears in:

ValueDescription
HTTPActiveHealthCheckerTypeHTTP defines the HTTP type of health checking.
TCPActiveHealthCheckerTypeTCP defines the TCP type of health checking.

AppProtocolType

Underlying type: string

AppProtocolType defines various backend applications protocols supported by Envoy Gateway

Appears in:

ValueDescription
gateway.envoyproxy.io/h2cAppProtocolTypeH2C defines the HTTP/2 application protocol.
gateway.envoyproxy.io/wsAppProtocolTypeWS defines the WebSocket over HTTP protocol.
gateway.envoyproxy.io/wssAppProtocolTypeWSS 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:

FieldTypeRequiredDescription
rulesAuthorizationRule arrayfalseRules 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.
defaultActionAuthorizationActionfalseDefaultAction 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:

ValueDescription
AllowAuthorizationActionAllow is the action to allow the request.
DenyAuthorizationActionDeny is the action to deny the request.

AuthorizationRule

AuthorizationRule defines a single authorization rule.

Appears in:

FieldTypeRequiredDescription
namestringfalseName is a user-friendly name for the rule.
If not specified, Envoy Gateway will generate a unique name for the rule.n
actionAuthorizationActiontrueAction defines the action to be taken if the rule matches.
principalPrincipaltruePrincipal specifies the client identity of a request.

BackOffPolicy

Appears in:

FieldTypeRequiredDescription
baseIntervalDurationtrueBaseInterval is the base interval between retries.
maxIntervalDurationfalseMaxInterval 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.

Appears in:

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringBackend
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specBackendSpectrueSpec defines the desired state of Backend.
statusBackendStatustrueStatus defines the current status of Backend.

BackendConnection

BackendConnection allows users to configure connection-level settings of backend

Appears in:

FieldTypeRequiredDescription
bufferLimitQuantityfalseBufferLimit Soft limit on size of the cluster’s connections read and write buffers.
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.

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:

FieldTypeRequiredDescription
fqdnFQDNEndpointfalseFQDN defines a FQDN endpoint
ipIPEndpointfalseIP defines an IP endpoint. Currently, only IPv4 Addresses are supported.
unixUnixSocketfalseUnix defines the unix domain socket endpoint

BackendList

BackendList contains a list of Backend resources.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringBackendList
metadataListMetatrueRefer to Kubernetes API documentation for fields of metadata.
itemsBackend arraytrue

BackendRef

BackendRef defines how an ObjectReference that is specific to BackendRef.

Appears in:

FieldTypeRequiredDescription
groupGroupfalseGroup is the group of the referent. For example, “gateway.networking.k8s.io”.
When unspecified or empty string, core API group is inferred.
kindKindfalseKind 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)
nameObjectNametrueName is the name of the referent.
namespaceNamespacefalseNamespace 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
portPortNumberfalsePort 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.

BackendSpec

BackendSpec describes the desired state of BackendSpec.

Appears in:

FieldTypeRequiredDescription
endpointsBackendEndpoint arraytrueEndpoints defines the endpoints to be used when connecting to the backend.
appProtocolsAppProtocolType arrayfalseAppProtocols defines the application protocols to be supported when connecting to the backend.

BackendStatus

BackendStatus defines the state of Backend

Appears in:

FieldTypeRequiredDescription
conditionsCondition arrayfalseConditions describe the current conditions of the Backend.

BackendTLSConfig

BackendTLSConfig describes the BackendTLS configuration for Envoy Proxy.

Appears in:

FieldTypeRequiredDescription
clientCertificateRefSecretObjectReferencefalseClientCertificateRef 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.
minVersionTLSVersionfalseMin specifies the minimal TLS protocol version to allow.
The default is TLS 1.2 if this is not specified.
maxVersionTLSVersionfalseMax specifies the maximal TLS protocol version to allow
The default is TLS 1.3 if this is not specified.
ciphersstring arrayfalseCiphers specifies the set of cipher suites supported when
negotiating TLS 1.0 - 1.2. This setting has no effect for TLS 1.3.
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
ecdhCurvesstring arrayfalseECDHCurves 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
signatureAlgorithmsstring arrayfalseSignatureAlgorithms specifies which signature algorithms the listener should
support.
alpnProtocolsALPNProtocol arrayfalseALPNProtocols supplies the list of ALPN protocols that should be
exposed by the listener. By default h2 and http/1.1 are enabled.
Supported values are:
- http/1.0
- http/1.1
- h2

BackendTrafficPolicy

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

Appears in:

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringBackendTrafficPolicy
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specBackendTrafficPolicySpectruespec defines the desired state of BackendTrafficPolicy.
statusPolicyStatustruestatus defines the current status of BackendTrafficPolicy.

BackendTrafficPolicyList

BackendTrafficPolicyList contains a list of BackendTrafficPolicy resources.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringBackendTrafficPolicyList
metadataListMetatrueRefer to Kubernetes API documentation for fields of metadata.
itemsBackendTrafficPolicy arraytrue

BackendTrafficPolicySpec

BackendTrafficPolicySpec defines the desired state of BackendTrafficPolicy.

Appears in:

FieldTypeRequiredDescription
targetRefLocalPolicyTargetReferenceWithSectionNametrueTargetRef 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
targetRefsLocalPolicyTargetReferenceWithSectionName arraytrueTargetRefs are the names of the Gateway resources this policy
is being attached to.
targetSelectorsTargetSelector arraytrueTargetSelectors allow targeting resources for this policy based on labels
rateLimitRateLimitSpecfalseRateLimit allows the user to limit the number of incoming requests
to a predefined value based on attributes within the traffic flow.
loadBalancerLoadBalancerfalseLoadBalancer policy to apply when routing traffic from the gateway to
the backend endpoints
proxyProtocolProxyProtocolfalseProxyProtocol enables the Proxy Protocol when communicating with the backend.
tcpKeepaliveTCPKeepalivefalseTcpKeepalive settings associated with the upstream client connection.
Disabled by default.
healthCheckHealthCheckfalseHealthCheck allows gateway to perform active health checking on backends.
faultInjectionFaultInjectionfalseFaultInjection 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
circuitBreakerCircuitBreakerfalseCircuit Breaker settings for the upstream connections and requests.
If not set, circuit breakers will be enabled with the default thresholds
retryRetryfalseRetry 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.
useClientProtocolbooleanfalseUseClientProtocol 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.
timeoutTimeoutfalseTimeout settings for the backend connections.
connectionBackendConnectionfalseConnection includes backend connection settings.

BasicAuth

BasicAuth defines the configuration for the HTTP Basic Authentication.

Appears in:

FieldTypeRequiredDescription
usersSecretObjectReferencetrueThe Kubernetes secret which contains the username-password pairs in
htpasswd format, used to verify user credentials in the “Authorization”
header.

This is an Opaque secret. The username-password pairs should be stored in
the key “.htpasswd”. As the key name indicates, the value needs to be the
htpasswd format, for example: “user1:{SHA}hashed_user1_password”.
Right now, only SHA hash algorithm is supported.
Reference to https://httpd.apache.org/docs/2.4/programs/htpasswd.html
for more details.

Note: The secret must be in the same namespace as the SecurityPolicy.

BootstrapType

Underlying type: string

BootstrapType defines the types of bootstrap supported by Envoy Gateway.

Appears in:

ValueDescription
MergeMerge merges the provided bootstrap with the default one. The provided bootstrap can add or override a value
within a map, or add a new value to a list.
Please note that the provided bootstrap can’t override a value within a list.
ReplaceReplace replaces the default bootstrap with the provided one.

CIDR

Underlying type: string

CIDR defines a CIDR Address range. A CIDR can be an IPv4 address range such as “192.168.1.0/24” or an IPv6 address range such as “2001:0db8:11a3:09d7::/64”.

Appears in:

CORS

CORS defines the configuration for Cross-Origin Resource Sharing (CORS).

Appears in:

FieldTypeRequiredDescription
allowOriginsOrigin arraytrueAllowOrigins defines the origins that are allowed to make requests.
allowMethodsstring arraytrueAllowMethods defines the methods that are allowed to make requests.
allowHeadersstring arraytrueAllowHeaders defines the headers that are allowed to be sent with requests.
exposeHeadersstring arraytrueExposeHeaders defines the headers that can be exposed in the responses.
maxAgeDurationtrueMaxAge defines how long the results of a preflight request can be cached.
allowCredentialsbooleantrueAllowCredentials indicates whether a request can include user credentials
like cookies, authentication headers, or TLS client certificates.

CircuitBreaker

CircuitBreaker defines the Circuit Breaker configuration.

Appears in:

FieldTypeRequiredDescription
maxConnectionsintegerfalseThe maximum number of connections that Envoy will establish to the referenced backend defined within a xRoute rule.
maxPendingRequestsintegerfalseThe maximum number of pending requests that Envoy will queue to the referenced backend defined within a xRoute rule.
maxParallelRequestsintegerfalseThe maximum number of parallel requests that Envoy will make to the referenced backend defined within a xRoute rule.
maxParallelRetriesintegerfalseThe maximum number of parallel retries that Envoy will make to the referenced backend defined within a xRoute rule.
maxRequestsPerConnectionintegerfalseThe maximum number of requests that Envoy will make over a single connection to the referenced backend defined within a xRoute rule.
Default: unlimited.

ClaimToHeader

ClaimToHeader defines a configuration to convert JWT claims into HTTP headers

Appears in:

FieldTypeRequiredDescription
headerstringtrueHeader defines the name of the HTTP request header that the JWT Claim will be saved into.
claimstringtrueClaim is the JWT Claim that should be saved into the header : it can be a nested claim of type
(eg. “claim.nested.key”, “sub”). The nested claim name must use dot “."
to separate the JSON name path.

ClientConnection

ClientConnection allows users to configure connection-level settings of client

Appears in:

FieldTypeRequiredDescription
connectionLimitConnectionLimitfalseConnectionLimit defines limits related to connections
bufferLimitQuantityfalseBufferLimit provides configuration for the maximum buffer size in bytes for each incoming connection.
For example, 20Mi, 1Gi, 256Ki etc.
Note that when the suffix is not provided, the value is interpreted as bytes.
Default: 32768 bytes.

ClientIPDetectionSettings

ClientIPDetectionSettings provides configuration for determining the original client IP address for requests.

Appears in:

FieldTypeRequiredDescription
xForwardedForXForwardedForSettingsfalseXForwardedForSettings provides configuration for using X-Forwarded-For headers for determining the client IP address.
customHeaderCustomHeaderExtensionSettingsfalseCustomHeader provides configuration for determining the client IP address for a request based on
a trusted custom HTTP header. This uses the custom_header original IP detection extension.
Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto
for more details.

ClientTLSSettings

Appears in:

FieldTypeRequiredDescription
clientValidationClientValidationContextfalseClientValidation specifies the configuration to validate the client
initiating the TLS connection to the Gateway listener.
minVersionTLSVersionfalseMin specifies the minimal TLS protocol version to allow.
The default is TLS 1.2 if this is not specified.
maxVersionTLSVersionfalseMax specifies the maximal TLS protocol version to allow
The default is TLS 1.3 if this is not specified.
ciphersstring arrayfalseCiphers specifies the set of cipher suites supported when
negotiating TLS 1.0 - 1.2. This setting has no effect for TLS 1.3.
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
ecdhCurvesstring arrayfalseECDHCurves 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
signatureAlgorithmsstring arrayfalseSignatureAlgorithms specifies which signature algorithms the listener should
support.
alpnProtocolsALPNProtocol arrayfalseALPNProtocols supplies the list of ALPN protocols that should be
exposed by the listener. By default h2 and http/1.1 are enabled.
Supported values are:
- http/1.0
- http/1.1
- h2

ClientTimeout

Appears in:

FieldTypeRequiredDescription
tcpTCPClientTimeoutfalseTimeout settings for TCP.
httpHTTPClientTimeoutfalseTimeout settings for HTTP.

ClientTrafficPolicy

ClientTrafficPolicy allows the user to configure the behavior of the connection between the downstream client and Envoy Proxy listener.

Appears in:

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringClientTrafficPolicy
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specClientTrafficPolicySpectrueSpec defines the desired state of ClientTrafficPolicy.
statusPolicyStatustrueStatus defines the current status of ClientTrafficPolicy.

ClientTrafficPolicyList

ClientTrafficPolicyList contains a list of ClientTrafficPolicy resources.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringClientTrafficPolicyList
metadataListMetatrueRefer to Kubernetes API documentation for fields of metadata.
itemsClientTrafficPolicy arraytrue

ClientTrafficPolicySpec

ClientTrafficPolicySpec defines the desired state of ClientTrafficPolicy.

Appears in:

FieldTypeRequiredDescription
targetRefLocalPolicyTargetReferenceWithSectionNametrueTargetRef 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
targetRefsLocalPolicyTargetReferenceWithSectionName arraytrueTargetRefs are the names of the Gateway resources this policy
is being attached to.
targetSelectorsTargetSelector arraytrueTargetSelectors allow targeting resources for this policy based on labels
tcpKeepaliveTCPKeepalivefalseTcpKeepalive settings associated with the downstream client connection.
If defined, sets SO_KEEPALIVE on the listener socket to enable TCP Keepalives.
Disabled by default.
enableProxyProtocolbooleanfalseEnableProxyProtocol interprets the ProxyProtocol header and adds the
Client Address into the X-Forwarded-For header.
Note Proxy Protocol must be present when this field is set, else the connection
is closed.
clientIPDetectionClientIPDetectionSettingsfalseClientIPDetectionSettings provides configuration for determining the original client IP address for requests.
tlsClientTLSSettingsfalseTLS settings configure TLS termination settings with the downstream client.
pathPathSettingsfalsePath enables managing how the incoming path set by clients can be normalized.
headersHeaderSettingsfalseHeaderSettings provides configuration for header management.
timeoutClientTimeoutfalseTimeout settings for the client connections.
connectionClientConnectionfalseConnection includes client connection settings.
http1HTTP1SettingsfalseHTTP1 provides HTTP/1 configuration on the listener.
http2HTTP2SettingsfalseHTTP2 provides HTTP/2 configuration on the listener.
http3HTTP3SettingsfalseHTTP3 provides HTTP/3 configuration on the listener.
healthCheckHealthCheckSettingsfalseHealthCheck provides configuration for determining whether the HTTP/HTTPS listener is healthy.

ClientValidationContext

ClientValidationContext holds configuration that can be used to validate the client initiating the TLS connection to the Gateway. By default, no client specific configuration is validated.

Appears in:

FieldTypeRequiredDescription
optionalbooleanfalseOptional set to true accepts connections even when a client doesn’t present a certificate.
Defaults to false, which rejects connections without a valid client certificate.
caCertificateRefsSecretObjectReference arrayfalseCACertificateRefs 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 client.

A single reference to a Kubernetes ConfigMap or a Kubernetes Secret,
with the CA certificate in a key named ca.crt is currently supported.

References to a resource in different namespace are invalid UNLESS there
is a ReferenceGrant in the target namespace that allows the certificate
to be attached.

Compression

Compression defines the config of enabling compression. This can help reduce the bandwidth at the expense of higher CPU.

Appears in:

FieldTypeRequiredDescription
typeCompressorTypetrueCompressorType defines the compressor type to use for compression.
gzipGzipCompressorfalseThe configuration for GZIP compressor.

CompressorType

Underlying type: string

CompressorType defines the types of compressor library supported by Envoy Gateway.

Appears in:

ConnectionLimit

Appears in:

FieldTypeRequiredDescription
valueintegertrueValue of the maximum concurrent connections limit.
When the limit is reached, incoming connections will be closed after the CloseDelay duration.
Default: unlimited.
closeDelayDurationfalseCloseDelay defines the delay to use before closing connections that are rejected
once the limit value is reached.
Default: none.

ConsistentHash

ConsistentHash defines the configuration related to the consistent hash load balancer policy.

Appears in:

FieldTypeRequiredDescription
typeConsistentHashTypetrueConsistentHashType defines the type of input to hash on. Valid Type values are
“SourceIP”,
“Header”,
“Cookie”.
headerHeaderfalseHeader configures the header hash policy when the consistent hash type is set to Header.
cookieCookiefalseCookie configures the cookie hash policy when the consistent hash type is set to Cookie.
tableSizeintegerfalseThe table size for consistent hashing, must be prime number limited to 5000011.

ConsistentHashType

Underlying type: string

ConsistentHashType defines the type of input to hash on.

Appears in:

ValueDescription
SourceIPSourceIPConsistentHashType hashes based on the source IP address.
HeaderHeaderConsistentHashType hashes based on a request header.
CookieCookieConsistentHashType hashes based on a cookie.

Cookie defines the cookie hashing configuration for consistent hash based load balancing.

Appears in:

FieldTypeRequiredDescription
namestringtrueName of the cookie to hash.
If this cookie does not exist in the request, Envoy will generate a cookie and set
the TTL on the response back to the client based on Layer 4
attributes of the backend endpoint, to ensure that these future requests
go to the same backend endpoint. Make sure to set the TTL field for this case.
ttlDurationfalseTTL of the generated cookie if the cookie is not present. This value sets the
Max-Age attribute value.
attributesobject (keys:string, values:string)falseAdditional Attributes to set for the generated cookie.

CustomHeaderExtensionSettings

CustomHeaderExtensionSettings provides configuration for determining the client IP address for a request based on a trusted custom HTTP header. This uses the the custom_header original IP detection extension. Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto for more details.

Appears in:

FieldTypeRequiredDescription
namestringtrueName of the header containing the original downstream remote address, if present.
failClosedbooleanfalseFailClosed is a switch used to control the flow of traffic when client IP detection
fails. If set to true, the listener will respond with 403 Forbidden when the client
IP address cannot be determined.

CustomTag

Appears in:

FieldTypeRequiredDescription
typeCustomTagTypetrueType defines the type of custom tag.
literalLiteralCustomTagtrueLiteral adds hard-coded value to each span.
It’s required when the type is “Literal”.
environmentEnvironmentCustomTagtrueEnvironment adds value from environment variable to each span.
It’s required when the type is “Environment”.
requestHeaderRequestHeaderCustomTagtrueRequestHeader adds value from request header to each span.
It’s required when the type is “RequestHeader”.

CustomTagType

Underlying type: string

Appears in:

ValueDescription
LiteralCustomTagTypeLiteral adds hard-coded value to each span.
EnvironmentCustomTagTypeEnvironment adds value from environment variable to each span.
RequestHeaderCustomTagTypeRequestHeader adds value from request header to each span.

EnvironmentCustomTag

EnvironmentCustomTag adds value from environment variable to each span.

Appears in:

FieldTypeRequiredDescription
namestringtrueName defines the name of the environment variable which to extract the value from.
defaultValuestringfalseDefaultValue defines the default value to use if the environment variable is not set.

EnvoyExtensionPolicy

EnvoyExtensionPolicy allows the user to configure various envoy extensibility options for the Gateway.

Appears in:

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringEnvoyExtensionPolicy
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specEnvoyExtensionPolicySpectrueSpec defines the desired state of EnvoyExtensionPolicy.
statusPolicyStatustrueStatus defines the current status of EnvoyExtensionPolicy.

EnvoyExtensionPolicyList

EnvoyExtensionPolicyList contains a list of EnvoyExtensionPolicy resources.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringEnvoyExtensionPolicyList
metadataListMetatrueRefer to Kubernetes API documentation for fields of metadata.
itemsEnvoyExtensionPolicy arraytrue

EnvoyExtensionPolicySpec

EnvoyExtensionPolicySpec defines the desired state of EnvoyExtensionPolicy.

Appears in:

FieldTypeRequiredDescription
targetRefLocalPolicyTargetReferenceWithSectionNametrueTargetRef 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
targetRefsLocalPolicyTargetReferenceWithSectionName arraytrueTargetRefs are the names of the Gateway resources this policy
is being attached to.
targetSelectorsTargetSelector arraytrueTargetSelectors allow targeting resources for this policy based on labels
wasmWasm arrayfalseWasm is a list of Wasm extensions to be loaded by the Gateway.
Order matters, as the extensions will be loaded in the order they are
defined in this list.
extProcExtProc arrayfalseExtProc is an ordered list of external processing filters
that should added to the envoy filter chain

EnvoyFilter

Underlying type: string

EnvoyFilter defines the type of Envoy HTTP filter.

Appears in:

ValueDescription
envoy.filters.http.health_checkEnvoyFilterHealthCheck defines the Envoy HTTP health check filter.
envoy.filters.http.faultEnvoyFilterFault defines the Envoy HTTP fault filter.
envoy.filters.http.corsEnvoyFilterCORS defines the Envoy HTTP CORS filter.
envoy.filters.http.ext_authzEnvoyFilterExtAuthz defines the Envoy HTTP external authorization filter.
envoy.filters.http.basic_authEnvoyFilterBasicAuth defines the Envoy HTTP basic authentication filter.
envoy.filters.http.oauth2EnvoyFilterOAuth2 defines the Envoy HTTP OAuth2 filter.
envoy.filters.http.jwt_authnEnvoyFilterJWTAuthn defines the Envoy HTTP JWT authentication filter.
envoy.filters.http.ext_procEnvoyFilterExtProc defines the Envoy HTTP external process filter.
envoy.filters.http.wasmEnvoyFilterWasm defines the Envoy HTTP WebAssembly filter.
envoy.filters.http.rbacEnvoyFilterRBAC defines the Envoy RBAC filter.
envoy.filters.http.local_ratelimitEnvoyFilterLocalRateLimit defines the Envoy HTTP local rate limit filter.
envoy.filters.http.ratelimitEnvoyFilterRateLimit defines the Envoy HTTP rate limit filter.
envoy.filters.http.routerEnvoyFilterRouter defines the Envoy HTTP router filter.

EnvoyGateway

EnvoyGateway is the schema for the envoygateways API.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringEnvoyGateway
gatewayGatewayfalseGateway defines desired Gateway API specific configuration. If unset,
default configuration parameters will apply.
providerEnvoyGatewayProviderfalseProvider defines the desired provider and provider-specific configuration.
If unspecified, the Kubernetes provider is used with default configuration
parameters.
loggingEnvoyGatewayLoggingfalseLogging defines logging parameters for Envoy Gateway.
adminEnvoyGatewayAdminfalseAdmin defines the desired admin related abilities.
If unspecified, the Admin is used with default configuration
parameters.
telemetryEnvoyGatewayTelemetryfalseTelemetry defines the desired control plane telemetry related abilities.
If unspecified, the telemetry is used with default configuration.
rateLimitRateLimitfalseRateLimit defines the configuration associated with the Rate Limit service
deployed by Envoy Gateway required to implement the Global Rate limiting
functionality. The specific rate limit service used here is the reference
implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.
This configuration is unneeded for “Local” rate limiting.
extensionManagerExtensionManagerfalseExtensionManager defines an extension manager to register for the Envoy Gateway Control Plane.
extensionApisExtensionAPISettingsfalseExtensionAPIs defines the settings related to specific Gateway API Extensions
implemented by Envoy Gateway

EnvoyGatewayAdmin

EnvoyGatewayAdmin defines the Envoy Gateway Admin configuration.

Appears in:

FieldTypeRequiredDescription
addressEnvoyGatewayAdminAddressfalseAddress defines the address of Envoy Gateway Admin Server.
enableDumpConfigbooleanfalseEnableDumpConfig defines if enable dump config in Envoy Gateway logs.
enablePprofbooleanfalseEnablePprof defines if enable pprof in Envoy Gateway Admin Server.

EnvoyGatewayAdminAddress

EnvoyGatewayAdminAddress defines the Envoy Gateway Admin Address configuration.

Appears in:

FieldTypeRequiredDescription
portintegerfalsePort defines the port the admin server is exposed on.
hoststringfalseHost defines the admin server hostname.

EnvoyGatewayCustomProvider

EnvoyGatewayCustomProvider defines configuration for the Custom provider.

Appears in:

FieldTypeRequiredDescription
resourceEnvoyGatewayResourceProvidertrueResource defines the desired resource provider.
This provider is used to specify the provider to be used
to retrieve the resource configurations such as Gateway API
resources
infrastructureEnvoyGatewayInfrastructureProvidertrueInfrastructure defines the desired infrastructure provider.
This provider is used to specify the provider to be used
to provide an environment to deploy the out resources like
the Envoy Proxy data plane.

EnvoyGatewayFileResourceProvider

EnvoyGatewayFileResourceProvider defines configuration for the File Resource provider.

Appears in:

FieldTypeRequiredDescription
pathsstring arraytruePaths are the paths to a directory or file containing the resource configuration.
Recursive sub directories are not currently supported.

EnvoyGatewayHostInfrastructureProvider

EnvoyGatewayHostInfrastructureProvider defines configuration for the Host Infrastructure provider.

Appears in:

EnvoyGatewayInfrastructureProvider

EnvoyGatewayInfrastructureProvider defines configuration for the Custom Infrastructure provider.

Appears in:

FieldTypeRequiredDescription
typeInfrastructureProviderTypetrueType is the type of infrastructure providers to use. Supported types are “Host”.
hostEnvoyGatewayHostInfrastructureProviderfalseHost defines the configuration of the Host provider. Host provides runtime
deployment of the data plane as a child process on the host environment.

EnvoyGatewayKubernetesProvider

EnvoyGatewayKubernetesProvider defines configuration for the Kubernetes provider.

Appears in:

FieldTypeRequiredDescription
rateLimitDeploymentKubernetesDeploymentSpecfalseRateLimitDeployment defines the desired state of the Envoy ratelimit deployment resource.
If unspecified, default settings for the managed Envoy ratelimit deployment resource
are applied.
watchKubernetesWatchModefalseWatch holds configuration of which input resources should be watched and reconciled.
deployKubernetesDeployModefalseDeploy holds configuration of how output managed resources such as the Envoy Proxy data plane
should be deployed
overwriteControlPlaneCertsbooleanfalseOverwriteControlPlaneCerts updates the secrets containing the control plane certs, when set.
leaderElectionLeaderElectionfalseLeaderElection specifies the configuration for leader election.
If it’s not set up, leader election will be active by default, using Kubernetes’ standard settings.
shutdownManagerShutdownManagerfalseShutdownManager defines the configuration for the shutdown manager.

EnvoyGatewayLogComponent

Underlying type: string

EnvoyGatewayLogComponent defines a component that supports a configured logging level.

Appears in:

ValueDescription
defaultLogComponentGatewayDefault defines the “default”-wide logging component. When specified,
all other logging components are ignored.
providerLogComponentProviderRunner defines the “provider” runner component.
gateway-apiLogComponentGatewayAPIRunner defines the “gateway-api” runner component.
xds-translatorLogComponentXdsTranslatorRunner defines the “xds-translator” runner component.
xds-serverLogComponentXdsServerRunner defines the “xds-server” runner component.
infrastructureLogComponentInfrastructureRunner defines the “infrastructure” runner component.
global-ratelimitLogComponentGlobalRateLimitRunner defines the “global-ratelimit” runner component.

EnvoyGatewayLogging

EnvoyGatewayLogging defines logging for Envoy Gateway.

Appears in:

FieldTypeRequiredDescription
levelobject (keys:EnvoyGatewayLogComponent, values:LogLevel)trueLevel is the logging level. If unspecified, defaults to “info”.
EnvoyGatewayLogComponent options: default/provider/gateway-api/xds-translator/xds-server/infrastructure/global-ratelimit.
LogLevel options: debug/info/error/warn.

EnvoyGatewayMetricSink

EnvoyGatewayMetricSink defines control plane metric sinks where metrics are sent to.

Appears in:

FieldTypeRequiredDescription
typeMetricSinkTypetrueType defines the metric sink type.
EG control plane currently supports OpenTelemetry.
openTelemetryEnvoyGatewayOpenTelemetrySinktrueOpenTelemetry defines the configuration for OpenTelemetry sink.
It’s required if the sink type is OpenTelemetry.

EnvoyGatewayMetrics

EnvoyGatewayMetrics defines control plane push/pull metrics configurations.

Appears in:

FieldTypeRequiredDescription
sinksEnvoyGatewayMetricSink arraytrueSinks defines the metric sinks where metrics are sent to.
prometheusEnvoyGatewayPrometheusProvidertruePrometheus defines the configuration for prometheus endpoint.

EnvoyGatewayOpenTelemetrySink

Appears in:

FieldTypeRequiredDescription
hoststringtrueHost define the sink service hostname.
protocolstringtrueProtocol define the sink service protocol.
portintegerfalsePort defines the port the sink service is exposed on.
exportIntervalDurationtrueExportInterval configures the intervening time between exports for a
Sink. This option overrides any value set for the
OTEL_METRIC_EXPORT_INTERVAL environment variable.
If ExportInterval is less than or equal to zero, 60 seconds
is used as the default.
exportTimeoutDurationtrueExportTimeout configures the time a Sink waits for an export to
complete before canceling it. This option overrides any value set for the
OTEL_METRIC_EXPORT_TIMEOUT environment variable.
If ExportTimeout is less than or equal to zero, 30 seconds
is used as the default.

EnvoyGatewayPrometheusProvider

EnvoyGatewayPrometheusProvider will expose prometheus endpoint in pull mode.

Appears in:

FieldTypeRequiredDescription
disablebooleantrueDisable defines if disables the prometheus metrics in pull mode.

EnvoyGatewayProvider

EnvoyGatewayProvider defines the desired configuration of a provider.

Appears in:

FieldTypeRequiredDescription
typeProviderTypetrueType is the type of provider to use. Supported types are “Kubernetes”.
kubernetesEnvoyGatewayKubernetesProviderfalseKubernetes defines the configuration of the Kubernetes provider. Kubernetes
provides runtime configuration via the Kubernetes API.
customEnvoyGatewayCustomProviderfalseCustom defines the configuration for the Custom provider. This provider
allows you to define a specific resource provider and a infrastructure
provider.

EnvoyGatewayResourceProvider

EnvoyGatewayResourceProvider defines configuration for the Custom Resource provider.

Appears in:

FieldTypeRequiredDescription
typeResourceProviderTypetrueType is the type of resource provider to use. Supported types are “File”.
fileEnvoyGatewayFileResourceProviderfalseFile defines the configuration of the File provider. File provides runtime
configuration defined by one or more files.

EnvoyGatewaySpec

EnvoyGatewaySpec defines the desired state of Envoy Gateway.

Appears in:

FieldTypeRequiredDescription
gatewayGatewayfalseGateway defines desired Gateway API specific configuration. If unset,
default configuration parameters will apply.
providerEnvoyGatewayProviderfalseProvider defines the desired provider and provider-specific configuration.
If unspecified, the Kubernetes provider is used with default configuration
parameters.
loggingEnvoyGatewayLoggingfalseLogging defines logging parameters for Envoy Gateway.
adminEnvoyGatewayAdminfalseAdmin defines the desired admin related abilities.
If unspecified, the Admin is used with default configuration
parameters.
telemetryEnvoyGatewayTelemetryfalseTelemetry defines the desired control plane telemetry related abilities.
If unspecified, the telemetry is used with default configuration.
rateLimitRateLimitfalseRateLimit defines the configuration associated with the Rate Limit service
deployed by Envoy Gateway required to implement the Global Rate limiting
functionality. The specific rate limit service used here is the reference
implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.
This configuration is unneeded for “Local” rate limiting.
extensionManagerExtensionManagerfalseExtensionManager defines an extension manager to register for the Envoy Gateway Control Plane.
extensionApisExtensionAPISettingsfalseExtensionAPIs defines the settings related to specific Gateway API Extensions
implemented by Envoy Gateway

EnvoyGatewayTelemetry

EnvoyGatewayTelemetry defines telemetry configurations for envoy gateway control plane. Control plane will focus on metrics observability telemetry and tracing telemetry later.

Appears in:

FieldTypeRequiredDescription
metricsEnvoyGatewayMetricstrueMetrics defines metrics configuration for envoy gateway.

EnvoyJSONPatchConfig

EnvoyJSONPatchConfig defines the configuration for patching a Envoy xDS Resource using JSONPatch semantic

Appears in:

FieldTypeRequiredDescription
typeEnvoyResourceTypetrueType is the typed URL of the Envoy xDS Resource
namestringtrueName is the name of the resource
operationJSONPatchOperationtruePatch defines the JSON Patch Operation

EnvoyPatchPolicy

EnvoyPatchPolicy allows the user to modify the generated Envoy xDS resources by Envoy Gateway using this patch API

Appears in:

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringEnvoyPatchPolicy
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specEnvoyPatchPolicySpectrueSpec defines the desired state of EnvoyPatchPolicy.
statusPolicyStatustrueStatus defines the current status of EnvoyPatchPolicy.

EnvoyPatchPolicyList

EnvoyPatchPolicyList contains a list of EnvoyPatchPolicy resources.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringEnvoyPatchPolicyList
metadataListMetatrueRefer to Kubernetes API documentation for fields of metadata.
itemsEnvoyPatchPolicy arraytrue

EnvoyPatchPolicySpec

EnvoyPatchPolicySpec defines the desired state of EnvoyPatchPolicy.

Appears in:

FieldTypeRequiredDescription
typeEnvoyPatchTypetrueType decides the type of patch.
Valid EnvoyPatchType values are “JSONPatch”.
jsonPatchesEnvoyJSONPatchConfig arrayfalseJSONPatch defines the JSONPatch configuration.
targetRefLocalPolicyTargetReferencetrueTargetRef is the name of the Gateway API resource this policy
is being attached to.
By default, attaching to Gateway is supported and
when mergeGateways is enabled it should attach to GatewayClass.
This Policy and the TargetRef MUST be in the same namespace
for this Policy to have effect and be applied to the Gateway
TargetRef
priorityintegertruePriority of the EnvoyPatchPolicy.
If multiple EnvoyPatchPolicies are applied to the same
TargetRef, they will be applied in the ascending order of
the priority i.e. int32.min has the highest priority and
int32.max has the lowest priority.
Defaults to 0.

EnvoyPatchType

Underlying type: string

EnvoyPatchType specifies the types of Envoy patching mechanisms.

Appears in:

ValueDescription
JSONPatchJSONPatchEnvoyPatchType allows the user to patch the generated xDS resources using JSONPatch semantics.
For more details on the semantics, please refer to https://datatracker.ietf.org/doc/html/rfc6902

EnvoyProxy

EnvoyProxy is the schema for the envoyproxies API.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringEnvoyProxy
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specEnvoyProxySpectrueEnvoyProxySpec defines the desired state of EnvoyProxy.
statusEnvoyProxyStatustrueEnvoyProxyStatus defines the actual state of EnvoyProxy.

EnvoyProxyKubernetesProvider

EnvoyProxyKubernetesProvider defines configuration for the Kubernetes resource provider.

Appears in:

FieldTypeRequiredDescription
envoyDeploymentKubernetesDeploymentSpecfalseEnvoyDeployment defines the desired state of the Envoy deployment resource.
If unspecified, default settings for the managed Envoy deployment resource
are applied.
envoyDaemonSetKubernetesDaemonSetSpecfalseEnvoyDaemonSet defines the desired state of the Envoy daemonset resource.
Disabled by default, a deployment resource is used instead to provision the Envoy Proxy fleet
envoyServiceKubernetesServiceSpecfalseEnvoyService defines the desired state of the Envoy service resource.
If unspecified, default settings for the managed Envoy service resource
are applied.
envoyHpaKubernetesHorizontalPodAutoscalerSpecfalseEnvoyHpa defines the Horizontal Pod Autoscaler settings for Envoy Proxy Deployment.
Once the HPA is being set, Replicas field from EnvoyDeployment will be ignored.
useListenerPortAsContainerPortbooleanfalseUseListenerPortAsContainerPort disables the port shifting feature in the Envoy Proxy.
When set to false (default value), if the service port is a privileged port (1-1023), add a constant to the value converting it into an ephemeral port.
This allows the container to bind to the port without needing a CAP_NET_BIND_SERVICE capability.
envoyPDBKubernetesPodDisruptionBudgetSpecfalseEnvoyPDB allows to control the pod disruption budget of an Envoy Proxy.

EnvoyProxyProvider

EnvoyProxyProvider defines the desired state of a resource provider.

Appears in:

FieldTypeRequiredDescription
typeProviderTypetrueType is the type of resource provider to use. A resource provider provides
infrastructure resources for running the data plane, e.g. Envoy proxy, and
optional auxiliary control planes. Supported types are “Kubernetes”.
kubernetesEnvoyProxyKubernetesProviderfalseKubernetes defines the desired state of the Kubernetes resource provider.
Kubernetes provides infrastructure resources for running the data plane,
e.g. Envoy proxy. If unspecified and type is “Kubernetes”, default settings
for managed Kubernetes resources are applied.

EnvoyProxySpec

EnvoyProxySpec defines the desired state of EnvoyProxy.

Appears in:

FieldTypeRequiredDescription
providerEnvoyProxyProviderfalseProvider defines the desired resource provider and provider-specific configuration.
If unspecified, the “Kubernetes” resource provider is used with default configuration
parameters.
loggingProxyLoggingtrueLogging defines logging parameters for managed proxies.
telemetryProxyTelemetryfalseTelemetry defines telemetry parameters for managed proxies.
bootstrapProxyBootstrapfalseBootstrap defines the Envoy Bootstrap as a YAML string.
Visit https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-msg-config-bootstrap-v3-bootstrap
to learn more about the syntax.
If set, this is the Bootstrap configuration used for the managed Envoy Proxy fleet instead of the default Bootstrap configuration
set by Envoy Gateway.
Some fields within the Bootstrap that are required to communicate with the xDS Server (Envoy Gateway) and receive xDS resources
from it are not configurable and will result in the EnvoyProxy resource being rejected.
Backward compatibility across minor versions is not guaranteed.
We strongly recommend using egctl x translate to generate a EnvoyProxy resource with the Bootstrap field set to the default
Bootstrap configuration used. You can edit this configuration, and rerun egctl x translate to ensure there are no validation errors.
concurrencyintegerfalseConcurrency defines the number of worker threads to run. If unset, it defaults to
the number of cpuset threads on the platform.
routingTypeRoutingTypefalseRoutingType can be set to “Service” to use the Service Cluster IP for routing to the backend,
or it can be set to “Endpoint” to use Endpoint routing. The default is “Endpoint”.
extraArgsstring arrayfalseExtraArgs defines additional command line options that are provided to Envoy.
More info: https://www.envoyproxy.io/docs/envoy/latest/operations/cli#command-line-options
Note: some command line options are used internally(e.g. –log-level) so they cannot be provided here.
mergeGatewaysbooleanfalseMergeGateways defines if Gateway resources should be merged onto the same Envoy Proxy Infrastructure.
Setting this field to true would merge all Gateway Listeners under the parent Gateway Class.
This means that the port, protocol and hostname tuple must be unique for every listener.
If a duplicate listener is detected, the newer listener (based on timestamp) will be rejected and its status will be updated with a “Accepted=False” condition.
shutdownShutdownConfigfalseShutdown defines configuration for graceful envoy shutdown process.
filterOrderFilterPosition arrayfalseFilterOrder defines the order of filters in the Envoy proxy’s HTTP filter chain.
The FilterPosition in the list will be applied in the order they are defined.
If unspecified, the default filter order is applied.
Default filter order is:

- envoy.filters.http.health_check

- envoy.filters.http.fault

- envoy.filters.http.cors

- envoy.filters.http.ext_authz

- envoy.filters.http.basic_auth

- envoy.filters.http.oauth2

- envoy.filters.http.jwt_authn

- envoy.filters.http.ext_proc

- envoy.filters.http.wasm

- envoy.filters.http.rbac

- envoy.filters.http.local_ratelimit

- envoy.filters.http.ratelimit

- envoy.filters.http.router

Note: “envoy.filters.http.router” cannot be reordered, it’s always the last filter in the chain.
backendTLSBackendTLSConfigfalseBackendTLS is the TLS configuration for the Envoy proxy to use when connecting to backends.
These settings are applied on backends for which TLS policies are specified.

EnvoyProxyStatus

EnvoyProxyStatus defines the observed state of EnvoyProxy. This type is not implemented until https://github.com/envoyproxy/gateway/issues/1007 is fixed.

Appears in:

EnvoyResourceType

Underlying type: string

EnvoyResourceType specifies the type URL of the Envoy resource.

Appears in:

ValueDescription
type.googleapis.com/envoy.config.listener.v3.ListenerListenerEnvoyResourceType defines the Type URL of the Listener resource
type.googleapis.com/envoy.config.route.v3.RouteConfigurationRouteConfigurationEnvoyResourceType defines the Type URL of the RouteConfiguration resource
type.googleapis.com/envoy.config.cluster.v3.ClusterClusterEnvoyResourceType defines the Type URL of the Cluster resource
type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignmentClusterLoadAssignmentEnvoyResourceType defines the Type URL of the ClusterLoadAssignment resource

ExtAuth

ExtAuth defines the configuration for External Authorization.

Appears in:

FieldTypeRequiredDescription
grpcGRPCExtAuthServicetrueGRPC defines the gRPC External Authorization service.
Either GRPCService or HTTPService must be specified,
and only one of them can be provided.
httpHTTPExtAuthServicetrueHTTP defines the HTTP External Authorization service.
Either GRPCService or HTTPService must be specified,
and only one of them can be provided.
headersToExtAuthstring arrayfalseHeadersToExtAuth defines the client request headers that will be included
in the request to the external authorization service.
Note: If not specified, the default behavior for gRPC and HTTP external
authorization services is different due to backward compatibility reasons.
All headers will be included in the check request to a gRPC authorization server.
Only the following headers will be included in the check request to an HTTP
authorization server: Host, Method, Path, Content-Length, and Authorization.
And these headers will always be included to the check request to an HTTP
authorization server by default, no matter whether they are specified
in HeadersToExtAuth or not.
failOpenbooleanfalseFailOpen is a switch used to control the behavior when a response from the External Authorization service cannot be obtained.
If FailOpen is set to true, the system allows the traffic to pass through.
Otherwise, if it is set to false or not set (defaulting to false),
the system blocks the traffic and returns a HTTP 5xx error, reflecting a fail-closed approach.
This setting determines whether to prioritize accessibility over strict security in case of authorization service failure.

ExtProc

ExtProc defines the configuration for External Processing filter.

Appears in:

FieldTypeRequiredDescription
backendRefsBackendRef arraytrueBackendRefs defines the configuration of the external processing service
messageTimeoutDurationfalseMessageTimeout is the timeout for a response to be returned from the external processor
Default: 200ms
failOpenbooleanfalseFailOpen defines if requests or responses that cannot be processed due to connectivity to the
external processor are terminated or passed-through.
Default: false
processingModeExtProcProcessingModefalseProcessingMode defines how request and response body is processed
Default: header and body are not sent to the external processor

ExtProcBodyProcessingMode

Underlying type: string

Appears in:

ValueDescription
StreamedStreamedExtProcBodyProcessingMode will stream the body to the server in pieces as they arrive at the proxy.
BufferedBufferedExtProcBodyProcessingMode will buffer the message body in memory and send the entire body at once. If the body exceeds the configured buffer limit, then the downstream system will receive an error.
BufferedPartialBufferedPartialExtBodyHeaderProcessingMode will buffer the message body in memory and send the entire body in one chunk. If the body exceeds the configured buffer limit, then the body contents up to the buffer limit will be sent.

ExtProcProcessingMode

ExtProcProcessingMode defines if and how headers and bodies are sent to the service. https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/processing_mode.proto#envoy-v3-api-msg-extensions-filters-http-ext-proc-v3-processingmode

Appears in:

FieldTypeRequiredDescription
requestProcessingModeOptionsfalseDefines processing mode for requests. If present, request headers are sent. Request body is processed according
to the specified mode.
responseProcessingModeOptionsfalseDefines processing mode for responses. If present, response headers are sent. Response body is processed according
to the specified mode.

ExtensionAPISettings

ExtensionAPISettings defines the settings specific to Gateway API Extensions.

Appears in:

FieldTypeRequiredDescription
enableEnvoyPatchPolicybooleantrueEnableEnvoyPatchPolicy enables Envoy Gateway to
reconcile and implement the EnvoyPatchPolicy resources.
enableBackendbooleantrueEnableBackend enables Envoy Gateway to
reconcile and implement the Backend resources.

ExtensionHooks

ExtensionHooks defines extension hooks across all supported runners

Appears in:

FieldTypeRequiredDescription
xdsTranslatorXDSTranslatorHookstrueXDSTranslator defines all the supported extension hooks for the xds-translator runner

ExtensionManager

ExtensionManager defines the configuration for registering an extension manager to the Envoy Gateway control plane.

Appears in:

FieldTypeRequiredDescription
resourcesGroupVersionKind arrayfalseResources defines the set of K8s resources the extension will handle as route
filter resources
policyResourcesGroupVersionKind arrayfalsePolicyResources defines the set of K8S resources the extension server will handle
as directly attached GatewayAPI policies
hooksExtensionHookstrueHooks defines the set of hooks the extension supports
serviceExtensionServicetrueService defines the configuration of the extension service that the Envoy
Gateway Control Plane will call through extension hooks.

ExtensionService

ExtensionService defines the configuration for connecting to a registered extension service.

Appears in:

FieldTypeRequiredDescription
fqdnFQDNEndpointfalseFQDN defines a FQDN endpoint
ipIPEndpointfalseIP defines an IP endpoint. Currently, only IPv4 Addresses are supported.
unixUnixSocketfalseUnix defines the unix domain socket endpoint
hoststringfalseHost define the extension service hostname.
Deprecated: use the appropriate transport attribute instead (FQDN,IP,Unix)
portintegerfalsePort defines the port the extension service is exposed on.
Deprecated: use the appropriate transport attribute instead (FQDN,IP,Unix)
tlsExtensionTLSfalseTLS defines TLS configuration for communication between Envoy Gateway and
the extension service.

ExtensionTLS

ExtensionTLS defines the TLS configuration when connecting to an extension service

Appears in:

FieldTypeRequiredDescription
certificateRefSecretObjectReferencetrueCertificateRef contains a references to objects (Kubernetes objects or otherwise) that
contains a TLS certificate and private keys. These certificates are used to
establish a TLS handshake to the extension server.

CertificateRef can only reference a Kubernetes Secret at this time.

FQDNEndpoint

FQDNEndpoint describes TCP/UDP socket address, corresponding to Envoy’s Socket Address https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-socketaddress

Appears in:

FieldTypeRequiredDescription
hostnamestringtrueHostname defines the FQDN hostname of the backend endpoint.
portintegertruePort defines the port of the backend endpoint.

FaultInjection

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

Appears in:

FieldTypeRequiredDescription
delayFaultInjectionDelayfalseIf specified, a delay will be injected into the request.
abortFaultInjectionAbortfalseIf specified, the request will be aborted if it meets the configuration criteria.

FaultInjectionAbort

FaultInjectionAbort defines the abort fault injection configuration

Appears in:

FieldTypeRequiredDescription
httpStatusintegerfalseStatusCode specifies the HTTP status code to be returned
grpcStatusintegerfalseGrpcStatus specifies the GRPC status code to be returned
percentagefloatfalsePercentage specifies the percentage of requests to be aborted. Default 100%, if set 0, no requests will be aborted. Accuracy to 0.0001%.

FaultInjectionDelay

FaultInjectionDelay defines the delay fault injection configuration

Appears in:

FieldTypeRequiredDescription
fixedDelayDurationtrueFixedDelay specifies the fixed delay duration
percentagefloatfalsePercentage specifies the percentage of requests to be delayed. Default 100%, if set 0, no requests will be delayed. Accuracy to 0.0001%.

FileEnvoyProxyAccessLog

Appears in:

FieldTypeRequiredDescription
pathstringtruePath defines the file path used to expose envoy access log(e.g. /dev/stdout).

FilterPosition

FilterPosition defines the position of an Envoy HTTP filter in the filter chain.

Appears in:

FieldTypeRequiredDescription
nameEnvoyFiltertrueName of the filter.
beforeEnvoyFiltertrueBefore defines the filter that should come before the filter.
Only one of Before or After must be set.
afterEnvoyFiltertrueAfter defines the filter that should come after the filter.
Only one of Before or After must be set.

GRPCExtAuthService

GRPCExtAuthService defines the gRPC External Authorization service The authorization request message is defined in https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto

Appears in:

FieldTypeRequiredDescription
backendRefBackendObjectReferencetrueBackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Only Service kind is supported for now.

Deprecated: Use BackendRefs instead.
backendRefsBackendRef arrayfalseBackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Only Service kind is supported for now.

Gateway

Gateway defines the desired Gateway API configuration of Envoy Gateway.

Appears in:

FieldTypeRequiredDescription
controllerNamestringfalseControllerName defines the name of the Gateway API controller. If unspecified,
defaults to “gateway.envoyproxy.io/gatewayclass-controller”. See the following
for additional details:
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GatewayClass

GlobalRateLimit

GlobalRateLimit defines global rate limit configuration.

Appears in:

FieldTypeRequiredDescription
rulesRateLimitRule arraytrueRules are a list of RateLimit selectors and limits. Each rule and its
associated limit is applied in a mutually exclusive way. If a request
matches multiple rules, each of their associated limits get applied, so a
single request might increase the rate limit counters for multiple rules
if selected. The rate limit service will return a logical OR of the individual
rate limit decisions of all matching rules. For example, if a request
matches two rules, one rate limited and one not, the final decision will be
to rate limit the request.

GroupVersionKind

GroupVersionKind unambiguously identifies a Kind. It can be converted to k8s.io/apimachinery/pkg/runtime/schema.GroupVersionKind

Appears in:

FieldTypeRequiredDescription
groupstringtrue
versionstringtrue
kindstringtrue

GzipCompressor

GzipCompressor defines the config for the Gzip compressor. The default values can be found here: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/compression/gzip/compressor/v3/gzip.proto#extension-envoy-compression-gzip-compressor

Appears in:

HTTP10Settings

HTTP10Settings provides HTTP/1.0 configuration on the listener.

Appears in:

FieldTypeRequiredDescription
useDefaultHostbooleanfalseUseDefaultHost defines if the HTTP/1.0 request is missing the Host header,
then the hostname associated with the listener should be injected into the
request.
If this is not set and an HTTP/1.0 request arrives without a host, then
it will be rejected.

HTTP1Settings

HTTP1Settings provides HTTP/1 configuration on the listener.

Appears in:

FieldTypeRequiredDescription
enableTrailersbooleanfalseEnableTrailers defines if HTTP/1 trailers should be proxied by Envoy.
preserveHeaderCasebooleanfalsePreserveHeaderCase defines if Envoy should preserve the letter case of headers.
By default, Envoy will lowercase all the headers.
http10HTTP10SettingsfalseHTTP10 turns on support for HTTP/1.0 and HTTP/0.9 requests.

HTTP2Settings

HTTP2Settings provides HTTP/2 configuration on the listener.

Appears in:

FieldTypeRequiredDescription
initialStreamWindowSizeQuantityfalseInitialStreamWindowSize sets the initial window size for HTTP/2 streams.
If not set, the default value is 64 KiB(64*1024).
initialConnectionWindowSizeQuantityfalseInitialConnectionWindowSize sets the initial window size for HTTP/2 connections.
If not set, the default value is 1 MiB.
maxConcurrentStreamsintegerfalseMaxConcurrentStreams sets the maximum number of concurrent streams allowed per connection.
If not set, the default value is 100.

HTTP3Settings

HTTP3Settings provides HTTP/3 configuration on the listener.

Appears in:

HTTPActiveHealthChecker

HTTPActiveHealthChecker defines the settings of http health check.

Appears in:

FieldTypeRequiredDescription
pathstringtruePath defines the HTTP path that will be requested during health checking.
methodstringfalseMethod defines the HTTP method used for health checking.
Defaults to GET
expectedStatusesHTTPStatus arrayfalseExpectedStatuses defines a list of HTTP response statuses considered healthy.
Defaults to 200 only
expectedResponseActiveHealthCheckPayloadfalseExpectedResponse defines a list of HTTP expected responses to match.

HTTPClientTimeout

Appears in:

FieldTypeRequiredDescription
requestReceivedTimeoutDurationfalseRequestReceivedTimeout is the duration envoy waits for the complete request reception. This timer starts upon request
initiation and stops when either the last byte of the request is sent upstream or when the response begins.
idleTimeoutDurationfalseIdleTimeout for an HTTP connection. Idle time is defined as a period in which there are no active requests in the connection.
Default: 1 hour.

HTTPExtAuthService

HTTPExtAuthService defines the HTTP External Authorization service

Appears in:

FieldTypeRequiredDescription
backendRefBackendObjectReferencetrueBackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Only Service kind is supported for now.

Deprecated: Use BackendRefs instead.
backendRefsBackendRef arrayfalseBackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Only Service kind is supported for now.
pathstringtruePath is the path of the HTTP External Authorization service.
If path is specified, the authorization request will be sent to that path,
or else the authorization request will be sent to the root path.
headersToBackendstring arrayfalseHeadersToBackend are the authorization response headers that will be added
to the original client request before sending it to the backend server.
Note that coexisting headers will be overridden.
If not specified, no authorization response headers will be added to the
original client request.

HTTPStatus

Underlying type: integer

HTTPStatus defines the http status code.

Appears in:

HTTPTimeout

Appears in:

FieldTypeRequiredDescription
connectionIdleTimeoutDurationfalseThe idle timeout for an HTTP connection. Idle time is defined as a period in which there are no active requests in the connection.
Default: 1 hour.
maxConnectionDurationDurationfalseThe maximum duration of an HTTP connection.
Default: unlimited.

HTTPWasmCodeSource

HTTPWasmCodeSource defines the HTTP URL containing the Wasm code.

Appears in:

FieldTypeRequiredDescription
urlstringtrueURL is the URL containing the Wasm code.
sha256stringfalseSHA256 checksum that will be used to verify the Wasm code.

If not specified, Envoy Gateway will not verify the downloaded Wasm code.
kubebuilder:validation:Pattern=^[a-f0-9]{64}$

Header defines the header hashing configuration for consistent hash based load balancing.

Appears in:

FieldTypeRequiredDescription
namestringtrueName of the header to hash.

HeaderMatchType

Underlying type: string

HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values are “Exact”, “RegularExpression”, and “Distinct”.

Appears in:

ValueDescription
ExactHeaderMatchExact matches the exact value of the Value field against the value of
the specified HTTP Header.
RegularExpressionHeaderMatchRegularExpression matches a regular expression against the value of the
specified HTTP Header. The regex string must adhere to the syntax documented in
https://github.com/google/re2/wiki/Syntax.
DistinctHeaderMatchDistinct matches any and all possible unique values encountered in the
specified HTTP Header. Note that each unique value will receive its own rate limit
bucket.
Note: This is only supported for Global Rate Limits.

HeaderSettings

HeaderSettings provides configuration options for headers on the listener.

Appears in:

FieldTypeRequiredDescription
enableEnvoyHeadersbooleanfalseEnableEnvoyHeaders configures Envoy Proxy to add the “X-Envoy-” headers to requests
and responses.
disableRateLimitHeadersbooleanfalseDisableRateLimitHeaders configures Envoy Proxy to omit the “X-RateLimit-” response headers
when rate limiting is enabled.
xForwardedClientCertXForwardedClientCertfalseXForwardedClientCert configures how Envoy Proxy handle the x-forwarded-client-cert (XFCC) HTTP header.

x-forwarded-client-cert (XFCC) is an HTTP header used to forward the certificate
information of part or all of the clients or proxies that a request has flowed through,
on its way from the client to the server.

Envoy proxy may choose to sanitize/append/forward the XFCC header before proxying the request.

If not set, the default behavior is sanitizing the XFCC header.
withUnderscoresActionWithUnderscoresActionfalseWithUnderscoresAction configures the action to take when an HTTP header with underscores
is encountered. The default action is to reject the request.
preserveXRequestIDbooleanfalsePreserveXRequestID configures Envoy to 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.
It defaults to false.

HealthCheck

HealthCheck configuration to decide which endpoints are healthy and can be used for routing.

Appears in:

FieldTypeRequiredDescription
activeActiveHealthCheckfalseActive health check configuration
passivePassiveHealthCheckfalsePassive passive check configuration

HealthCheckSettings

HealthCheckSettings provides HealthCheck configuration on the HTTP/HTTPS listener.

Appears in:

FieldTypeRequiredDescription
pathstringtruePath specifies the HTTP path to match on for health check requests.

IPEndpoint

IPEndpoint describes TCP/UDP socket address, corresponding to Envoy’s Socket Address https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-socketaddress

Appears in:

FieldTypeRequiredDescription
addressstringtrueAddress defines the IP address of the backend endpoint.
portintegertruePort defines the port of the backend endpoint.

ImagePullPolicy

Underlying type: string

ImagePullPolicy defines the policy to use when pulling an OIC image.

Appears in:

ValueDescription
IfNotPresentImagePullPolicyIfNotPresent will only pull the image if it does not already exist in the EG cache.
AlwaysImagePullPolicyAlways will pull the image when the EnvoyExtension resource version changes.
Note: EG does not update the Wasm module every time an Envoy proxy requests the Wasm module.

ImageWasmCodeSource

ImageWasmCodeSource defines the OCI image containing the Wasm code.

Appears in:

FieldTypeRequiredDescription
urlstringtrueURL is the URL of the OCI image.
URL can be in the format of registry/image:tag or registry/image@sha256:digest.
sha256stringfalseSHA256 checksum that will be used to verify the OCI image.

It must match the digest of the OCI image.

If not specified, Envoy Gateway will not verify the downloaded OCI image.
kubebuilder:validation:Pattern=^[a-f0-9]{64}$
pullSecretRefSecretObjectReferencefalsePullSecretRef is a reference to the secret containing the credentials to pull the image.
Only support Kubernetes Secret resource from the same namespace.

InfrastructureProviderType

Underlying type: string

InfrastructureProviderType defines the types of custom infrastructure providers supported by Envoy Gateway.

Appears in:

ValueDescription
HostInfrastructureProviderTypeHost defines the “Host” provider.

JSONPatchOperation

JSONPatchOperation defines the JSON Patch Operation as defined in https://datatracker.ietf.org/doc/html/rfc6902

Appears in:

FieldTypeRequiredDescription
opJSONPatchOperationTypetrueOp is the type of operation to perform
pathstringtruePath is the location of the target document/field where the operation will be performed
Refer to https://datatracker.ietf.org/doc/html/rfc6901 for more details.
fromstringfalseFrom is the source location of the value to be copied or moved. Only valid
for move or copy operations
Refer to https://datatracker.ietf.org/doc/html/rfc6901 for more details.
valueJSONfalseValue is the new value of the path location. The value is only used by
the add and replace operations.

JSONPatchOperationType

Underlying type: string

JSONPatchOperationType specifies the JSON Patch operations that can be performed.

Appears in:

JWT

JWT defines the configuration for JSON Web Token (JWT) authentication.

Appears in:

FieldTypeRequiredDescription
optionalbooleantrueOptional determines whether a missing JWT is acceptable, defaulting to false if not specified.
Note: Even if optional is set to true, JWT authentication will still fail if an invalid JWT is presented.
providersJWTProvider arraytrueProviders defines the JSON Web Token (JWT) authentication provider type.
When multiple JWT providers are specified, the JWT is considered valid if
any of the providers successfully validate the JWT. For additional details,
see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html.

JWTExtractor

JWTExtractor defines a custom JWT token extraction from HTTP request. If specified, Envoy will extract the JWT token from the listed extractors (headers, cookies, or params) and validate each of them. If any value extracted is found to be an invalid JWT, a 401 error will be returned.

Appears in:

FieldTypeRequiredDescription
headersJWTHeaderExtractor arrayfalseHeaders represents a list of HTTP request headers to extract the JWT token from.
cookiesstring arrayfalseCookies represents a list of cookie names to extract the JWT token from.
paramsstring arrayfalseParams represents a list of query parameters to extract the JWT token from.

JWTHeaderExtractor

JWTHeaderExtractor defines an HTTP header location to extract JWT token

Appears in:

FieldTypeRequiredDescription
namestringtrueName is the HTTP header name to retrieve the token
valuePrefixstringfalseValuePrefix is the prefix that should be stripped before extracting the token.
The format would be used by Envoy like “{ValuePrefix}”.
For example, “Authorization: Bearer ”, then the ValuePrefix=“Bearer " with a space at the end.

JWTProvider

JWTProvider defines how a JSON Web Token (JWT) can be verified.

Appears in:

FieldTypeRequiredDescription
namestringtrueName defines a unique name for the JWT provider. A name can have a variety of forms,
including RFC1123 subdomains, RFC 1123 labels, or RFC 1035 labels.
issuerstringfalseIssuer is the principal that issued the JWT and takes the form of a URL or email address.
For additional details, see https://tools.ietf.org/html/rfc7519#section-4.1.1 for
URL format and https://rfc-editor.org/rfc/rfc5322.html for email format. If not provided,
the JWT issuer is not checked.
audiencesstring arrayfalseAudiences is a list of JWT audiences allowed access. For additional details, see
https://tools.ietf.org/html/rfc7519#section-4.1.3. If not provided, JWT audiences
are not checked.
remoteJWKSRemoteJWKStrueRemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote
HTTP/HTTPS endpoint.
claimToHeadersClaimToHeader arrayfalseClaimToHeaders is a list of JWT claims that must be extracted into HTTP request headers
For examples, following config:
The claim must be of type; string, int, double, bool. Array type claims are not supported
recomputeRoutebooleanfalseRecomputeRoute clears the route cache and recalculates the routing decision.
This field must be enabled if the headers generated from the claim are used for
route matching decisions. If the recomputation selects a new route, features targeting
the new matched route will be applied.
extractFromJWTExtractorfalseExtractFrom defines different ways to extract the JWT token from HTTP request.
If empty, it defaults to extract JWT token from the Authorization HTTP request header using Bearer schema
or access_token from query parameters.

KubernetesContainerSpec

KubernetesContainerSpec defines the desired state of the Kubernetes container resource.

Appears in:

FieldTypeRequiredDescription
envEnvVar arrayfalseList of environment variables to set in the container.
resourcesResourceRequirementsfalseResources required by this container.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
securityContextSecurityContextfalseSecurityContext defines the security options the container should be run with.
If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext.
More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
imagestringfalseImage specifies the EnvoyProxy container image to be used, instead of the default image.
volumeMountsVolumeMount arrayfalseVolumeMounts are volumes to mount into the container’s filesystem.
Cannot be updated.

KubernetesDaemonSetSpec

KubernetesDaemonsetSpec defines the desired state of the Kubernetes daemonset resource.

Appears in:

FieldTypeRequiredDescription
patchKubernetesPatchSpecfalsePatch defines how to perform the patch operation to daemonset
strategyDaemonSetUpdateStrategyfalseThe daemonset strategy to use to replace existing pods with new ones.
podKubernetesPodSpecfalsePod defines the desired specification of pod.
containerKubernetesContainerSpecfalseContainer defines the desired specification of main container.
namestringfalseName of the daemonSet.
When unset, this defaults to an autogenerated name.

KubernetesDeployMode

KubernetesDeployMode holds configuration for how to deploy managed resources such as the Envoy Proxy data plane fleet.

Appears in:

KubernetesDeploymentSpec

KubernetesDeploymentSpec defines the desired state of the Kubernetes deployment resource.

Appears in:

FieldTypeRequiredDescription
patchKubernetesPatchSpecfalsePatch defines how to perform the patch operation to deployment
replicasintegerfalseReplicas is the number of desired pods. Defaults to 1.
strategyDeploymentStrategyfalseThe deployment strategy to use to replace existing pods with new ones.
podKubernetesPodSpecfalsePod defines the desired specification of pod.
containerKubernetesContainerSpecfalseContainer defines the desired specification of main container.
initContainersContainer arrayfalseList of initialization containers belonging to the pod.
More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
namestringfalseName of the deployment.
When unset, this defaults to an autogenerated name.

KubernetesHorizontalPodAutoscalerSpec

KubernetesHorizontalPodAutoscalerSpec defines Kubernetes Horizontal Pod Autoscaler settings of Envoy Proxy Deployment. When HPA is enabled, it is recommended that the value in KubernetesDeploymentSpec.replicas be removed, otherwise Envoy Gateway will revert back to this value every time reconciliation occurs. See k8s.io.autoscaling.v2.HorizontalPodAutoScalerSpec.

Appears in:

FieldTypeRequiredDescription
minReplicasintegerfalseminReplicas is the lower limit for the number of replicas to which the autoscaler
can scale down. It defaults to 1 replica.
maxReplicasintegertruemaxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up.
It cannot be less that minReplicas.
metricsMetricSpec arrayfalsemetrics contains the specifications for which to use to calculate the
desired replica count (the maximum replica count across all metrics will
be used).
If left empty, it defaults to being based on CPU utilization with average on 80% usage.
behaviorHorizontalPodAutoscalerBehaviorfalsebehavior configures the scaling behavior of the target
in both Up and Down directions (scaleUp and scaleDown fields respectively).
If not set, the default HPAScalingRules for scale up and scale down are used.
See k8s.io.autoscaling.v2.HorizontalPodAutoScalerBehavior.

KubernetesPatchSpec

KubernetesPatchSpec defines how to perform the patch operation

Appears in:

FieldTypeRequiredDescription
typeMergeTypefalseType is the type of merge operation to perform

By default, StrategicMerge is used as the patch type.
valueJSONtrueObject contains the raw configuration for merged object

KubernetesPodDisruptionBudgetSpec

KubernetesPodDisruptionBudgetSpec defines Kubernetes PodDisruptionBudget settings of Envoy Proxy Deployment.

Appears in:

FieldTypeRequiredDescription
minAvailableintegerfalseMinAvailable specifies the minimum number of pods that must be available at all times during voluntary disruptions,
such as node drains or updates. This setting ensures that your envoy proxy maintains a certain level of availability
and resilience during maintenance operations.

KubernetesPodSpec

KubernetesPodSpec defines the desired state of the Kubernetes pod resource.

Appears in:

FieldTypeRequiredDescription
annotationsobject (keys:string, values:string)falseAnnotations are the annotations that should be appended to the pods.
By default, no pod annotations are appended.
labelsobject (keys:string, values:string)falseLabels are the additional labels that should be tagged to the pods.
By default, no additional pod labels are tagged.
securityContextPodSecurityContextfalseSecurityContext holds pod-level security attributes and common container settings.
Optional: Defaults to empty. See type description for default values of each field.
affinityAffinityfalseIf specified, the pod’s scheduling constraints.
tolerationsToleration arrayfalseIf specified, the pod’s tolerations.
volumesVolume arrayfalseVolumes that can be mounted by containers belonging to the pod.
More info: https://kubernetes.io/docs/concepts/storage/volumes
imagePullSecretsLocalObjectReference arrayfalseImagePullSecrets is an optional list of references to secrets
in the same namespace to use for pulling any of the images used by this PodSpec.
If specified, these secrets will be passed to individual puller implementations for them to use.
More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod
nodeSelectorobject (keys:string, values:string)falseNodeSelector is a selector which must be true for the pod to fit on a node.
Selector which must match a node’s labels for the pod to be scheduled on that node.
More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
topologySpreadConstraintsTopologySpreadConstraint arrayfalseTopologySpreadConstraints describes how a group of pods ought to spread across topology
domains. Scheduler will schedule pods in a way which abides by the constraints.
All topologySpreadConstraints are ANDed.

KubernetesServiceSpec

KubernetesServiceSpec defines the desired state of the Kubernetes service resource.

Appears in:

FieldTypeRequiredDescription
annotationsobject (keys:string, values:string)falseAnnotations that should be appended to the service.
By default, no annotations are appended.
typeServiceTypefalseType determines how the Service is exposed. Defaults to LoadBalancer.
Valid options are ClusterIP, LoadBalancer and NodePort.
“LoadBalancer” means a service will be exposed via an external load balancer (if the cloud provider supports it).
“ClusterIP” means a service will only be accessible inside the cluster, via the cluster IP.
“NodePort” means a service will be exposed on a static Port on all Nodes of the cluster.
loadBalancerClassstringfalseLoadBalancerClass, when specified, allows for choosing the LoadBalancer provider
implementation if more than one are available or is otherwise expected to be specified
allocateLoadBalancerNodePortsbooleanfalseAllocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for
services with type LoadBalancer. Default is “true”. It may be set to “false” if the cluster
load-balancer does not rely on NodePorts. If the caller requests specific NodePorts (by specifying a
value), those requests will be respected, regardless of this field. This field may only be set for
services with type LoadBalancer and will be cleared if the type is changed to any other type.
loadBalancerSourceRangesstring arrayfalseLoadBalancerSourceRanges defines a list of allowed IP addresses which will be configured as
firewall rules on the platform providers load balancer. This is not guaranteed to be working as
it happens outside of kubernetes and has to be supported and handled by the platform provider.
This field may only be set for services with type LoadBalancer and will be cleared if the type
is changed to any other type.
loadBalancerIPstringfalseLoadBalancerIP defines the IP Address of the underlying load balancer service. This field
may be ignored if the load balancer provider does not support this feature.
This field has been deprecated in Kubernetes, but it is still used for setting the IP Address in some cloud
providers such as GCP.
externalTrafficPolicyServiceExternalTrafficPolicyfalseExternalTrafficPolicy determines the externalTrafficPolicy for the Envoy Service. Valid options
are Local and Cluster. Default is “Local”. “Local” means traffic will only go to pods on the node
receiving the traffic. “Cluster” means connections are loadbalanced to all pods in the cluster.
patchKubernetesPatchSpecfalsePatch defines how to perform the patch operation to the service
namestringfalseName of the service.
When unset, this defaults to an autogenerated name.

KubernetesWatchMode

KubernetesWatchMode holds the configuration for which input resources to watch and reconcile.

Appears in:

FieldTypeRequiredDescription
typeKubernetesWatchModeTypetrueType indicates what watch mode to use. KubernetesWatchModeTypeNamespaces and
KubernetesWatchModeTypeNamespaceSelector are currently supported
By default, when this field is unset or empty, Envoy Gateway will watch for input namespaced resources
from all namespaces.
namespacesstring arraytrueNamespaces holds the list of namespaces that Envoy Gateway will watch for namespaced scoped
resources such as Gateway, HTTPRoute and Service.
Note that Envoy Gateway will continue to reconcile relevant cluster scoped resources such as
GatewayClass that it is linked to. Precisely one of Namespaces and NamespaceSelector must be set.
namespaceSelectorLabelSelectortrueNamespaceSelector holds the label selector used to dynamically select namespaces.
Envoy Gateway will watch for namespaces matching the specified label selector.
Precisely one of Namespaces and NamespaceSelector must be set.

KubernetesWatchModeType

Underlying type: string

KubernetesWatchModeType defines the type of KubernetesWatchMode

Appears in:

LeaderElection

LeaderElection defines the desired leader election settings.

Appears in:

FieldTypeRequiredDescription
leaseDurationDurationtrueLeaseDuration defines the time non-leader contenders will wait before attempting to claim leadership.
It’s based on the timestamp of the last acknowledged signal. The default setting is 15 seconds.
renewDeadlineDurationtrueRenewDeadline represents the time frame within which the current leader will attempt to renew its leadership
status before relinquishing its position. The default setting is 10 seconds.
retryPeriodDurationtrueRetryPeriod denotes the interval at which LeaderElector clients should perform action retries.
The default setting is 2 seconds.
disablebooleantrueDisable provides the option to turn off leader election, which is enabled by default.

LiteralCustomTag

LiteralCustomTag adds hard-coded value to each span.

Appears in:

FieldTypeRequiredDescription
valuestringtrueValue defines the hard-coded value to add to each span.

LoadBalancer

LoadBalancer defines the load balancer policy to be applied.

Appears in:

FieldTypeRequiredDescription
typeLoadBalancerTypetrueType decides the type of Load Balancer policy.
Valid LoadBalancerType values are
“ConsistentHash”,
“LeastRequest”,
“Random”,
“RoundRobin”.
consistentHashConsistentHashfalseConsistentHash defines the configuration when the load balancer type is
set to ConsistentHash
slowStartSlowStartfalseSlowStart defines the configuration related to the slow start load balancer policy.
If set, during slow start window, traffic sent to the newly added hosts will gradually increase.
Currently this is only supported for RoundRobin and LeastRequest load balancers

LoadBalancerType

Underlying type: string

LoadBalancerType specifies the types of LoadBalancer.

Appears in:

ValueDescription
ConsistentHashConsistentHashLoadBalancerType load balancer policy.
LeastRequestLeastRequestLoadBalancerType load balancer policy.
RandomRandomLoadBalancerType load balancer policy.
RoundRobinRoundRobinLoadBalancerType load balancer policy.

LocalRateLimit

LocalRateLimit defines local rate limit configuration.

Appears in:

FieldTypeRequiredDescription
rulesRateLimitRule arrayfalseRules are a list of RateLimit selectors and limits. If a request matches
multiple rules, the strictest limit is applied. For example, if a request
matches two rules, one with 10rps and one with 20rps, the final limit will
be based on the rule with 10rps.

LogLevel

Underlying type: string

LogLevel defines a log level for Envoy Gateway and EnvoyProxy system logs.

Appears in:

ValueDescription
debugLogLevelDebug defines the “debug” logging level.
infoLogLevelInfo defines the “Info” logging level.
warnLogLevelWarn defines the “Warn” logging level.
errorLogLevelError defines the “Error” logging level.

MetricSinkType

Underlying type: string

Appears in:

ValueDescription
OpenTelemetry

OIDC

OIDC defines the configuration for the OpenID Connect (OIDC) authentication.

Appears in:

FieldTypeRequiredDescription
providerOIDCProvidertrueThe OIDC Provider configuration.
clientIDstringtrueThe client ID to be used in the OIDC
Authentication Request.
clientSecretSecretObjectReferencetrueThe Kubernetes secret which contains the OIDC client secret to be used in the
Authentication Request.

This is an Opaque secret. The client secret should be stored in the key
“client-secret”.
cookieNamesOIDCCookieNamesfalseThe optional cookie name overrides to be used for Bearer and IdToken cookies in the
Authentication Request.
If not specified, uses a randomly generated suffix
scopesstring arrayfalseThe OIDC scopes to be used in the
Authentication Request.
The “openid” scope is always added to the list of scopes if not already
specified.
resourcesstring arrayfalseThe OIDC resources to be used in the
Authentication Request.
redirectURLstringtrueThe redirect URL to be used in the OIDC
Authentication Request.
If not specified, uses the default redirect URI “%REQ(x-forwarded-proto)%://%REQ(:authority)%/oauth2/callback”
logoutPathstringtrueThe path to log a user out, clearing their credential cookies.

If not specified, uses a default logout path “/logout”
forwardAccessTokenbooleanfalseForwardAccessToken indicates whether the Envoy should forward the access token
via the Authorization header Bearer scheme to the upstream.
If not specified, defaults to false.
defaultTokenTTLDurationfalseDefaultTokenTTL is the default lifetime of the id token and access token.
Please note that Envoy will always use the expiry time from the response
of the authorization server if it is provided. This field is only used when
the expiry time is not provided by the authorization.

If not specified, defaults to 0. In this case, the “expires_in” field in
the authorization response must be set by the authorization server, or the
OAuth flow will fail.
refreshTokenbooleanfalseRefreshToken indicates whether the Envoy should automatically refresh the
id token and access token when they expire.
When set to true, the Envoy will use the refresh token to get a new id token
and access token when they expire.

If not specified, defaults to false.
defaultRefreshTokenTTLDurationfalseDefaultRefreshTokenTTL is the default lifetime of the refresh token.
This field is only used when the exp (expiration time) claim is omitted in
the refresh token or the refresh token is not JWT.

If not specified, defaults to 604800s (one week).
Note: this field is only applicable when the “refreshToken” field is set to true.

OIDCCookieNames

OIDCCookieNames defines the names of cookies to use in the Envoy OIDC filter.

Appears in:

FieldTypeRequiredDescription
accessTokenstringfalseThe name of the cookie used to store the AccessToken in the
Authentication Request.
If not specified, defaults to “AccessToken-(randomly generated uid)”
idTokenstringfalseThe name of the cookie used to store the IdToken in the
Authentication Request.
If not specified, defaults to “IdToken-(randomly generated uid)”

OIDCProvider

OIDCProvider defines the OIDC Provider configuration.

Appears in:

FieldTypeRequiredDescription
issuerstringtrueThe OIDC Provider’s issuer identifier.
Issuer MUST be a URI RFC 3986 [RFC3986] with a scheme component that MUST
be https, a host component, and optionally, port and path components and
no query or fragment components.
authorizationEndpointstringfalseThe OIDC Provider’s authorization endpoint.
If not provided, EG will try to discover it from the provider’s Well-Known Configuration Endpoint.
tokenEndpointstringfalseThe OIDC Provider’s token endpoint.
If not provided, EG will try to discover it from the provider’s Well-Known Configuration Endpoint.

OpenTelemetryEnvoyProxyAccessLog

OpenTelemetryEnvoyProxyAccessLog defines the OpenTelemetry access log sink.

Appears in:

FieldTypeRequiredDescription
hoststringfalseHost define the extension service hostname.
Deprecated: Use BackendRefs instead.
portintegerfalsePort defines the port the extension service is exposed on.
Deprecated: Use BackendRefs instead.
backendRefsBackendRef arrayfalseBackendRefs references a Kubernetes object that represents the
backend server to which the access log will be sent.
Only Service kind is supported for now.
resourcesobject (keys:string, values:string)falseResources is a set of labels that describe the source of a log entry, including envoy node info.
It’s recommended to follow semantic conventions.

Origin

Underlying type: string

Origin is defined by the scheme (protocol), hostname (domain), and port of the URL used to access it. The hostname can be “precise” which is just the domain name or “wildcard” which is a domain name prefixed with a single wildcard label such as “*.example.com”. In addition to that a single wildcard (with or without scheme) can be configured to match any origin.

For example, the following are valid origins:

Appears in:

PassiveHealthCheck

PassiveHealthCheck defines the configuration for passive health checks in the context of Envoy’s Outlier Detection, see https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/outlier

Appears in:

FieldTypeRequiredDescription
splitExternalLocalOriginErrorsbooleanfalseSplitExternalLocalOriginErrors enables splitting of errors between external and local origin.
intervalDurationfalseInterval defines the time between passive health checks.
consecutiveLocalOriginFailuresintegerfalseConsecutiveLocalOriginFailures sets the number of consecutive local origin failures triggering ejection.
Parameter takes effect only when split_external_local_origin_errors is set to true.
consecutiveGatewayErrorsintegerfalseConsecutiveGatewayErrors sets the number of consecutive gateway errors triggering ejection.
consecutive5XxErrorsintegerfalseConsecutive5xxErrors sets the number of consecutive 5xx errors triggering ejection.
baseEjectionTimeDurationfalseBaseEjectionTime defines the base duration for which a host will be ejected on consecutive failures.
maxEjectionPercentintegerfalseMaxEjectionPercent sets the maximum percentage of hosts in a cluster that can be ejected.

PathEscapedSlashAction

Underlying type: string

PathEscapedSlashAction determines the action for requests that contain %2F, %2f, %5C, or %5c sequences in the URI path.

Appears in:

ValueDescription
KeepUnchangedKeepUnchangedAction keeps escaped slashes as they arrive without changes
RejectRequestRejectRequestAction rejects client requests containing escaped slashes
with a 400 status. gRPC requests will be rejected with the INTERNAL (13)
error code.
The “httpN.downstream_rq_failed_path_normalization” counter is incremented
for each rejected request.
UnescapeAndRedirectUnescapeAndRedirect unescapes %2F and %5C sequences and redirects to the new path
if these sequences were present.
Redirect occurs after path normalization and merge slashes transformations if
they were configured. gRPC requests will be rejected with the INTERNAL (13)
error code.
This option minimizes possibility of path confusion exploits by forcing request
with unescaped slashes to traverse all parties: downstream client, intermediate
proxies, Envoy and upstream server.
The “httpN.downstream_rq_redirected_with_normalized_path” counter is incremented
for each redirected request.
UnescapeAndForwardUnescapeAndForward unescapes %2F and %5C sequences and forwards the request.
Note: this option should not be enabled if intermediaries perform path based access
control as it may lead to path confusion vulnerabilities.

PathSettings

PathSettings provides settings that managing how the incoming path set by clients is handled.

Appears in:

FieldTypeRequiredDescription
escapedSlashesActionPathEscapedSlashActionfalseEscapedSlashesAction determines how %2f, %2F, %5c, or %5C sequences in the path URI
should be handled.
The default is UnescapeAndRedirect.
disableMergeSlashesbooleanfalseDisableMergeSlashes allows disabling the default configuration of merging adjacent
slashes in the path.
Note that slash merging is not part of the HTTP spec and is provided for convenience.

PerRetryPolicy

Appears in:

FieldTypeRequiredDescription
timeoutDurationfalseTimeout is the timeout per retry attempt.
backOffBackOffPolicyfalseBackoff is the backoff policy to be applied per retry attempt. gateway uses a fully jittered exponential
back-off algorithm for retries. For additional details,
see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-max-retries

PolicyTargetReferences

Appears in:

FieldTypeRequiredDescription
targetRefLocalPolicyTargetReferenceWithSectionNametrueTargetRef 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
targetRefsLocalPolicyTargetReferenceWithSectionName arraytrueTargetRefs are the names of the Gateway resources this policy
is being attached to.
targetSelectorsTargetSelector arraytrueTargetSelectors allow targeting resources for this policy based on labels

Principal

Principal specifies the client identity of a request. A client identity can be a client IP, a JWT claim, username from the Authorization header, or any other identity that can be extracted from a custom header. Currently, only the client IP is supported.

Appears in:

FieldTypeRequiredDescription
clientCIDRsCIDR arraytrueClientCIDRs are the IP CIDR ranges of the client.
Valid examples are “192.168.1.0/24” or “2001:db8::/64”

The client IP is inferred from the X-Forwarded-For header, a custom header,
or the proxy protocol.
You can use the ClientIPDetection or the EnableProxyProtocol field in
the ClientTrafficPolicy to configure how the client IP is detected.

ProcessingModeOptions

ProcessingModeOptions defines if headers or body should be processed by the external service

Appears in:

FieldTypeRequiredDescription
bodyExtProcBodyProcessingModefalseDefines body processing mode

ProviderType

Underlying type: string

ProviderType defines the types of providers supported by Envoy Gateway.

Appears in:

ValueDescription
KubernetesProviderTypeKubernetes defines the “Kubernetes” provider.
FileProviderTypeFile defines the “File” provider. This type is not implemented
until https://github.com/envoyproxy/gateway/issues/1001 is fixed.

ProxyAccessLog

Appears in:

FieldTypeRequiredDescription
disablebooleantrueDisable disables access logging for managed proxies if set to true.
settingsProxyAccessLogSetting arrayfalseSettings defines accesslog settings for managed proxies.
If unspecified, will send default format to stdout.

ProxyAccessLogFormat

ProxyAccessLogFormat defines the format of accesslog. By default accesslogs are written to standard output.

Appears in:

FieldTypeRequiredDescription
typeProxyAccessLogFormatTypetrueType defines the type of accesslog format.
textstringfalseText defines the text accesslog format, following Envoy accesslog formatting,
It’s required when the format type is “Text”.
Envoy command operators may be used in the format.
The format string documentation provides more information.
jsonobject (keys:string, values:string)falseJSON is additional attributes that describe the specific event occurrence.
Structured format for the envoy access logs. Envoy command operators
can be used as values for fields within the Struct.
It’s required when the format type is “JSON”.

ProxyAccessLogFormatType

Underlying type: string

Appears in:

ValueDescription
TextProxyAccessLogFormatTypeText defines the text accesslog format.
JSONProxyAccessLogFormatTypeJSON defines the JSON accesslog format.

ProxyAccessLogSetting

Appears in:

FieldTypeRequiredDescription
formatProxyAccessLogFormatfalseFormat defines the format of accesslog.
This will be ignored if sink type is ALS.
matchesstring arraytrueMatches defines the match conditions for accesslog in CEL expression.
An accesslog will be emitted only when one or more match conditions are evaluated to true.
Invalid CEL expressions will be ignored.
sinksProxyAccessLogSink arraytrueSinks defines the sinks of accesslog.

ProxyAccessLogSink

ProxyAccessLogSink defines the sink of accesslog.

Appears in:

FieldTypeRequiredDescription
typeProxyAccessLogSinkTypetrueType defines the type of accesslog sink.
alsALSEnvoyProxyAccessLogfalseALS defines the gRPC Access Log Service (ALS) sink.
fileFileEnvoyProxyAccessLogfalseFile defines the file accesslog sink.
openTelemetryOpenTelemetryEnvoyProxyAccessLogfalseOpenTelemetry defines the OpenTelemetry accesslog sink.

ProxyAccessLogSinkType

Underlying type: string

Appears in:

ValueDescription
ALSProxyAccessLogSinkTypeALS 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
FileProxyAccessLogSinkTypeFile defines the file accesslog sink.
OpenTelemetryProxyAccessLogSinkTypeOpenTelemetry defines the OpenTelemetry accesslog sink.
When the provider is Kubernetes, EnvoyGateway always sends k8s.namespace.name
and k8s.pod.name as additional attributes.

ProxyBootstrap

ProxyBootstrap defines Envoy Bootstrap configuration.

Appears in:

FieldTypeRequiredDescription
typeBootstrapTypefalseType is the type of the bootstrap configuration, it should be either Replace or Merge.
If unspecified, it defaults to Replace.
valuestringtrueValue is a YAML string of the bootstrap.

ProxyLogComponent

Underlying type: string

ProxyLogComponent defines a component that supports a configured logging level.

Appears in:

ValueDescription
defaultLogComponentDefault defines the default logging component.
See more details: https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-l
upstreamLogComponentUpstream defines the “upstream” logging component.
httpLogComponentHTTP defines the “http” logging component.
connectionLogComponentConnection defines the “connection” logging component.
adminLogComponentAdmin defines the “admin” logging component.
clientLogComponentClient defines the “client” logging component.
filterLogComponentFilter defines the “filter” logging component.
mainLogComponentMain defines the “main” logging component.
routerLogComponentRouter defines the “router” logging component.
runtimeLogComponentRuntime defines the “runtime” logging component.

ProxyLogging

ProxyLogging defines logging parameters for managed proxies.

Appears in:

FieldTypeRequiredDescription
levelobject (keys:ProxyLogComponent, values:LogLevel)trueLevel is a map of logging level per component, where the component is the key
and the log level is the value. If unspecified, defaults to “default: warn”.

ProxyMetricSink

ProxyMetricSink defines the sink of metrics. Default metrics sink is OpenTelemetry.

Appears in:

FieldTypeRequiredDescription
typeMetricSinkTypetrueType defines the metric sink type.
EG currently only supports OpenTelemetry.
openTelemetryProxyOpenTelemetrySinkfalseOpenTelemetry defines the configuration for OpenTelemetry sink.
It’s required if the sink type is OpenTelemetry.

ProxyMetrics

Appears in:

FieldTypeRequiredDescription
prometheusProxyPrometheusProvidertruePrometheus defines the configuration for Admin endpoint /stats/prometheus.
sinksProxyMetricSink arraytrueSinks defines the metric sinks where metrics are sent to.
matchesStringMatch arraytrueMatches defines configuration for selecting specific metrics instead of generating all metrics stats
that are enabled by default. This helps reduce CPU and memory overhead in Envoy, but eliminating some stats
may after critical functionality. Here are the stats that we strongly recommend not disabling:
cluster_manager.warming_clusters, cluster.<cluster_name>.membership_total,cluster.<cluster_name>.membership_healthy,
cluster.<cluster_name>.membership_degraded,reference https://github.com/envoyproxy/envoy/issues/9856,
https://github.com/envoyproxy/envoy/issues/14610
enableVirtualHostStatsbooleantrueEnableVirtualHostStats enables envoy stat metrics for virtual hosts.
enablePerEndpointStatsbooleantrueEnablePerEndpointStats enables per endpoint envoy stats metrics.
Please use with caution.

ProxyOpenTelemetrySink

ProxyOpenTelemetrySink defines the configuration for OpenTelemetry sink.

Appears in:

FieldTypeRequiredDescription
hoststringfalseHost define the service hostname.
Deprecated: Use BackendRefs instead.
portintegerfalsePort defines the port the service is exposed on.
Deprecated: Use BackendRefs instead.
backendRefsBackendRef arrayfalseBackendRefs references a Kubernetes object that represents the
backend server to which the metric will be sent.
Only Service kind is supported for now.

ProxyPrometheusProvider

Appears in:

FieldTypeRequiredDescription
disablebooleantrueDisable the Prometheus endpoint.
compressionCompressionfalseConfigure the compression on Prometheus endpoint. Compression is useful in situations when bandwidth is scarce and large payloads can be effectively compressed at the expense of higher CPU load.

ProxyProtocol

ProxyProtocol defines the configuration related to the proxy protocol when communicating with the backend.

Appears in:

FieldTypeRequiredDescription
versionProxyProtocolVersiontrueVersion of ProxyProtol
Valid ProxyProtocolVersion values are
“V1”
“V2”

ProxyProtocolVersion

Underlying type: string

ProxyProtocolVersion defines the version of the Proxy Protocol to use.

Appears in:

ValueDescription
V1ProxyProtocolVersionV1 is the PROXY protocol version 1 (human readable format).
V2ProxyProtocolVersionV2 is the PROXY protocol version 2 (binary format).

ProxyTelemetry

Appears in:

FieldTypeRequiredDescription
accessLogProxyAccessLogfalseAccessLogs defines accesslog parameters for managed proxies.
If unspecified, will send default format to stdout.
tracingProxyTracingfalseTracing defines tracing configuration for managed proxies.
If unspecified, will not send tracing data.
metricsProxyMetricstrueMetrics defines metrics configuration for managed proxies.

ProxyTracing

Appears in:

FieldTypeRequiredDescription
samplingRateintegerfalseSamplingRate controls the rate at which traffic will be
selected for tracing if no prior sampling decision has been made.
Defaults to 100, valid values [0-100]. 100 indicates 100% sampling.
customTagsobject (keys:string, values:CustomTag)trueCustomTags defines the custom tags to add to each span.
If provider is kubernetes, pod name and namespace are added by default.
providerTracingProvidertrueProvider defines the tracing provider.

RateLimit

RateLimit defines the configuration associated with the Rate Limit Service used for Global Rate Limiting.

Appears in:

FieldTypeRequiredDescription
backendRateLimitDatabaseBackendtrueBackend holds the configuration associated with the
database backend used by the rate limit service to store
state associated with global ratelimiting.
timeoutDurationfalseTimeout specifies the timeout period for the proxy to access the ratelimit server
If not set, timeout is 20ms.
failClosedbooleantrueFailClosed is a switch used to control the flow of traffic
when the response from the ratelimit server cannot be obtained.
If FailClosed is false, let the traffic pass,
otherwise, don’t let the traffic pass and return 500.
If not set, FailClosed is False.
telemetryRateLimitTelemetryfalseTelemetry defines telemetry configuration for RateLimit.

RateLimitDatabaseBackend

RateLimitDatabaseBackend defines the configuration associated with the database backend used by the rate limit service.

Appears in:

FieldTypeRequiredDescription
typeRateLimitDatabaseBackendTypetrueType is the type of database backend to use. Supported types are:
* Redis: Connects to a Redis database.
redisRateLimitRedisSettingsfalseRedis defines the settings needed to connect to a Redis database.

RateLimitDatabaseBackendType

Underlying type: string

RateLimitDatabaseBackendType specifies the types of database backend to be used by the rate limit service.

Appears in:

ValueDescription
RedisRedisBackendType uses a redis database for the rate limit service.

RateLimitMetrics

Appears in:

FieldTypeRequiredDescription
prometheusRateLimitMetricsPrometheusProvidertruePrometheus defines the configuration for prometheus endpoint.

RateLimitMetricsPrometheusProvider

Appears in:

FieldTypeRequiredDescription
disablebooleantrueDisable the Prometheus endpoint.

RateLimitRedisSettings

RateLimitRedisSettings defines the configuration for connecting to redis database.

Appears in:

FieldTypeRequiredDescription
urlstringtrueURL of the Redis Database.
tlsRedisTLSSettingsfalseTLS defines TLS configuration for connecting to redis database.

RateLimitRule

RateLimitRule defines the semantics for matching attributes from the incoming requests, and setting limits for them.

Appears in:

FieldTypeRequiredDescription
clientSelectorsRateLimitSelectCondition arrayfalseClientSelectors holds the list of select conditions to select
specific clients using attributes from the traffic flow.
All individual select conditions must hold True for this rule
and its limit to be applied.

If no client selectors are specified, the rule applies to all traffic of
the targeted Route.

If the policy targets a Gateway, the rule applies to each Route of the Gateway.
Please note that each Route has its own rate limit counters. For example,
if a Gateway has two Routes, and the policy has a rule with limit 10rps,
each Route will have its own 10rps limit.
limitRateLimitValuetrueLimit holds the rate limit values.
This limit is applied for traffic flows when the selectors
compute to True, causing the request to be counted towards the limit.
The limit is enforced and the request is ratelimited, i.e. a response with
429 HTTP status code is sent back to the client when
the selected requests have reached the limit.

RateLimitSelectCondition

RateLimitSelectCondition specifies the attributes within the traffic flow that can be used to select a subset of clients to be ratelimited. All the individual conditions must hold True for the overall condition to hold True.

Appears in:

FieldTypeRequiredDescription
headersHeaderMatch arrayfalseHeaders is a list of request headers to match. Multiple header values are ANDed together,
meaning, a request MUST match all the specified headers.
At least one of headers or sourceCIDR condition must be specified.
sourceCIDRSourceMatchfalseSourceCIDR is the client IP Address range to match on.
At least one of headers or sourceCIDR condition must be specified.

RateLimitSpec

RateLimitSpec defines the desired state of RateLimitSpec.

Appears in:

FieldTypeRequiredDescription
typeRateLimitTypetrueType decides the scope for the RateLimits.
Valid RateLimitType values are “Global” or “Local”.
globalGlobalRateLimitfalseGlobal defines global rate limit configuration.
localLocalRateLimitfalseLocal defines local rate limit configuration.

RateLimitTelemetry

Appears in:

FieldTypeRequiredDescription
metricsRateLimitMetricstrueMetrics defines metrics configuration for RateLimit.
tracingRateLimitTracingtrueTracing defines traces configuration for RateLimit.

RateLimitTracing

Appears in:

FieldTypeRequiredDescription
samplingRateintegerfalseSamplingRate controls the rate at which traffic will be
selected for tracing if no prior sampling decision has been made.
Defaults to 100, valid values [0-100]. 100 indicates 100% sampling.
providerRateLimitTracingProvidertrueProvider defines the rateLimit tracing provider.
Only OpenTelemetry is supported currently.

RateLimitTracingProvider

RateLimitTracingProvider defines the tracing provider configuration of RateLimit

Appears in:

FieldTypeRequiredDescription
typeRateLimitTracingProviderTypetrueType defines the tracing provider type.
Since to RateLimit Exporter currently using OpenTelemetry, only OpenTelemetry is supported
urlstringtrueURL is the endpoint of the trace collector that supports the OTLP protocol

RateLimitType

Underlying type: string

RateLimitType specifies the types of RateLimiting.

Appears in:

ValueDescription
GlobalGlobalRateLimitType allows the rate limits to be applied across all Envoy
proxy instances.
LocalLocalRateLimitType allows the rate limits to be applied on a per Envoy
proxy instance basis.

RateLimitUnit

Underlying type: string

RateLimitUnit specifies the intervals for setting rate limits. Valid RateLimitUnit values are “Second”, “Minute”, “Hour”, and “Day”.

Appears in:

ValueDescription
SecondRateLimitUnitSecond specifies the rate limit interval to be 1 second.
MinuteRateLimitUnitMinute specifies the rate limit interval to be 1 minute.
HourRateLimitUnitHour specifies the rate limit interval to be 1 hour.
DayRateLimitUnitDay specifies the rate limit interval to be 1 day.

RateLimitValue

RateLimitValue defines the limits for rate limiting.

Appears in:

FieldTypeRequiredDescription
requestsintegertrue
unitRateLimitUnittrue

RedisTLSSettings

RedisTLSSettings defines the TLS configuration for connecting to redis database.

Appears in:

FieldTypeRequiredDescription
certificateRefSecretObjectReferencefalseCertificateRef defines the client certificate reference for TLS connections.
Currently only a Kubernetes Secret of type TLS is supported.

RemoteJWKS

RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint.

Appears in:

FieldTypeRequiredDescription
uristringtrueURI is the HTTPS URI to fetch the JWKS. Envoy’s system trust bundle is used to
validate the server certificate.

RequestHeaderCustomTag

RequestHeaderCustomTag adds value from request header to each span.

Appears in:

FieldTypeRequiredDescription
namestringtrueName defines the name of the request header which to extract the value from.
defaultValuestringfalseDefaultValue defines the default value to use if the request header is not set.

ResourceProviderType

Underlying type: string

ResourceProviderType defines the types of custom resource providers supported by Envoy Gateway.

Appears in:

ValueDescription
FileResourceProviderTypeFile defines the “File” provider.

Retry

Retry defines the retry strategy to be applied.

Appears in:

FieldTypeRequiredDescription
numRetriesintegerfalseNumRetries is the number of retries to be attempted. Defaults to 2.
retryOnRetryOnfalseRetryOn specifies the retry trigger condition.

If not specified, the default is to retry on connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes(503).
perRetryPerRetryPolicyfalsePerRetry is the retry policy to be applied per retry attempt.

RetryOn

Appears in:

FieldTypeRequiredDescription
triggersTriggerEnum arrayfalseTriggers specifies the retry trigger condition(Http/Grpc).
httpStatusCodesHTTPStatus arrayfalseHttpStatusCodes specifies the http status codes to be retried.
The retriable-status-codes trigger must also be configured for these status codes to trigger a retry.

RoutingType

Underlying type: string

RoutingType defines the type of routing of this Envoy proxy.

Appears in:

ValueDescription
ServiceServiceRoutingType is the RoutingType for Service Cluster IP routing.
EndpointEndpointRoutingType is the RoutingType for Endpoint routing.

SecurityPolicy

SecurityPolicy allows the user to configure various security settings for a Gateway.

Appears in:

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringSecurityPolicy
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specSecurityPolicySpectrueSpec defines the desired state of SecurityPolicy.
statusPolicyStatustrueStatus defines the current status of SecurityPolicy.

SecurityPolicyList

SecurityPolicyList contains a list of SecurityPolicy resources.

FieldTypeRequiredDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringSecurityPolicyList
metadataListMetatrueRefer to Kubernetes API documentation for fields of metadata.
itemsSecurityPolicy arraytrue

SecurityPolicySpec

SecurityPolicySpec defines the desired state of SecurityPolicy.

Appears in:

FieldTypeRequiredDescription
targetRefLocalPolicyTargetReferenceWithSectionNametrueTargetRef 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
targetRefsLocalPolicyTargetReferenceWithSectionName arraytrueTargetRefs are the names of the Gateway resources this policy
is being attached to.
targetSelectorsTargetSelector arraytrueTargetSelectors allow targeting resources for this policy based on labels
corsCORSfalseCORS defines the configuration for Cross-Origin Resource Sharing (CORS).
basicAuthBasicAuthfalseBasicAuth defines the configuration for the HTTP Basic Authentication.
jwtJWTfalseJWT defines the configuration for JSON Web Token (JWT) authentication.
oidcOIDCfalseOIDC defines the configuration for the OpenID Connect (OIDC) authentication.
extAuthExtAuthfalseExtAuth defines the configuration for External Authorization.
authorizationAuthorizationfalseAuthorization defines the authorization configuration.

ServiceExternalTrafficPolicy

Underlying type: string

ServiceExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs.

Appears in:

ValueDescription
ClusterServiceExternalTrafficPolicyCluster routes traffic to all endpoints.
LocalServiceExternalTrafficPolicyLocal preserves the source IP of the traffic by
routing only to endpoints on the same node as the traffic was received on
(dropping the traffic if there are no local endpoints).

ServiceType

Underlying type: string

ServiceType string describes ingress methods for a service

Appears in:

ValueDescription
ClusterIPServiceTypeClusterIP means a service will only be accessible inside the
cluster, via the cluster IP.
LoadBalancerServiceTypeLoadBalancer means a service will be exposed via an
external load balancer (if the cloud provider supports it).
NodePortServiceTypeNodePort means a service will be exposed on each Kubernetes Node
at a static Port, common across all Nodes.

ShutdownConfig

ShutdownConfig defines configuration for graceful envoy shutdown process.

Appears in:

FieldTypeRequiredDescription
drainTimeoutDurationfalseDrainTimeout defines the graceful drain timeout. This should be less than the pod’s terminationGracePeriodSeconds.
If unspecified, defaults to 600 seconds.
minDrainDurationDurationfalseMinDrainDuration defines the minimum drain duration allowing time for endpoint deprogramming to complete.
If unspecified, defaults to 5 seconds.

ShutdownManager

ShutdownManager defines the configuration for the shutdown manager.

Appears in:

FieldTypeRequiredDescription
imagestringtrueImage specifies the ShutdownManager container image to be used, instead of the default image.

SlowStart

SlowStart defines the configuration related to the slow start load balancer policy.

Appears in:

FieldTypeRequiredDescription
windowDurationtrueWindow defines the duration of the warm up period for newly added host.
During slow start window, traffic sent to the newly added hosts will gradually increase.
Currently only supports linear growth of traffic. For additional details,
see https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#config-cluster-v3-cluster-slowstartconfig

SourceMatchType

Underlying type: string

Appears in:

ValueDescription
ExactSourceMatchExact All IP Addresses within the specified Source IP CIDR are treated as a single client selector
and share the same rate limit bucket.
DistinctSourceMatchDistinct Each IP Address within the specified Source IP CIDR is treated as a distinct client selector
and uses a separate rate limit bucket/counter.
Note: This is only supported for Global Rate Limits.

StringMatch

StringMatch defines how to match any strings. This is a general purpose match condition that can be used by other EG APIs that need to match against a string.

Appears in:

FieldTypeRequiredDescription
typeStringMatchTypefalseType specifies how to match against a string.
valuestringtrueValue specifies the string value that the match must have.

StringMatchType

Underlying type: string

StringMatchType specifies the semantics of how a string value should be compared. Valid MatchType values are “Exact”, “Prefix”, “Suffix”, “RegularExpression”.

Appears in:

ValueDescription
ExactStringMatchExact :the input string must match exactly the match value.
PrefixStringMatchPrefix :the input string must start with the match value.
SuffixStringMatchSuffix :the input string must end with the match value.
RegularExpressionStringMatchRegularExpression :The input string must match the regular expression
specified in the match value.
The regex string must adhere to the syntax documented in
https://github.com/google/re2/wiki/Syntax.

TCPActiveHealthChecker

TCPActiveHealthChecker defines the settings of tcp health check.

Appears in:

FieldTypeRequiredDescription
sendActiveHealthCheckPayloadfalseSend defines the request payload.
receiveActiveHealthCheckPayloadfalseReceive defines the expected response payload.

TCPClientTimeout

TCPClientTimeout only provides timeout configuration on the listener whose protocol is TCP or TLS.

Appears in:

FieldTypeRequiredDescription
idleTimeoutDurationfalseIdleTimeout for a TCP connection. Idle time is defined as a period in which there are no
bytes sent or received on either the upstream or downstream connection.
Default: 1 hour.

TCPKeepalive

TCPKeepalive define the TCP Keepalive configuration.

Appears in:

FieldTypeRequiredDescription
probesintegerfalseThe total number of unacknowledged probes to send before deciding
the connection is dead.
Defaults to 9.
idleTimeDurationfalseThe duration a connection needs to be idle before keep-alive
probes start being sent.
The duration format is
Defaults to 7200s.
intervalDurationfalseThe duration between keep-alive probes.
Defaults to 75s.

TCPTimeout

Appears in:

FieldTypeRequiredDescription
connectTimeoutDurationfalseThe timeout for network connection establishment, including TCP and TLS handshakes.
Default: 10 seconds.

TLSSettings

Appears in:

FieldTypeRequiredDescription
minVersionTLSVersionfalseMin specifies the minimal TLS protocol version to allow.
The default is TLS 1.2 if this is not specified.
maxVersionTLSVersionfalseMax specifies the maximal TLS protocol version to allow
The default is TLS 1.3 if this is not specified.
ciphersstring arrayfalseCiphers specifies the set of cipher suites supported when
negotiating TLS 1.0 - 1.2. This setting has no effect for TLS 1.3.
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
ecdhCurvesstring arrayfalseECDHCurves 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
signatureAlgorithmsstring arrayfalseSignatureAlgorithms specifies which signature algorithms the listener should
support.
alpnProtocolsALPNProtocol arrayfalseALPNProtocols supplies the list of ALPN protocols that should be
exposed by the listener. By default h2 and http/1.1 are enabled.
Supported values are:
- http/1.0
- http/1.1
- h2

TLSVersion

Underlying type: string

TLSVersion specifies the TLS version

Appears in:

ValueDescription
AutoTLSAuto allows Envoy to choose the optimal TLS Version
1.0TLS1.0 specifies TLS version 1.0
1.1TLS1.1 specifies TLS version 1.1
1.2TLSv1.2 specifies TLS version 1.2
1.3TLSv1.3 specifies TLS version 1.3

TargetSelector

Appears in:

FieldTypeRequiredDescription
groupGrouptrueGroup is the group that this selector targets. Defaults to gateway.networking.k8s.io
kindKindtrueKind is the resource kind that this selector targets.
matchLabelsobject (keys:string, values:string)trueMatchLabels are the set of label selectors for identifying the targeted resource

Timeout

Timeout defines configuration for timeouts related to connections.

Appears in:

FieldTypeRequiredDescription
tcpTCPTimeoutfalseTimeout settings for TCP.
httpHTTPTimeoutfalseTimeout settings for HTTP.

TracingProvider

TracingProvider defines the tracing provider configuration.

Appears in:

FieldTypeRequiredDescription
typeTracingProviderTypetrueType defines the tracing provider type.
hoststringfalseHost define the provider service hostname.
Deprecated: Use BackendRefs instead.
portintegerfalsePort defines the port the provider service is exposed on.
Deprecated: Use BackendRefs instead.
backendRefsBackendRef arrayfalseBackendRefs references a Kubernetes object that represents the
backend server to which the trace will be sent.
Only Service kind is supported for now.
zipkinZipkinTracingProviderfalseZipkin defines the Zipkin tracing provider configuration

TracingProviderType

Underlying type: string

Appears in:

ValueDescription
OpenTelemetry
OpenTelemetry
Zipkin

TriggerEnum

Underlying type: string

TriggerEnum specifies the conditions that trigger retries.

Appears in:

ValueDescription
5xxThe upstream server responds with any 5xx response code, or does not respond at all (disconnect/reset/read timeout).
Includes connect-failure and refused-stream.
gateway-errorThe response is a gateway error (502,503 or 504).
resetThe upstream server does not respond at all (disconnect/reset/read timeout.)
connect-failureConnection failure to the upstream server (connect timeout, etc.). (Included in 5xx)
retriable-4xxThe upstream server responds with a retriable 4xx response code.
Currently, the only response code in this category is 409.
refused-streamThe upstream server resets the stream with a REFUSED_STREAM error code.
retriable-status-codesThe upstream server responds with any response code matching one defined in the RetriableStatusCodes.
cancelledThe gRPC status code in the response headers is “cancelled”.
deadline-exceededThe gRPC status code in the response headers is “deadline-exceeded”.
internalThe gRPC status code in the response headers is “internal”.
resource-exhaustedThe gRPC status code in the response headers is “resource-exhausted”.
unavailableThe gRPC status code in the response headers is “unavailable”.

UnixSocket

UnixSocket describes TCP/UDP unix domain socket address, corresponding to Envoy’s Pipe https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-pipe

Appears in:

FieldTypeRequiredDescription
pathstringtruePath defines the unix domain socket path of the backend endpoint.

Wasm

Wasm defines a Wasm extension.

Note: at the moment, Envoy Gateway does not support configuring Wasm runtime. v8 is used as the VM runtime for the Wasm extensions.

Appears in:

FieldTypeRequiredDescription
namestringfalseName is a unique name for this Wasm extension. It is used to identify the
Wasm extension if multiple extensions are handled by the same vm_id and root_id.
It’s also used for logging/debugging.
If not specified, EG will generate a unique name for the Wasm extension.
rootIDstringtrueRootID is a unique ID for a set of extensions in a VM which will share a
RootContext and Contexts if applicable (e.g., an Wasm HttpFilter and an Wasm AccessLog).
If left blank, all extensions with a blank root_id with the same vm_id will share Context(s).

Note: RootID must match the root_id parameter used to register the Context in the Wasm code.
codeWasmCodeSourcetrueCode is the Wasm code for the extension.
configJSONfalseConfig is the configuration for the Wasm extension.
This configuration will be passed as a JSON string to the Wasm extension.
failOpenbooleanfalseFailOpen is a switch used to control the behavior when a fatal error occurs
during the initialization or the execution of the Wasm extension.
If FailOpen is set to true, the system bypasses the Wasm extension and
allows the traffic to pass through. Otherwise, if it is set to false or
not set (defaulting to false), the system blocks the traffic and returns
an HTTP 5xx error.

WasmCodeSource

WasmCodeSource defines the source of the Wasm code.

Appears in:

FieldTypeRequiredDescription
typeWasmCodeSourceTypetrueType is the type of the source of the Wasm code.
Valid WasmCodeSourceType values are “HTTP” or “Image”.
httpHTTPWasmCodeSourcefalseHTTP is the HTTP URL containing the Wasm code.

Note that the HTTP server must be accessible from the Envoy proxy.
imageImageWasmCodeSourcefalseImage is the OCI image containing the Wasm code.

Note that the image must be accessible from the Envoy Gateway.
pullPolicyImagePullPolicyfalsePullPolicy is the policy to use when pulling the Wasm module by either the HTTP or Image source.
This field is only applicable when the SHA256 field is not set.

If not specified, the default policy is IfNotPresent except for OCI images whose tag is latest.

Note: EG does not update the Wasm module every time an Envoy proxy requests
the Wasm module even if the pull policy is set to Always.
It only updates the Wasm module when the EnvoyExtension resource version changes.

WasmCodeSourceType

Underlying type: string

WasmCodeSourceType specifies the types of sources for the Wasm code.

Appears in:

ValueDescription
HTTPHTTPWasmCodeSourceType allows the user to specify the Wasm code in an HTTP URL.
ImageImageWasmCodeSourceType allows the user to specify the Wasm code in an OCI image.

WithUnderscoresAction

Underlying type: string

WithUnderscoresAction configures the action to take when an HTTP header with underscores is encountered.

Appears in:

ValueDescription
AllowWithUnderscoresActionAllow allows headers with underscores to be passed through.
RejectRequestWithUnderscoresActionRejectRequest rejects the client request. HTTP/1 requests are rejected with
the 400 status. HTTP/2 requests end with the stream reset.
DropHeaderWithUnderscoresActionDropHeader drops the client header with name containing underscores. The header
is dropped before the filter chain is invoked and as such filters will not see
dropped headers.

XDSTranslatorHook

Underlying type: string

XDSTranslatorHook defines the types of hooks that an Envoy Gateway extension may support for the xds-translator

Appears in:

ValueDescription
VirtualHost
Route
HTTPListener
Translation

XDSTranslatorHooks

XDSTranslatorHooks contains all the pre and post hooks for the xds-translator runner.

Appears in:

FieldTypeRequiredDescription
preXDSTranslatorHook arraytrue
postXDSTranslatorHook arraytrue

XFCCCertData

Underlying type: string

XFCCCertData specifies the fields in the client certificate to be forwarded in the XFCC header.

Appears in:

ValueDescription
SubjectXFCCCertDataSubject is the Subject field of the current client certificate.
CertXFCCCertDataCert is the entire client certificate in URL encoded PEM format.
ChainXFCCCertDataChain is the entire client certificate chain (including the leaf certificate) in URL encoded PEM format.
DNSXFCCCertDataDNS is the DNS type Subject Alternative Name field of the current client certificate.
URIXFCCCertDataURI is the URI type Subject Alternative Name field of the current client certificate.

XFCCForwardMode

Underlying type: string

XFCCForwardMode defines how XFCC header is handled by Envoy Proxy.

Appears in:

ValueDescription
SanitizeXFCCForwardModeSanitize removes the XFCC header from the request. This is the default mode.
ForwardOnlyXFCCForwardModeForwardOnly forwards the XFCC header in the request if the client connection is mTLS.
AppendForwardXFCCForwardModeAppendForward appends the client certificate information to the request’s XFCC header and forward it if the client connection is mTLS.
SanitizeSetXFCCForwardModeSanitizeSet resets the XFCC header with the client certificate information and forward it if the client connection is mTLS.
The existing certificate information in the XFCC header is removed.
AlwaysForwardOnlyXFCCForwardModeAlwaysForwardOnly always forwards the XFCC header in the request, regardless of whether the client connection is mTLS.

XForwardedClientCert

XForwardedClientCert configures how Envoy Proxy handle the x-forwarded-client-cert (XFCC) HTTP header.

Appears in:

FieldTypeRequiredDescription
modeXFCCForwardModefalseMode defines how XFCC header is handled by Envoy Proxy.
If not set, the default mode is Sanitize.
certDetailsToAddXFCCCertData arrayfalseCertDetailsToAdd specifies the fields in the client certificate to be forwarded in the XFCC header.

Hash(the SHA 256 digest of the current client certificate) and By(the Subject Alternative Name)
are always included if the client certificate is forwarded.

This field is only applicable when the mode is set to AppendForward or
SanitizeSet and the client connection is mTLS.

XForwardedForSettings

XForwardedForSettings provides configuration for using X-Forwarded-For headers for determining the client IP address.

Appears in:

FieldTypeRequiredDescription
numTrustedHopsintegerfalseNumTrustedHops controls the number of additional ingress proxy hops from the right side of XFF HTTP
headers to trust when determining the origin client’s IP address.
Refer to https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-for
for more details.

ZipkinTracingProvider

ZipkinTracingProvider defines the Zipkin tracing provider configuration.

Appears in:

FieldTypeRequiredDescription
enable128BitTraceIdbooleanfalseEnable128BitTraceID determines whether a 128bit trace id will be used
when creating a new trace instance. If set to false, a 64bit trace
id will be used.
disableSharedSpanContextbooleanfalseDisableSharedSpanContext determines whether the default Envoy behaviour of
client and server spans sharing the same span context should be disabled.

Last modified December 6, 2024: feat: add body to ext auth (#4671) (ac86045)