package envoy.config.core.v3
Get desktop application:
View/edit binary Protocol Buffers messages
message
address.proto:180Addresses specify either a logical or physical address and port, which are used to tell Envoy where to bind/listen, connect to upstream and find management servers.
Used in: , , , , , , , , , , , , , , , , , , , ,
oneof address
socket_address = 1
pipe = 2
envoy_internal_address = 3
Specifies a user-space address handled by :ref:`internal listeners <envoy_v3_api_field_config.listener.v3.Listener.internal_listener>`.
message
config_source.proto:126Aggregated Discovery Service (ADS) options. This is currently empty, but when set in :ref:`ConfigSource <envoy_v3_api_msg_config.core.v3.ConfigSource>` can be used to specify that ADS is to be used.
Used in:
(message has no fields)
message
protocol.proto:159Configures the alternate protocols cache which tracks alternate protocols that can be used to make an HTTP connection to an origin server. See https://tools.ietf.org/html/rfc7838 for HTTP Alternative Services and https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04 for the "HTTPS" DNS resource record. [#next-free-field: 6]
Used in: ,
string name = 1
The name of the cache. Multiple named caches allow independent alternate protocols cache configurations to operate within a single Envoy process using different configurations. All alternate protocols cache options with the same name *must* be equal in all fields when referenced from different configuration components. Configuration will fail to load if this is not the case.
optional max_entries = 2
The maximum number of entries that the cache will hold. If not specified defaults to 1024. .. note: The implementation is approximate and enforced independently on each worker thread, thus it is possible for the maximum entries in the cache to go slightly above the configured value depending on timing. This is similar to how other circuit breakers work.
optional key_value_store_config = 3
Allows configuring a persistent :ref:`key value store <envoy_v3_api_msg_config.common.key_value.v3.KeyValueStoreConfig>` to flush alternate protocols entries to disk. This function is currently only supported if concurrency is 1 Cached entries will take precedence over pre-populated entries below.
repeated prepopulated_entries = 4
Allows pre-populating the cache with entries, as described above.
repeated string canonical_suffixes = 5
Optional list of hostnames suffixes for which Alt-Svc entries can be shared. For example, if this list contained the value ``.c.example.com``, then an Alt-Svc entry for ``foo.c.example.com`` could be shared with ``bar.c.example.com`` but would not be shared with ``baz.example.com``. On the other hand, if the list contained the value ``.example.com`` then all three hosts could share Alt-Svc entries. Each entry must start with ``.``. If a hostname matches multiple suffixes, the first listed suffix will be used. Since lookup in this list is O(n), it is recommended that the number of suffixes be limited. [#not-implemented-hide:]
message
protocol.proto:169Allows pre-populating the cache with HTTP/3 alternate protocols entries with a 7 day lifetime. This will cause Envoy to attempt HTTP/3 to those upstreams, even if the upstreams have not advertised HTTP/3 support. These entries will be overwritten by alt-svc response headers or cached values. As with regular cached entries, if the origin response would result in clearing an existing alternate protocol cache entry, pre-populated entries will also be cleared. Adding a cache entry with hostname=foo.com port=123 is the equivalent of getting response headers alt-svc: h3=:"123"; ma=86400" in a response to a request to foo.com:123
Used in:
string hostname = 1
The host name for the alternate protocol entry.
uint32 port = 2
The port for the alternate protocol entry.
message
config_source.proto:44API configuration source. This identifies the API type and cluster that Envoy will use to fetch an xDS API. [#next-free-field: 10]
Used in: , , ,
ApiConfigSource.ApiType api_type = 1
API type (gRPC, REST, delta gRPC)
ApiVersion transport_api_version = 8
API version for xDS transport protocol. This describes the xDS gRPC/REST endpoint and version of [Delta]DiscoveryRequest/Response used on the wire.
repeated string cluster_names = 2
Cluster names should be used only with REST. If > 1 cluster is defined, clusters will be cycled through if any kind of failure occurs. .. note:: The cluster with name ``cluster_name`` must be statically defined and its type must not be ``EDS``.
repeated grpc_services = 4
Multiple gRPC services be provided for GRPC. If > 1 cluster is defined, services will be cycled through if any kind of failure occurs.
optional refresh_delay = 3
For REST APIs, the delay between successive polls.
optional request_timeout = 5
For REST APIs, the request timeout. If not set, a default value of 1s will be used.
optional rate_limit_settings = 6
For GRPC APIs, the rate limit settings. If present, discovery requests made by Envoy will be rate limited.
bool set_node_on_first_message_only = 7
Skip the node identifier in subsequent discovery requests for streaming gRPC config types.
repeated config_validators = 9
A list of config validators that will be executed when a new update is received from the ApiConfigSource. Note that each validator handles a specific xDS service type, and only the validators corresponding to the type url (in ``:ref: DiscoveryResponse`` or ``:ref: DeltaDiscoveryResponse``) will be invoked. If the validator returns false or throws an exception, the config will be rejected by the client, and a NACK will be sent. [#extension-category: envoy.config.validators]
APIs may be fetched via either REST or gRPC.
Used in:
DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE = 0
Ideally this would be 'reserved 0' but one can't reserve the default value. Instead we throw an exception if this is ever used.
REST = 1
REST-JSON v2 API. The `canonical JSON encoding <https://developers.google.com/protocol-buffers/docs/proto3#json>`_ for the v2 protos is used.
GRPC = 2
SotW gRPC service.
DELTA_GRPC = 3
Using the delta xDS gRPC service, i.e. DeltaDiscovery{Request,Response} rather than Discovery{Request,Response}. Rather than sending Envoy the entire state with every update, the xDS server only sends what has changed since the last update.
AGGREGATED_GRPC = 5
SotW xDS gRPC with ADS. All resources which resolve to this configuration source will be multiplexed on a single connection to an ADS endpoint. [#not-implemented-hide:]
AGGREGATED_DELTA_GRPC = 6
Delta xDS gRPC with ADS. All resources which resolve to this configuration source will be multiplexed on a single connection to an ADS endpoint. [#not-implemented-hide:]
xDS API and non-xDS services version. This is used to describe both resource and transport protocol versions (in distinct configuration fields).
Used in: , , , , , , ,
AUTO = 0
When not specified, we assume v3; it is the only supported version.
V2 = 1
Use xDS v2 API. This is no longer supported.
V3 = 2
Use xDS v3 API.
message
base.proto:597Async data source which support async data fetch.
Used in:
oneof specifier
local = 1
Local async data source.
remote = 2
Remote async data source.
message
backoff.proto:20Configuration defining a jittered exponential back off strategy.
Used in: , , , ,
optional base_interval = 1
The base interval to be used for the next back off computation. It should be greater than zero and less than or equal to :ref:`max_interval <envoy_v3_api_field_config.core.v3.BackoffStrategy.max_interval>`.
optional max_interval = 2
Specifies the maximum interval between retries. This parameter is optional, but must be greater than or equal to the :ref:`base_interval <envoy_v3_api_field_config.core.v3.BackoffStrategy.base_interval>` if set. The default is 10 times the :ref:`base_interval <envoy_v3_api_field_config.core.v3.BackoffStrategy.base_interval>`.
message
address.proto:140[#next-free-field: 7]
Used in: , ,
optional source_address = 1
The address to bind to when creating a socket.
optional freebind = 2
Whether to set the ``IP_FREEBIND`` option when creating the socket. When this flag is set to true, allows the :ref:`source_address <envoy_v3_api_field_config.core.v3.BindConfig.source_address>` to be an IP address that is not configured on the system running Envoy. When this flag is set to false, the option ``IP_FREEBIND`` is disabled on the socket. When this flag is not set (default), the socket is not modified, i.e. the option is neither enabled nor disabled.
repeated socket_options = 3
Additional socket options that may not be present in Envoy source code or precompiled binaries.
repeated extra_source_addresses = 5
Extra source addresses appended to the address specified in the ``source_address`` field. This enables to specify multiple source addresses. The source address selection is determined by :ref:`local_address_selector <envoy_v3_api_field_config.core.v3.BindConfig.local_address_selector>`.
repeated additional_source_addresses = 4
Deprecated by :ref:`extra_source_addresses <envoy_v3_api_field_config.core.v3.BindConfig.extra_source_addresses>`
optional local_address_selector = 6
Custom local address selector to override the default (i.e. :ref:`DefaultLocalAddressSelector <envoy_v3_api_msg_config.upstream.local_address_selector.v3.DefaultLocalAddressSelector>`). [#extension-category: envoy.upstream.local_address_selector]
message
base.proto:94BuildVersion combines SemVer version of extension with free-form build information (i.e. 'alpha', 'private-build') as a set of strings.
Used in: ,
optional version = 1
SemVer version of extension.
optional metadata = 2
Free-form build information. Envoy defines several well known keys in the source/common/version/version.h file
message
address.proto:198CidrRange specifies an IP Address and a prefix length to construct the subnet mask for a `CIDR <https://tools.ietf.org/html/rfc4632>`_ range.
Used in: , , , , , , , ,
string address_prefix = 1
IPv4 or IPv6 address, e.g. ``192.0.0.0`` or ``2001:db8::``.
optional prefix_len = 2
Length of prefix, e.g. 0, 32. Defaults to 0 when unset.
message
config_source.proto:201Configuration for :ref:`listeners <config_listeners>`, :ref:`clusters <config_cluster_manager>`, :ref:`routes <envoy_v3_api_msg_config.route.v3.RouteConfiguration>`, :ref:`endpoints <arch_overview_service_discovery>` etc. may either be sourced from the filesystem or from an xDS API source. Filesystem configs are watched with inotify for updates. [#next-free-field: 9]
Used in: , , , , , , , , , , , , , , , ,
repeated authorities = 7
Authorities that this config source may be used for. An authority specified in a xdstp:// URL is resolved to a ``ConfigSource`` prior to configuration fetch. This field provides the association between authority name and configuration source. [#not-implemented-hide:]
oneof config_source_specifier
string path = 1
Deprecated in favor of ``path_config_source``. Use that field instead.
path_config_source = 8
Local filesystem path configuration source.
api_config_source = 2
API configuration source.
ads = 3
When set, ADS will be used to fetch resources. The ADS API configuration source in the bootstrap configuration is used.
self = 5
[#not-implemented-hide:] When set, the client will access the resources from the same server it got the ConfigSource from, although not necessarily from the same stream. This is similar to the :ref:`ads<envoy_v3_api_field.ConfigSource.ads>` field, except that the client may use a different stream to the same server. As a result, this field can be used for things like LRS that cannot be sent on an ADS stream. It can also be used to link from (e.g.) LDS to RDS on the same server without requiring the management server to know its name or required credentials. [#next-major-version: In xDS v3, consider replacing the ads field with this one, since this field can implicitly mean to use the same stream in the case where the ConfigSource is provided via ADS and the specified data can also be obtained via ADS.]
optional initial_fetch_timeout = 4
When this timeout is specified, Envoy will wait no longer than the specified time for first config response on this xDS subscription during the :ref:`initialization process <arch_overview_initialization>`. After reaching the timeout, Envoy will move to the next initialization phase, even if the first config is not delivered yet. The timer is activated when the xDS API subscription starts, and is disarmed on first config update or on error. 0 means no timeout - Envoy will wait indefinitely for the first xDS config (unless another timeout applies). The default is 15s.
ApiVersion resource_api_version = 6
API version for xDS resources. This implies the type URLs that the client will request for resources and the resource type that the client will in turn expect to be delivered.
message
base.proto:655Identifies a specific ControlPlane instance that Envoy is connected to.
Used in: ,
string identifier = 1
An opaque control plane identifier that uniquely identifies an instance of control plane. This can be used to identify which control plane instance, the Envoy is connected to.
message
base.proto:500Data source consisting of a file, an inline value, or an environment variable. [#next-free-field: 6]
Used in: , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
oneof specifier
string filename = 1
Local filesystem data source.
bytes inline_bytes = 2
Bytes inlined in the configuration.
string inline_string = 3
String inlined in the configuration.
string environment_variable = 4
Environment variable data source.
optional watched_directory = 5
Watched directory that is watched for file changes. If this is set explicitly, the file specified in the ``filename`` field will be reloaded when relevant file move events occur. .. note:: This field only makes sense when the ``filename`` field is set. .. note:: Envoy only updates when the file is replaced by a file move, and not when the file is edited in place. .. note:: Not all use cases of ``DataSource`` support watching directories. It depends on the specific usage of the ``DataSource``. See the documentation of the parent message for details.
message
resolver.proto:28DNS resolution configuration which includes the underlying dns resolver addresses and options.
Used in: , , ,
repeated resolvers = 1
A list of dns resolver addresses. If specified, the DNS client library will perform resolution via the underlying DNS resolvers. Otherwise, the default system resolvers (e.g., /etc/resolv.conf) will be used.
optional dns_resolver_options = 2
Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
message
resolver.proto:19Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
Used in: ,
bool use_tcp_for_dns_lookups = 1
Use TCP for all DNS queries instead of the default protocol UDP.
bool no_default_search_domain = 2
Do not use the default search domains; only query hostnames as-is or as aliases.
message
address.proto:38The address represents an envoy internal listener. [#comment: TODO(asraa): When address available, remove workaround from test/server/server_fuzz_test.cc:30.]
Used in:
oneof address_name_specifier
string server_listener_name = 1
Specifies the :ref:`name <envoy_v3_api_field_config.listener.v3.Listener.name>` of the internal listener.
string endpoint_id = 2
Specifies an endpoint identifier to distinguish between multiple endpoints for the same internal listener in a single upstream pool. Only used in the upstream addresses for tracking changes to individual endpoints. This, for example, may be set to the final destination IP for the target internal listener.
message
event_service_config.proto:19[#not-implemented-hide:] Configuration of the event reporting service endpoint.
Used in: ,
oneof config_source_specifier
grpc_service = 1
Specifies the gRPC service that hosts the event reporting service.
message
base.proto:107Version and identification for an Envoy extension. [#next-free-field: 7]
Used in:
string name = 1
This is the name of the Envoy filter as specified in the Envoy configuration, e.g. envoy.filters.http.router, com.acme.widget.
string category = 2
Category of the extension. Extension category names use reverse DNS notation. For instance "envoy.filters.listener" for Envoy's built-in listener filters or "com.acme.filters.http" for HTTP filters from acme.com vendor. [#comment:TODO(yanavlasov): Link to the doc with existing envoy category names.]
string type_descriptor = 3
[#not-implemented-hide:] Type descriptor of extension configuration proto. [#comment:TODO(yanavlasov): Link to the doc with existing configuration protos.] [#comment:TODO(yanavlasov): Add tests when PR #9391 lands.]
optional version = 4
The version is a property of the extension and maintained independently of other extensions and the Envoy API. This field is not set when extension did not provide version information.
bool disabled = 5
Indicates that the extension is present but was disabled via dynamic configuration.
repeated string type_urls = 6
Type URLs of extension configuration protos.
message
config_source.proto:266Configuration source specifier for a late-bound extension configuration. The parent resource is warmed until all the initial extension configurations are received, unless the flag to apply the default configuration is set. Subsequent extension updates are atomic on a per-worker basis. Once an extension configuration is applied to a request or a connection, it remains constant for the duration of processing. If the initial delivery of the extension configuration fails, due to a timeout for example, the optional default configuration is applied. Without a default configuration, the extension is disabled, until an extension configuration is received. The behavior of a disabled extension depends on the context. For example, a filter chain with a disabled extension filter rejects all incoming streams.
Used in: , , , , ,
optional config_source = 1
optional default_config = 2
Optional default configuration to use as the initial configuration if there is a failure to receive the initial extension configuration or if ``apply_default_config_without_warming`` flag is set.
bool apply_default_config_without_warming = 3
Use the default config as the initial configuration without warming and waiting for the first discovery response. Requires the default configuration to be supplied.
repeated string type_urls = 4
A set of permitted extension type URLs. Extension configuration updates are rejected if they do not match any type URL in the set.
message
address.proto:125Used in:
optional address = 1
The additional address to bind.
optional socket_options = 2
Additional socket options that may not be present in Envoy source code or precompiled binaries. If specified, this will override the :ref:`socket_options <envoy_v3_api_field_config.core.v3.BindConfig.socket_options>` in the BindConfig. If specified with no :ref:`socket_options <envoy_v3_api_field_config.core.v3.SocketOptionsOverride.socket_options>` or an empty list of :ref:`socket_options <envoy_v3_api_field_config.core.v3.SocketOptionsOverride.socket_options>`, it means no socket option will apply.
message
grpc_method_list.proto:18A list of gRPC methods which can be used as an allowlist, for example.
Used in:
repeated services = 1
message
grpc_method_list.proto:21Used in:
string name = 1
The name of the gRPC service.
repeated string method_names = 2
The names of the gRPC methods in this service.
message
protocol.proto:651[#not-implemented-hide:]
optional http2_protocol_options = 1
message
grpc_service.proto:29gRPC service configuration. This is used by :ref:`ApiConfigSource <envoy_v3_api_msg_config.core.v3.ApiConfigSource>` and filter configurations. [#next-free-field: 7]
Used in: , , , , , , , , , , , , , , , ,
oneof target_specifier
envoy_grpc = 1
Envoy's in-built gRPC client. See the :ref:`gRPC services overview <arch_overview_grpc_services>` documentation for discussion on gRPC client selection.
google_grpc = 2
`Google C++ gRPC client <https://github.com/grpc/grpc>`_ See the :ref:`gRPC services overview <arch_overview_grpc_services>` documentation for discussion on gRPC client selection.
optional timeout = 3
The timeout for the gRPC request. This is the timeout for a specific request.
repeated initial_metadata = 5
Additional metadata to include in streams initiated to the GrpcService. This can be used for scenarios in which additional ad hoc authorization headers (e.g. ``x-foo-bar: baz-key``) are to be injected. For more information, including details on header value syntax, see the documentation on :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
optional retry_policy = 6
Optional default retry policy for streams toward the service. If an async stream doesn't have retry policy configured in its stream options, this retry policy is used.
message
grpc_service.proto:33[#next-free-field: 6]
Used in:
string cluster_name = 1
The name of the upstream gRPC cluster. SSL credentials will be supplied in the :ref:`Cluster <envoy_v3_api_msg_config.cluster.v3.Cluster>` :ref:`transport_socket <envoy_v3_api_field_config.cluster.v3.Cluster.transport_socket>`.
string authority = 2
The ``:authority`` header in the grpc request. If this field is not set, the authority header value will be ``cluster_name``. Note that this authority does not override the SNI. The SNI is provided by the transport socket of the cluster.
optional retry_policy = 3
Indicates the retry policy for re-establishing the gRPC stream This field is optional. If max interval is not provided, it will be set to ten times the provided base interval. Currently only supported for xDS gRPC streams. If not set, xDS gRPC streams default base interval:500ms, maximum interval:30s will be applied.
optional max_receive_message_length = 4
Maximum gRPC message size that is allowed to be received. If a message over this limit is received, the gRPC stream is terminated with the RESOURCE_EXHAUSTED error. This limit is applied to individual messages in the streaming response and not the total size of streaming response. Defaults to 0, which means unlimited.
bool skip_envoy_headers = 5
This provides gRPC client level control over envoy generated headers. If false, the header will be sent but it can be overridden by per stream option. If true, the header will be removed and can not be overridden by per stream option. Default to false.
message
grpc_service.proto:68[#next-free-field: 9]
Used in:
string target_uri = 1
The target URI when using the `Google C++ gRPC client <https://github.com/grpc/grpc>`_. SSL credentials will be supplied in :ref:`channel_credentials <envoy_v3_api_field_config.core.v3.GrpcService.GoogleGrpc.channel_credentials>`.
optional channel_credentials = 2
repeated call_credentials = 3
A set of call credentials that can be composed with `channel credentials <https://grpc.io/docs/guides/auth.html#credential-types>`_.
string stat_prefix = 4
The human readable prefix to use when emitting statistics for the gRPC service. .. csv-table:: :header: Name, Type, Description :widths: 1, 1, 2 streams_total, Counter, Total number of streams opened streams_closed_<gRPC status code>, Counter, Total streams closed with <gRPC status code>
string credentials_factory_name = 5
The name of the Google gRPC credentials factory to use. This must have been registered with Envoy. If this is empty, a default credentials factory will be used that sets up channel credentials based on other configuration parameters.
optional config = 6
Additional configuration for site-specific customizations of the Google gRPC library.
optional per_stream_buffer_limit_bytes = 7
How many bytes each stream can buffer internally. If not set an implementation defined default is applied (1MiB).
optional channel_args = 8
Custom channels args.
message
grpc_service.proto:113[#next-free-field: 8]
Used in:
oneof credential_specifier
string access_token = 1
Access token credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#ad3a80da696ffdaea943f0f858d7a360d.
google_compute_engine = 2
Google Compute Engine credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a6beb3ac70ff94bd2ebbd89b8f21d1f61
string google_refresh_token = 3
Google refresh token credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a96901c997b91bc6513b08491e0dca37c.
service_account_jwt_access = 4
Service Account JWT Access credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a92a9f959d6102461f66ee973d8e9d3aa.
google_iam = 5
Google IAM credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a9fc1fc101b41e680d47028166e76f9d0.
from_plugin = 6
Custom authenticator credentials. https://grpc.io/grpc/cpp/namespacegrpc.html#a823c6a4b19ffc71fb33e90154ee2ad07. https://grpc.io/docs/guides/auth.html#extending-grpc-to-support-other-authentication-mechanisms.
sts_service = 7
Custom security token service which implements OAuth 2.0 token exchange. https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16 See https://github.com/grpc/grpc/pull/19587.
message
grpc_service.proto:127Used in:
string authorization_token = 1
string authority_selector = 2
message
grpc_service.proto:136Used in:
string name = 1
oneof config_type
[#extension-category: envoy.grpc_credentials]
typed_config = 3
message
grpc_service.proto:117Used in:
string json_key = 1
uint64 token_lifetime_seconds = 2
message
grpc_service.proto:158Security token service configuration that allows Google gRPC to fetch security token from an OAuth 2.0 authorization server. See https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16 and https://github.com/grpc/grpc/pull/19587. [#next-free-field: 10]
Used in:
string token_exchange_service_uri = 1
URI of the token exchange service that handles token exchange requests. [#comment:TODO(asraa): Add URI validation when implemented. Tracked by https://github.com/bufbuild/protoc-gen-validate/issues/303]
string resource = 2
Location of the target service or resource where the client intends to use the requested security token.
string audience = 3
Logical name of the target service where the client intends to use the requested security token.
string scope = 4
The desired scope of the requested security token in the context of the service or resource where the token will be used.
string requested_token_type = 5
Type of the requested security token.
string subject_token_path = 6
The path of subject token, a security token that represents the identity of the party on behalf of whom the request is being made.
string subject_token_type = 7
Type of the subject token.
string actor_token_path = 8
The path of actor token, a security token that represents the identity of the acting party. The acting party is authorized to use the requested security token and act on behalf of the subject.
string actor_token_type = 9
Type of the actor token.
message
grpc_service.proto:234Channel arguments.
Used in:
map<string, > args = 1
See grpc_types.h GRPC_ARG #defines for keys that work here.
message
grpc_service.proto:235Used in:
oneof value_specifier
Pointer values are not supported, since they don't make any sense when delivered via the API.
string string_value = 1
int64 int_value = 2
message
grpc_service.proto:96See https://grpc.io/docs/guides/auth.html#credential-types to understand Channel and Call credential types.
Used in:
oneof credential_specifier
ssl_credentials = 1
google_default = 2
https://grpc.io/grpc/cpp/namespacegrpc.html#a6beb3ac70ff94bd2ebbd89b8f21d1f61
local_credentials = 3
message
grpc_service.proto:89Local channel credentials. Only UDS is supported for now. See https://github.com/grpc/grpc/pull/15909.
Used in:
(message has no fields)
message
grpc_service.proto:73See https://grpc.io/grpc/cpp/structgrpc_1_1_ssl_credentials_options.html.
Used in:
optional root_certs = 1
PEM encoded server root certificates.
optional private_key = 2
PEM encoded client private key.
optional cert_chain = 3
PEM encoded client certificate chain.
message
base.proto:484Wrapper for a set of headers.
Used in: , , , ,
repeated headers = 1
A list of header names and their values.
message
base.proto:400Header name/value pair.
Used in: , , , , , ,
string key = 1
Header name.
string value = 2
Header value. The same :ref:`format specifier <config_access_log_format>` as used for :ref:`HTTP access logging <config_access_log>` applies here, however unknown header values are replaced with the empty string instead of ``-``. Header value is encoded as string. This does not work for non-utf8 characters. Only one of ``value`` or ``raw_value`` can be set.
bytes raw_value = 3
Header value is encoded as bytes which can support non-utf8 characters. Only one of ``value`` or ``raw_value`` can be set.
message
base.proto:429Header name/value pair plus option to control append behavior.
Used in: , , , , , , , , , , , , , , , , , , ,
optional header = 1
Header name/value pair that this option applies to.
optional append = 2
Should the value be appended? If true (default), the value is appended to existing values. Otherwise it replaces any existing values. This field is deprecated and please use :ref:`append_action <envoy_v3_api_field_config.core.v3.HeaderValueOption.append_action>` as replacement. .. note:: The :ref:`external authorization service <envoy_v3_api_msg_service.auth.v3.CheckResponse>` and :ref:`external processor service <envoy_v3_api_msg_service.ext_proc.v3.ProcessingResponse>` have default value (``false``) for this field.
HeaderValueOption.HeaderAppendAction append_action = 3
Describes the action taken to append/overwrite the given value for an existing header or to only add this header if it's absent. Value defaults to :ref:`APPEND_IF_EXISTS_OR_ADD <envoy_v3_api_enum_value_config.core.v3.HeaderValueOption.HeaderAppendAction.APPEND_IF_EXISTS_OR_ADD>`.
bool keep_empty_value = 4
Is the header value allowed to be empty? If false (default), custom headers with empty values are dropped, otherwise they are added.
Describes the supported actions types for header append action.
Used in:
APPEND_IF_EXISTS_OR_ADD = 0
If the header already exists, this action will result in: - Comma-concatenated for predefined inline headers. - Duplicate header added in the ``HeaderMap`` for other headers. If the header doesn't exist then this will add new header with specified key and value.
ADD_IF_ABSENT = 1
This action will add the header if it doesn't already exist. If the header already exists then this will be a no-op.
OVERWRITE_IF_EXISTS_OR_ADD = 2
This action will overwrite the specified value by discarding any existing values if the header already exists. If the header doesn't exist then this will add the header with specified key and value.
OVERWRITE_IF_EXISTS = 3
This action will overwrite the specified value by discarding any existing values if the header already exists. If the header doesn't exist then this will be no-op.
message
health_check.proto:67[#next-free-field: 27]
Used in: ,
optional timeout = 1
The time to wait for a health check response. If the timeout is reached the health check attempt will be considered a failure.
optional interval = 2
The interval between health checks.
optional initial_jitter = 20
An optional jitter amount in milliseconds. If specified, Envoy will start health checking after for a random time in ms between 0 and initial_jitter. This only applies to the first health check.
optional interval_jitter = 3
An optional jitter amount in milliseconds. If specified, during every interval Envoy will add interval_jitter to the wait time.
uint32 interval_jitter_percent = 18
An optional jitter amount as a percentage of interval_ms. If specified, during every interval Envoy will add ``interval_ms`` * ``interval_jitter_percent`` / 100 to the wait time. If interval_jitter_ms and interval_jitter_percent are both set, both of them will be used to increase the wait time.
optional unhealthy_threshold = 4
The number of unhealthy health checks required before a host is marked unhealthy. Note that for ``http`` health checking if a host responds with a code not in :ref:`expected_statuses <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.expected_statuses>` or :ref:`retriable_statuses <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.retriable_statuses>`, this threshold is ignored and the host is considered immediately unhealthy.
optional healthy_threshold = 5
The number of healthy health checks required before a host is marked healthy. Note that during startup, only a single successful health check is required to mark a host healthy.
optional alt_port = 6
[#not-implemented-hide:] Non-serving port for health checking.
optional reuse_connection = 7
Reuse health check connection between health checks. Default is true.
oneof health_checker
http_health_check = 8
HTTP health check.
tcp_health_check = 9
TCP health check.
grpc_health_check = 11
gRPC health check.
custom_health_check = 13
Custom health check.
optional no_traffic_interval = 12
The "no traffic interval" is a special health check interval that is used when a cluster has never had traffic routed to it. This lower interval allows cluster information to be kept up to date, without sending a potentially large amount of active health checking traffic for no reason. Once a cluster has been used for traffic routing, Envoy will shift back to using the standard health check interval that is defined. Note that this interval takes precedence over any other. The default value for "no traffic interval" is 60 seconds.
optional no_traffic_healthy_interval = 24
The "no traffic healthy interval" is a special health check interval that is used for hosts that are currently passing active health checking (including new hosts) when the cluster has received no traffic. This is useful for when we want to send frequent health checks with ``no_traffic_interval`` but then revert to lower frequency ``no_traffic_healthy_interval`` once a host in the cluster is marked as healthy. Once a cluster has been used for traffic routing, Envoy will shift back to using the standard health check interval that is defined. If no_traffic_healthy_interval is not set, it will default to the no traffic interval and send that interval regardless of health state.
optional unhealthy_interval = 14
The "unhealthy interval" is a health check interval that is used for hosts that are marked as unhealthy. As soon as the host is marked as healthy, Envoy will shift back to using the standard health check interval that is defined. The default value for "unhealthy interval" is the same as "interval".
optional unhealthy_edge_interval = 15
The "unhealthy edge interval" is a special health check interval that is used for the first health check right after a host is marked as unhealthy. For subsequent health checks Envoy will shift back to using either "unhealthy interval" if present or the standard health check interval that is defined. The default value for "unhealthy edge interval" is the same as "unhealthy interval".
optional healthy_edge_interval = 16
The "healthy edge interval" is a special health check interval that is used for the first health check right after a host is marked as healthy. For subsequent health checks Envoy will shift back to using the standard health check interval that is defined. The default value for "healthy edge interval" is the same as the default interval.
string event_log_path = 17
Specifies the path to the :ref:`health check event log <arch_overview_health_check_logging>`. .. attention:: This field is deprecated in favor of the extension :ref:`event_logger <envoy_v3_api_field_config.core.v3.HealthCheck.event_logger>` and :ref:`event_log_path <envoy_v3_api_field_extensions.health_check.event_sinks.file.v3.HealthCheckEventFileSink.event_log_path>` in the file sink extension.
repeated event_logger = 25
A list of event log sinks to process the health check event. [#extension-category: envoy.health_check.event_sinks]
optional event_service = 22
[#not-implemented-hide:] The gRPC service for the health check event service. If empty, health check events won't be sent to a remote endpoint.
bool always_log_health_check_failures = 19
If set to true, health check failure events will always be logged. If set to false, only the initial health check failure event will be logged. The default value is false.
bool always_log_health_check_success = 26
If set to true, health check success events will always be logged. If set to false, only host addition event will be logged if it is the first successful health check, or if the healthy threshold is reached. The default value is false.
optional tls_options = 21
This allows overriding the cluster TLS settings, just for health check connections.
optional transport_socket_match_criteria = 23
Optional key/value pairs that will be used to match a transport socket from those specified in the cluster's :ref:`tranport socket matches <envoy_v3_api_field_config.cluster.v3.Cluster.transport_socket_matches>`. For example, the following match criteria .. code-block:: yaml transport_socket_match_criteria: useMTLS: true Will match the following :ref:`cluster socket match <envoy_v3_api_msg_config.cluster.v3.Cluster.TransportSocketMatch>` .. code-block:: yaml transport_socket_matches: - name: "useMTLS" match: useMTLS: true transport_socket: name: envoy.transport_sockets.tls config: { ... } # tls socket configuration If this field is set, then for health checks it will supersede an entry of ``envoy.transport_socket`` in the :ref:`LbEndpoint.Metadata <envoy_v3_api_field_config.endpoint.v3.LbEndpoint.metadata>`. This allows using different transport socket capabilities for health checking versus proxying to the endpoint. If the key/values pairs specified do not match any :ref:`transport socket matches <envoy_v3_api_field_config.cluster.v3.Cluster.transport_socket_matches>`, the cluster's :ref:`transport socket <envoy_v3_api_field_config.cluster.v3.Cluster.transport_socket>` will be used for health check socket configuration.
message
health_check.proto:231Custom health check.
Used in:
string name = 1
The registered name of the custom health checker.
oneof config_type
A custom health checker specific configuration which depends on the custom health checker being instantiated. See :api:`envoy/config/health_checker` for reference. [#extension-category: envoy.health_checkers]
typed_config = 3
message
health_check.proto:205`grpc.health.v1.Health <https://github.com/grpc/grpc/blob/master/src/proto/grpc/health/v1/health.proto>`_-based healthcheck. See `gRPC doc <https://github.com/grpc/grpc/blob/master/doc/health-checking.md>`_ for details.
Used in:
string service_name = 1
An optional service name parameter which will be sent to gRPC service in `grpc.health.v1.HealthCheckRequest <https://github.com/grpc/grpc/blob/master/src/proto/grpc/health/v1/health.proto#L20>`_. message. See `gRPC health-checking overview <https://github.com/grpc/grpc/blob/master/doc/health-checking.md>`_ for more information.
string authority = 2
The value of the :authority header in the gRPC health check request. If left empty (default value), the name of the cluster this health check is associated with will be used. The authority header can be customized for a specific endpoint by setting the :ref:`hostname <envoy_v3_api_field_config.endpoint.v3.Endpoint.HealthCheckConfig.hostname>` field.
repeated initial_metadata = 3
Specifies a list of key-value pairs that should be added to the metadata of each GRPC call that is sent to the health checked cluster. For more information, including details on header value syntax, see the documentation on :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
message
health_check.proto:87[#next-free-field: 15]
Used in:
string host = 1
The value of the host header in the HTTP health check request. If left empty (default value), the name of the cluster this health check is associated with will be used. The host header can be customized for a specific endpoint by setting the :ref:`hostname <envoy_v3_api_field_config.endpoint.v3.Endpoint.HealthCheckConfig.hostname>` field.
string path = 2
Specifies the HTTP path that will be requested during health checking. For example ``/healthcheck``.
optional send = 3
[#not-implemented-hide:] HTTP specific payload.
repeated receive = 4
Specifies a list of HTTP expected responses to match in the first ``response_buffer_size`` bytes of the response body. If it is set, both the expected response check and status code determine the health check. When checking the response, “fuzzy” matching is performed such that each payload block must be found, and in the order specified, but not necessarily contiguous. .. note:: It is recommended to set ``response_buffer_size`` based on the total Payload size for efficiency. The default buffer size is 1024 bytes when it is not set.
optional response_buffer_size = 14
Specifies the size of response buffer in bytes that is used to Payload match. The default value is 1024. Setting to 0 implies that the Payload will be matched against the entire response.
repeated request_headers_to_add = 6
Specifies a list of HTTP headers that should be added to each request that is sent to the health checked cluster. For more information, including details on header value syntax, see the documentation on :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
repeated string request_headers_to_remove = 8
Specifies a list of HTTP headers that should be removed from each request that is sent to the health checked cluster.
repeated expected_statuses = 9
Specifies a list of HTTP response statuses considered healthy. If provided, replaces default 200-only policy - 200 must be included explicitly as needed. Ranges follow half-open semantics of :ref:`Int64Range <envoy_v3_api_msg_type.v3.Int64Range>`. The start and end of each range are required. Only statuses in the range [100, 600) are allowed.
repeated retriable_statuses = 12
Specifies a list of HTTP response statuses considered retriable. If provided, responses in this range will count towards the configured :ref:`unhealthy_threshold <envoy_v3_api_field_config.core.v3.HealthCheck.unhealthy_threshold>`, but will not result in the host being considered immediately unhealthy. Ranges follow half-open semantics of :ref:`Int64Range <envoy_v3_api_msg_type.v3.Int64Range>`. The start and end of each range are required. Only statuses in the range [100, 600) are allowed. The :ref:`expected_statuses <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.expected_statuses>` field takes precedence for any range overlaps with this field i.e. if status code 200 is both retriable and expected, a 200 response will be considered a successful health check. By default all responses not in :ref:`expected_statuses <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.expected_statuses>` will result in the host being considered immediately unhealthy i.e. if status code 200 is expected and there are no configured retriable statuses, any non-200 response will result in the host being marked unhealthy.
type.v3.CodecClientType codec_client_type = 10
Use specified application protocol for health checks.
optional service_name_matcher = 11
An optional service name parameter which is used to validate the identity of the health checked cluster using a :ref:`StringMatcher <envoy_v3_api_msg_type.matcher.v3.StringMatcher>`. See the :ref:`architecture overview <arch_overview_health_checking_identity>` for more information.
RequestMethod method = 13
HTTP Method that will be used for health checking, default is "GET". GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE, PATCH methods are supported, but making request body is not supported. CONNECT method is disallowed because it is not appropriate for health check request. If a non-200 response is expected by the method, it needs to be set in :ref:`expected_statuses <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.expected_statuses>`.
message
health_check.proto:71Describes the encoding of the payload bytes in the payload.
Used in: ,
oneof payload
string text = 1
Hex encoded payload. E.g., "000000FF".
bytes binary = 2
Binary payload.
message
health_check.proto:190string key = 1
If set, optionally perform ``EXISTS <key>`` instead of ``PING``. A return value from Redis of 0 (does not exist) is considered a passing healthcheck. A return value other than 0 is considered a failure. This allows the user to mark a Redis instance for maintenance by setting the specified key to any value and waiting for traffic to drain.
message
health_check.proto:170Used in:
optional send = 1
Empty payloads imply a connect-only health check.
repeated receive = 2
When checking the response, “fuzzy” matching is performed such that each payload block must be found, and in the order specified, but not necessarily contiguous.
optional proxy_protocol_config = 3
When setting this value, it tries to attempt health check request with ProxyProtocol. When ``send`` is presented, they are sent after preceding ProxyProtocol header. Only ProxyProtocol header is sent when ``send`` is not presented. It allows to use both ProxyProtocol V1 and V2. In V1, it presents L3/L4. In V2, it includes LOCAL command and doesn't include L3/L4.
message
health_check.proto:254Health checks occur over the transport socket specified for the cluster. This implies that if a cluster is using a TLS-enabled transport socket, the health check will also occur over TLS. This allows overriding the cluster TLS settings, just for health check connections.
Used in:
repeated string alpn_protocols = 1
Specifies the ALPN protocols for health check connections. This is useful if the corresponding upstream is using ALPN-based :ref:`FilterChainMatch <envoy_v3_api_msg_config.listener.v3.FilterChainMatch>` along with different protocols for health checks versus data connections. If empty, no ALPN protocols will be set on health check connections.
Endpoint health status.
Used in: , , ,
UNKNOWN = 0
The health status is not known. This is interpreted by Envoy as ``HEALTHY``.
HEALTHY = 1
Healthy.
UNHEALTHY = 2
Unhealthy.
DRAINING = 3
Connection draining in progress. E.g., `<https://aws.amazon.com/blogs/aws/elb-connection-draining-remove-instances-from-service-with-care/>`_ or `<https://cloud.google.com/compute/docs/load-balancing/enabling-connection-draining>`_. This is interpreted by Envoy as ``UNHEALTHY``.
TIMEOUT = 4
Health check timed out. This is part of HDS and is interpreted by Envoy as ``UNHEALTHY``.
DEGRADED = 5
Degraded.
message
health_check.proto:60Used in:
repeated HealthStatus statuses = 1
An order-independent set of health status.
message
protocol.proto:310[#next-free-field: 12]
Used in: , , , ,
optional allow_absolute_url = 1
Handle HTTP requests with absolute URLs in the requests. These requests are generally sent by clients to forward/explicit proxies. This allows clients to configure envoy as their HTTP proxy. In Unix, for example, this is typically done by setting the ``http_proxy`` environment variable.
bool accept_http_10 = 2
Handle incoming HTTP/1.0 and HTTP 0.9 requests. This is off by default, and not fully standards compliant. There is support for pre-HTTP/1.1 style connect logic, dechunking, and handling lack of client host iff ``default_host_for_http_10`` is configured.
string default_host_for_http_10 = 3
A default host for HTTP/1.0 requests. This is highly suggested if ``accept_http_10`` is true as Envoy does not otherwise support HTTP/1.0 without a Host header. This is a no-op if ``accept_http_10`` is not true.
optional header_key_format = 4
Describes how the keys for response headers should be formatted. By default, all header keys are lower cased.
bool enable_trailers = 5
Enables trailers for HTTP/1. By default the HTTP/1 codec drops proxied trailers. .. attention:: Note that this only happens when Envoy is chunk encoding which occurs when: - The request is HTTP/1.1. - Is neither a HEAD only request nor a HTTP Upgrade. - Not a response to a HEAD request. - The content length header is not present.
bool allow_chunked_length = 6
Allows Envoy to process requests/responses with both ``Content-Length`` and ``Transfer-Encoding`` headers set. By default such messages are rejected, but if option is enabled - Envoy will remove Content-Length header and process message. See `RFC7230, sec. 3.3.3 <https://tools.ietf.org/html/rfc7230#section-3.3.3>`_ for details. .. attention:: Enabling this option might lead to request smuggling vulnerability, especially if traffic is proxied via multiple layers of proxies. [#comment:TODO: This field is ignored when the :ref:`header validation configuration <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.typed_header_validation_config>` is present.]
optional override_stream_error_on_invalid_http_message = 7
Allows invalid HTTP messaging. When this option is false, then Envoy will terminate HTTP/1.1 connections upon receiving an invalid HTTP message. However, when this option is true, then Envoy will leave the HTTP/1.1 connection open where possible. If set, this overrides any HCM :ref:`stream_error_on_invalid_http_messaging <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>`.
bool send_fully_qualified_url = 8
Allows sending fully qualified URLs when proxying the first line of the response. By default, Envoy will only send the path components in the first line. If this is true, Envoy will create a fully qualified URI composing scheme (inferred if not present), host (from the host/:authority header) and path (from first line or :path header).
optional use_balsa_parser = 9
[#not-implemented-hide:] Hiding so that field can be removed after BalsaParser is rolled out. If set, force HTTP/1 parser: BalsaParser if true, http-parser if false. If unset, HTTP/1 parser is selected based on envoy.reloadable_features.http1_use_balsa_parser. See issue #21245.
bool allow_custom_methods = 10
[#not-implemented-hide:] Hiding so that field can be removed. If true, and BalsaParser is used (either `use_balsa_parser` above is true, or `envoy.reloadable_features.http1_use_balsa_parser` is true and `use_balsa_parser` is unset), then every non-empty method with only valid characters is accepted. Otherwise, methods not on the hard-coded list are rejected. Once UHV is enabled, this field should be removed, and BalsaParser should allow any method. UHV validates the method, rejecting empty string or invalid characters, and provides :ref:`restrict_http_methods <envoy_v3_api_field_extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.restrict_http_methods>` to reject custom methods.
repeated ignore_http_11_upgrade = 11
Ignore HTTP/1.1 upgrade values matching any of the supplied matchers. .. note:: ``h2c`` upgrades are always removed for backwards compatibility, regardless of the value in this setting.
message
protocol.proto:315[#next-free-field: 9]
Used in:
oneof header_format
proper_case_words = 1
Formats the header by proper casing words: the first character and any character following a special character will be capitalized if it's an alpha character. For example, "content-type" becomes "Content-Type", and "foo$b#$are" becomes "Foo$B#$Are". Note that while this results in most headers following conventional casing, certain headers are not covered. For example, the "TE" header will be formatted as "Te".
stateful_formatter = 8
Configuration for stateful formatter extensions that allow using received headers to affect the output of encoding headers. E.g., preserving case during proxying. [#extension-category: envoy.http.stateful_header_formatters]
message
protocol.proto:319Used in:
(message has no fields)
message
protocol.proto:462[#next-free-field: 18]
Used in: , , , , ,
optional hpack_table_size = 1
`Maximum table size <https://httpwg.org/specs/rfc7541.html#rfc.section.4.2>`_ (in octets) that the encoder is permitted to use for the dynamic HPACK table. Valid values range from 0 to 4294967295 (2^32 - 1) and defaults to 4096. 0 effectively disables header compression.
optional max_concurrent_streams = 2
`Maximum concurrent streams <https://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2>`_ allowed for peer on one HTTP/2 connection. Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 2147483647. For upstream connections, this also limits how many streams Envoy will initiate concurrently on a single connection. If the limit is reached, Envoy may queue requests or establish additional connections (as allowed per circuit breaker limits). This acts as an upper bound: Envoy will lower the max concurrent streams allowed on a given connection based on upstream settings. Config dumps will reflect the configured upper bound, not the per-connection negotiated limits.
optional initial_stream_window_size = 3
`Initial stream-level flow-control window <https://httpwg.org/specs/rfc7540.html#rfc.section.6.9.2>`_ size. Valid values range from 65535 (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to 268435456 (256 * 1024 * 1024). NOTE: 65535 is the initial window size from HTTP/2 spec. We only support increasing the default window size now, so it's also the minimum. This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to stop the flow of data to the codec buffers.
optional initial_connection_window_size = 4
Similar to ``initial_stream_window_size``, but for connection-level flow-control window. Currently, this has the same minimum/maximum/default as ``initial_stream_window_size``.
bool allow_connect = 5
Allows proxying Websocket and other upgrades over H2 connect.
bool allow_metadata = 6
[#not-implemented-hide:] Hiding until Envoy has full metadata support. Still under implementation. DO NOT USE. Allows sending and receiving HTTP/2 METADATA frames. See [metadata docs](https://github.com/envoyproxy/envoy/blob/main/source/docs/h2_metadata.md) for more information.
optional max_outbound_frames = 7
Limit the number of pending outbound downstream frames of all types (frames that are waiting to be written into the socket). Exceeding this limit triggers flood mitigation and connection is terminated. The ``http2.outbound_flood`` stat tracks the number of terminated connections due to flood mitigation. The default limit is 10000.
optional max_outbound_control_frames = 8
Limit the number of pending outbound downstream frames of types PING, SETTINGS and RST_STREAM, preventing high memory utilization when receiving continuous stream of these frames. Exceeding this limit triggers flood mitigation and connection is terminated. The ``http2.outbound_control_flood`` stat tracks the number of terminated connections due to flood mitigation. The default limit is 1000.
optional max_consecutive_inbound_frames_with_empty_payload = 9
Limit the number of consecutive inbound frames of types HEADERS, CONTINUATION and DATA with an empty payload and no end stream flag. Those frames have no legitimate use and are abusive, but might be a result of a broken HTTP/2 implementation. The `http2.inbound_empty_frames_flood`` stat tracks the number of connections terminated due to flood mitigation. Setting this to 0 will terminate connection upon receiving first frame with an empty payload and no end stream flag. The default limit is 1.
optional max_inbound_priority_frames_per_stream = 10
Limit the number of inbound PRIORITY frames allowed per each opened stream. If the number of PRIORITY frames received over the lifetime of connection exceeds the value calculated using this formula:: ``max_inbound_priority_frames_per_stream`` * (1 + ``opened_streams``) the connection is terminated. For downstream connections the ``opened_streams`` is incremented when Envoy receives complete response headers from the upstream server. For upstream connection the ``opened_streams`` is incremented when Envoy send the HEADERS frame for a new stream. The ``http2.inbound_priority_frames_flood`` stat tracks the number of connections terminated due to flood mitigation. The default limit is 100.
optional max_inbound_window_update_frames_per_data_frame_sent = 11
Limit the number of inbound WINDOW_UPDATE frames allowed per DATA frame sent. If the number of WINDOW_UPDATE frames received over the lifetime of connection exceeds the value calculated using this formula:: 5 + 2 * (``opened_streams`` + ``max_inbound_window_update_frames_per_data_frame_sent`` * ``outbound_data_frames``) the connection is terminated. For downstream connections the ``opened_streams`` is incremented when Envoy receives complete response headers from the upstream server. For upstream connections the ``opened_streams`` is incremented when Envoy sends the HEADERS frame for a new stream. The ``http2.inbound_priority_frames_flood`` stat tracks the number of connections terminated due to flood mitigation. The default max_inbound_window_update_frames_per_data_frame_sent value is 10. Setting this to 1 should be enough to support HTTP/2 implementations with basic flow control, but more complex implementations that try to estimate available bandwidth require at least 2.
bool stream_error_on_invalid_http_messaging = 12
Allows invalid HTTP messaging and headers. When this option is disabled (default), then the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However, when this option is enabled, only the offending stream is terminated. This is overridden by HCM :ref:`stream_error_on_invalid_http_messaging <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>` iff present. This is deprecated in favor of :ref:`override_stream_error_on_invalid_http_message <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.override_stream_error_on_invalid_http_message>` See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details.
optional override_stream_error_on_invalid_http_message = 14
Allows invalid HTTP messaging and headers. When this option is disabled (default), then the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However, when this option is enabled, only the offending stream is terminated. This overrides any HCM :ref:`stream_error_on_invalid_http_messaging <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>` See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details.
repeated custom_settings_parameters = 13
[#not-implemented-hide:] Specifies SETTINGS frame parameters to be sent to the peer, with two exceptions: 1. SETTINGS_ENABLE_PUSH (0x2) is not configurable as HTTP/2 server push is not supported by Envoy. 2. SETTINGS_ENABLE_CONNECT_PROTOCOL (0x8) is only configurable through the named field 'allow_connect'. Note that custom parameters specified through this field can not also be set in the corresponding named parameters: .. code-block:: text ID Field Name ---------------- 0x1 hpack_table_size 0x3 max_concurrent_streams 0x4 initial_stream_window_size Collisions will trigger config validation failure on load/update. Likewise, inconsistencies between custom parameters with the same identifier will trigger a failure. See `IANA HTTP/2 Settings <https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml#settings>`_ for standardized identifiers.
optional connection_keepalive = 15
Send HTTP/2 PING frames to verify that the connection is still healthy. If the remote peer does not respond within the configured timeout, the connection will be aborted.
optional use_oghttp2_codec = 16
[#not-implemented-hide:] Hiding so that the field can be removed after oghttp2 is rolled out. If set, force use of a particular HTTP/2 codec: oghttp2 if true, nghttp2 if false. If unset, HTTP/2 codec is selected based on envoy.reloadable_features.http2_use_oghttp2.
optional max_metadata_size = 17
Configure the maximum amount of metadata than can be handled per stream. Defaults to 1 MB.
message
protocol.proto:468Defines a parameter to be sent in the SETTINGS frame. See `RFC7540, sec. 6.5.1 <https://tools.ietf.org/html/rfc7540#section-6.5.1>`_ for details.
Used in:
optional identifier = 1
The 16 bit parameter identifier.
optional value = 2
The 32 bit parameter value.
message
protocol.proto:660A message which allows using HTTP/3. [#next-free-field: 8]
Used in: , , ,
optional quic_protocol_options = 1
optional override_stream_error_on_invalid_http_message = 2
Allows invalid HTTP messaging and headers. When this option is disabled (default), then the whole HTTP/3 connection is terminated upon receiving invalid HEADERS frame. However, when this option is enabled, only the offending stream is terminated. If set, this overrides any HCM :ref:`stream_error_on_invalid_http_messaging <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>`.
bool allow_extended_connect = 5
Allows proxying Websocket and other upgrades over HTTP/3 CONNECT using the header mechanisms from the `HTTP/2 extended connect RFC <https://datatracker.ietf.org/doc/html/rfc8441>`_ and settings `proposed for HTTP/3 <https://datatracker.ietf.org/doc/draft-ietf-httpbis-h3-websockets/>`_ Note that HTTP/3 CONNECT is not yet an RFC.
bool allow_metadata = 6
[#not-implemented-hide:] Hiding until Envoy has full metadata support. Still under implementation. DO NOT USE. Allows sending and receiving HTTP/3 METADATA frames. See [metadata docs](https://github.com/envoyproxy/envoy/blob/main/source/docs/h2_metadata.md) for more information.
bool disable_qpack = 7
[#not-implemented-hide:] Hiding until Envoy has full HTTP/3 upstream support. Still under implementation. DO NOT USE. Disables QPACK compression related features for HTTP/3 including: No huffman encoding, zero dynamic table capacity and no cookie crumbing. This can be useful for trading off CPU vs bandwidth when an upstream HTTP/3 connection multiplexes multiple downstream connections.
message
protocol.proto:217[#next-free-field: 8]
Used in: , ,
optional idle_timeout = 1
The idle timeout for connections. The idle timeout is defined as the period in which there are no active requests. When the idle timeout is reached the connection will be closed. If the connection is an HTTP/2 downstream connection a drain sequence will occur prior to closing the connection, see :ref:`drain_timeout <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.drain_timeout>`. Note that request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. If not specified, this defaults to 1 hour. To disable idle timeouts explicitly set this to 0. .. warning:: Disabling this timeout has a highly likelihood of yielding connection leaks due to lost TCP FIN packets, etc. If the :ref:`overload action <config_overload_manager_overload_actions>` "envoy.overload_actions.reduce_timeouts" is configured, this timeout is scaled for downstream connections according to the value for :ref:`HTTP_DOWNSTREAM_CONNECTION_IDLE <envoy_v3_api_enum_value_config.overload.v3.ScaleTimersOverloadActionConfig.TimerType.HTTP_DOWNSTREAM_CONNECTION_IDLE>`.
optional max_connection_duration = 3
The maximum duration of a connection. The duration is defined as a period since a connection was established. If not set, there is no max duration. When max_connection_duration is reached, the drain sequence will kick-in. The connection will be closed after the drain timeout period if there are no active streams. See :ref:`drain_timeout <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.drain_timeout>`.
optional max_headers_count = 2
The maximum number of headers (request headers if configured on HttpConnectionManager, response headers when configured on a cluster). If unconfigured, the default maximum number of headers allowed is 100. The default value for requests can be overridden by setting runtime key ``envoy.reloadable_features.max_request_headers_count``. The default value for responses can be overridden by setting runtime key ``envoy.reloadable_features.max_response_headers_count``. Downstream requests that exceed this limit will receive a 431 response for HTTP/1.x and cause a stream reset for HTTP/2. Upstream responses that exceed this limit will result in a 503 response.
optional max_response_headers_kb = 7
The maximum size of response headers. If unconfigured, the default is 60 KiB, except for HTTP/1 response headers which have a default of 80KiB. The default value can be overridden by setting runtime key ``envoy.reloadable_features.max_response_headers_size_kb``. Responses that exceed this limit will result in a 503 response. In Envoy, this setting is only valid when configured on an upstream cluster, not on the :ref:`HTTP Connection Manager <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.common_http_protocol_options>`. Note: currently some protocol codecs impose limits on the maximum size of a single header: HTTP/2 (when using nghttp2) limits a single header to around 100kb. HTTP/3 limits a single header to around 1024kb.
optional max_stream_duration = 4
Total duration to keep alive an HTTP request/response stream. If the time limit is reached the stream will be reset independent of any other timeouts. If not specified, this value is not set.
HttpProtocolOptions.HeadersWithUnderscoresAction headers_with_underscores_action = 5
Action to take when a client request with a header name containing underscore characters is received. If this setting is not specified, the value defaults to ALLOW. Note: upstream responses are not affected by this setting. Note: this only affects client headers. It does not affect headers added by Envoy filters and does not have any impact if added to cluster config.
optional max_requests_per_connection = 6
Optional maximum requests for both upstream and downstream connections. If not specified, there is no limit. Setting this parameter to 1 will effectively disable keep alive. For HTTP/2 and HTTP/3, due to concurrent stream processing, the limit is approximate.
Action to take when Envoy receives client request with header names containing underscore characters. Underscore character is allowed in header names by the RFC-7230 and this behavior is implemented as a security measure due to systems that treat '_' and '-' as interchangeable. Envoy by default allows client request headers with underscore characters.
Used in:
ALLOW = 0
Allow headers with underscores. This is the default behavior.
REJECT_REQUEST = 1
Reject client request. HTTP/1 requests are rejected with the 400 status. HTTP/2 requests end with the stream reset. The "httpN.requests_rejected_with_underscores_in_headers" counter is incremented for each rejected request.
DROP_HEADER = 2
Drop 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. The "httpN.dropped_headers_with_underscores" is incremented for each dropped header.
message
http_service.proto:20HTTP service configuration.
Used in: , ,
optional http_uri = 1
The service's HTTP URI. For example: .. code-block:: yaml http_uri: uri: https://www.myserviceapi.com/v1/data cluster: www.myserviceapi.com|443
repeated request_headers_to_add = 2
Specifies a list of HTTP headers that should be added to each request handled by this virtual host.
message
http_uri.proto:20Envoy external URI descriptor
Used in: , , , , , ,
string uri = 1
The HTTP server URI. It should be a full FQDN with protocol, host and path. Example: .. code-block:: yaml uri: https://www.googleapis.com/oauth2/v1/certs
oneof http_upstream_type
Specify how ``uri`` is to be fetched. Today, this requires an explicit cluster, but in the future we may support dynamic cluster creation or inline DNS resolution. See `issue <https://github.com/envoyproxy/envoy/issues/1606>`_.
string cluster = 2
A cluster is created in the Envoy "cluster_manager" config section. This field specifies the cluster name. Example: .. code-block:: yaml cluster: jwks_cluster
optional timeout = 3
Sets the maximum duration in milliseconds that a response can take to arrive upon request.
Optional configuration options to be used with json_format.
Used in:
bool sort_properties = 1
The output JSON string properties will be sorted. .. note:: As the properties are always sorted, this option has no effect and is deprecated.
message
protocol.proto:431Used in:
optional interval = 1
Send HTTP/2 PING frames at this period, in order to test that the connection is still alive. If this is zero, interval PINGs will not be sent.
optional timeout = 2
How long to wait for a response to a keepalive PING. If a response is not received within this time period, the connection will be aborted. Note that in order to prevent the influence of Head-of-line (HOL) blocking the timeout period is extended when *any* frame is received on the connection, under the assumption that if a frame is received the connection is healthy.
optional interval_jitter = 3
A random jitter amount as a percentage of interval that will be added to each interval. A value of zero means there will be no jitter. The default value is 15%.
optional connection_idle_interval = 4
If the connection has been idle for this duration, send a HTTP/2 ping ahead of new stream creation, to quickly detect dead connections. If this is zero, this type of PING will not be sent. If an interval ping is outstanding, a second ping will not be sent as the interval ping will determine if the connection is dead. The same feature for HTTP/3 is given by inheritance from QUICHE which uses :ref:`connection idle_timeout <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.idle_timeout>` and the current PTO of the connection to decide whether to probe before sending a new request.
message
base.proto:308Please use :ref:`KeyValuePair <envoy_api_msg_config.core.v3.KeyValuePair>` instead. [#not-implemented-hide:]
Used in:
string key = 1
The key of the key/value pair.
bytes value = 2
The value of the key/value pair. The ``bytes`` type is used. This means if JSON or YAML is used to to represent the configuration, the value must be base64 encoded. This is unfriendly for users in most use scenarios of this message.
message
base.proto:335Key/value pair plus option to control append behavior. This is used to specify key/value pairs that should be appended to a set of existing key/value pairs.
Used in:
optional record = 3
The single key/value pair record to be appended or overridden. This field must be set.
optional entry = 1
Key/value pair entry that this option to append or overwrite. This field is deprecated and please use :ref:`record <envoy_v3_api_field_config.core.v3.KeyValueAppend.record>` as replacement. [#not-implemented-hide:]
KeyValueAppend.KeyValueAppendAction action = 2
Describes the action taken to append/overwrite the given value for an existing key or to only add this key if it's absent.
Describes the supported actions types for key/value pair append action.
Used in:
APPEND_IF_EXISTS_OR_ADD = 0
If the key already exists, this action will result in the following behavior: - Comma-concatenated value if multiple values are not allowed. - New value added to the list of values if multiple values are allowed. If the key doesn't exist then this will add pair with specified key and value.
ADD_IF_ABSENT = 1
This action will add the key/value pair if it doesn't already exist. If the key already exists then this will be a no-op.
OVERWRITE_IF_EXISTS_OR_ADD = 2
This action will overwrite the specified value by discarding any existing values if the key already exists. If the key doesn't exist then this will add the pair with specified key and value.
OVERWRITE_IF_EXISTS = 3
This action will overwrite the specified value by discarding any existing values if the key already exists. If the key doesn't exist then this will be no-op.
message
base.proto:380Key/value pair to append or remove.
Used in:
optional append = 1
Key/value pair to append or overwrite. Only one of ``append`` or ``remove`` can be set or the configuration will be rejected.
string remove = 2
Key to remove. Only one of ``append`` or ``remove`` can be set or the configuration will be rejected.
message
base.proto:325Used in:
string key = 1
The key of the key/value pair.
optional value = 2
The value of the key/value pair.
message
base.proto:70Identifies location of where either Envoy runs or where upstream hosts run.
Used in: , , , , , ,
string region = 1
Region this :ref:`zone <envoy_v3_api_field_config.core.v3.Locality.zone>` belongs to.
string zone = 2
Defines the local service zone where Envoy is running. Though optional, it should be set if discovery service routing is used and the discovery service exposes :ref:`zone data <envoy_v3_api_field_config.endpoint.v3.LocalityLbEndpoints.locality>`, either in this message or via :option:`--service-zone`. The meaning of zone is context dependent, e.g. `Availability Zone (AZ) <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html>`_ on AWS, `Zone <https://cloud.google.com/compute/docs/regions-zones/>`_ on GCP, etc.
string sub_zone = 3
When used for locality of upstream hosts, this field further splits zone into smaller chunks of sub-zones so they can be load balanced independently.
message
base.proto:239Metadata provides additional inputs to filters based on matched listeners, filter chains, routes and endpoints. It is structured as a map, usually from filter name (in reverse DNS format) to metadata specific to the filter. Metadata key-values for a filter are merged as connection and request handling occurs, with later values for the same key overriding earlier values. An example use of metadata is providing additional values to http_connection_manager in the envoy.http_connection_manager.access_log namespace. Another example use of metadata is to per service config info in cluster metadata, which may get consumed by multiple filters. For load balancing, Metadata provides a means to subset cluster endpoints. Endpoints have a Metadata object associated and routes contain a Metadata object to match against. There are some well defined metadata used today for this purpose: * ``{"envoy.lb": {"canary": <bool> }}`` This indicates the canary status of an endpoint and is also used during header processing (x-envoy-upstream-canary) and for stats purposes. [#next-major-version: move to type/metadata/v2]
Used in: , , , , , , , , , , , , , , , , , , , , , ,
map<string, > filter_metadata = 1
Key is the reverse DNS filter name, e.g. com.acme.widget. The ``envoy.*`` namespace is reserved for Envoy's built-in filters. If both ``filter_metadata`` and :ref:`typed_filter_metadata <envoy_v3_api_field_config.core.v3.Metadata.typed_filter_metadata>` fields are present in the metadata with same keys, only ``typed_filter_metadata`` field will be parsed.
map<string, > typed_filter_metadata = 2
Key is the reverse DNS filter name, e.g. com.acme.widget. The ``envoy.*`` namespace is reserved for Envoy's built-in filters. The value is encoded as google.protobuf.Any. If both :ref:`filter_metadata <envoy_v3_api_field_config.core.v3.Metadata.filter_metadata>` and ``typed_filter_metadata`` fields are present in the metadata with same keys, only ``typed_filter_metadata`` field will be parsed.
message
base.proto:143Identifies a specific Envoy instance. The node identifier is presented to the management server, which may use this identifier to distinguish per Envoy configuration for serving. [#next-free-field: 13]
Used in: , , , , , , , , , , ,
string id = 1
An opaque node identifier for the Envoy node. This also provides the local service node name. It should be set if any of the following features are used: :ref:`statsd <arch_overview_statistics>`, :ref:`CDS <config_cluster_manager_cds>`, and :ref:`HTTP tracing <arch_overview_tracing>`, either in this message or via :option:`--service-node`.
string cluster = 2
Defines the local service cluster name where Envoy is running. Though optional, it should be set if any of the following features are used: :ref:`statsd <arch_overview_statistics>`, :ref:`health check cluster verification <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.service_name_matcher>`, :ref:`runtime override directory <envoy_v3_api_msg_config.bootstrap.v3.Runtime>`, :ref:`user agent addition <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.add_user_agent>`, :ref:`HTTP global rate limiting <config_http_filters_rate_limit>`, :ref:`CDS <config_cluster_manager_cds>`, and :ref:`HTTP tracing <arch_overview_tracing>`, either in this message or via :option:`--service-cluster`.
optional metadata = 3
Opaque metadata extending the node identifier. Envoy will pass this directly to the management server.
map<string, > dynamic_parameters = 12
Map from xDS resource type URL to dynamic context parameters. These may vary at runtime (unlike other fields in this message). For example, the xDS client may have a shard identifier that changes during the lifetime of the xDS client. In Envoy, this would be achieved by updating the dynamic context on the Server::Instance's LocalInfo context provider. The shard ID dynamic parameter then appears in this field during future discovery requests.
optional locality = 4
Locality specifying where the Envoy instance is running.
string user_agent_name = 6
Free-form string that identifies the entity requesting config. E.g. "envoy" or "grpc"
oneof user_agent_version_type
string user_agent_version = 7
Free-form string that identifies the version of the entity requesting config. E.g. "1.12.2" or "abcd1234", or "SpecialEnvoyBuild"
user_agent_build_version = 8
Structured version of the entity requesting config.
repeated extensions = 9
List of extensions and their versions supported by the node.
repeated string client_features = 10
Client feature support list. These are well known features described in the Envoy API repository for a given major version of an API. Client features use reverse DNS naming scheme, for example ``com.acme.feature``. See :ref:`the list of features <client_features>` that xDS client may support.
repeated listening_addresses = 11
Known listening ports on the node as a generic hint to the management server for filtering :ref:`listeners <config_listeners>` to be returned. For example, if there is a listener bound to port 80, the list can optionally contain the SocketAddress ``(0.0.0.0,80)``. The field is optional and just a hint.
message
config_source.proto:159Local filesystem path configuration source.
Used in:
string path = 1
Path on the filesystem to source and watch for configuration updates. When sourcing configuration for a :ref:`secret <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.Secret>`, the certificate and key files are also watched for updates. .. note:: The path to the source must exist at config load time. .. note:: If ``watched_directory`` is *not* configured, Envoy will watch the file path for *moves*. This is because in general only moves are atomic. The same method of swapping files as is demonstrated in the :ref:`runtime documentation <config_runtime_symbolic_link_swap>` can be used here also. If ``watched_directory`` is configured, no watch will be placed directly on this path. Instead, the configured ``watched_directory`` will be used to trigger reloads of this path. This is required in certain deployment scenarios. See below for more information.
optional watched_directory = 2
If configured, this directory will be watched for *moves*. When an entry in this directory is moved to, the ``path`` will be reloaded. This is required in certain deployment scenarios. Specifically, if trying to load an xDS resource using a `Kubernetes ConfigMap <https://kubernetes.io/docs/concepts/configuration/configmap/>`_, the following configuration might be used: 1. Store xds.yaml inside a ConfigMap. 2. Mount the ConfigMap to ``/config_map/xds`` 3. Configure path ``/config_map/xds/xds.yaml`` 4. Configure watched directory ``/config_map/xds`` The above configuration will ensure that Envoy watches the owning directory for moves which is required due to how Kubernetes manages ConfigMap symbolic links during atomic updates.
message
proxy_protocol.proto:87repeated added_tlvs = 1
Enables per-host configuration for Proxy Protocol.
message
address.proto:23Used in:
string path = 1
Unix Domain Socket path. On Linux, paths starting with '@' will use the abstract namespace. The starting '@' is replaced by a null byte by Envoy. Paths starting with '@' will result in an error in environments other than Linux.
uint32 mode = 2
The mode for the Pipe. Not applicable for abstract sockets.
message
proxy_protocol.proto:44Used in: , ,
ProxyProtocolConfig.Version version = 1
The PROXY protocol version to use. See https://www.haproxy.org/download/2.1/doc/proxy-protocol.txt for details
optional pass_through_tlvs = 2
This config controls which TLVs can be passed to upstream if it is Proxy Protocol V2 header. If there is no setting for this field, no TLVs will be passed through.
repeated added_tlvs = 3
This config allows additional TLVs to be included in the upstream PROXY protocol V2 header. Unlike ``pass_through_tlvs``, which passes TLVs from the downstream request, ``added_tlvs`` provides an extension mechanism for defining new TLVs that are included with the upstream request. These TLVs may not be present in the downstream request and can be defined at either the transport socket level or the host level to provide more granular control over the TLVs that are included in the upstream request. Host-level TLVs are specified in the ``metadata.typed_filter_metadata`` field under the ``envoy.transport_sockets.proxy_protocol`` namespace. .. literalinclude:: /_configs/repo/proxy_protocol.yaml :language: yaml :lines: 49-57 :linenos: :lineno-start: 49 :caption: :download:`proxy_protocol.yaml </_configs/repo/proxy_protocol.yaml>` **Precedence behavior**: - When a TLV is defined at both the host level and the transport socket level, the value from the host level configuration takes precedence. This allows users to define default TLVs at the transport socket level and override them at the host level. - Any TLV defined in the ``pass_through_tlvs`` field will be overridden by either the host-level or transport socket-level TLV.
Used in: ,
V1 = 0
PROXY protocol version 1. Human readable format.
V2 = 1
PROXY protocol version 2. Binary format.
message
proxy_protocol.proto:16Used in: ,
ProxyProtocolPassThroughTLVs.PassTLVsMatchType match_type = 1
The strategy to pass through TLVs. Default is INCLUDE_ALL. If INCLUDE_ALL is set, all TLVs will be passed through no matter the tlv_type field.
repeated uint32 tlv_type = 2
The TLV types that are applied based on match_type. TLV type is defined as uint8_t in proxy protocol. See `the spec <https://www.haproxy.org/download/2.1/doc/proxy-protocol.txt>`_ for details.
Used in:
INCLUDE_ALL = 0
Pass all TLVs.
INCLUDE = 1
Pass specific TLVs defined in tlv_type.
message
base.proto:391Query parameter name/value pair.
Used in:
string key = 1
The key of the query parameter. Case sensitive.
string value = 2
The value of the query parameter.
message
protocol.proto:36Config for keepalive probes in a QUIC connection. Note that QUIC keep-alive probing packets work differently from HTTP/2 keep-alive PINGs in a sense that the probing packet itself doesn't timeout waiting for a probing response. Quic has a shorter idle timeout than TCP, so it doesn't rely on such probing to discover dead connections. If the peer fails to respond, the connection will idle timeout eventually. Thus, they are configured differently from :ref:`connection_keepalive <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.connection_keepalive>`.
Used in:
optional max_interval = 1
The max interval for a connection to send keep-alive probing packets (with PING or PATH_RESPONSE). The value should be smaller than :ref:`connection idle_timeout <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.idle_timeout>` to prevent idle timeout while not less than 1s to avoid throttling the connection or flooding the peer with probes. If :ref:`initial_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.initial_interval>` is absent or zero, a client connection will use this value to start probing. If zero, disable keepalive probing. If absent, use the QUICHE default interval to probe.
optional initial_interval = 2
The interval to send the first few keep-alive probing packets to prevent connection from hitting the idle timeout. Subsequent probes will be sent, each one with an interval exponentially longer than previous one, till it reaches :ref:`max_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.max_interval>`. And the probes afterwards will always use :ref:`max_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.max_interval>`. The value should be smaller than :ref:`connection idle_timeout <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.idle_timeout>` to prevent idle timeout and smaller than max_interval to take effect. If absent, disable keepalive probing for a server connection. For a client connection, if :ref:`max_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.max_interval>` is zero, do not keepalive, otherwise use max_interval or QUICHE default to probe all the time.
message
protocol.proto:58QUIC protocol options which apply to both downstream and upstream connections. [#next-free-field: 10]
Used in: ,
optional max_concurrent_streams = 1
Maximum number of streams that the client can negotiate per connection. 100 if not specified.
optional initial_stream_window_size = 2
`Initial stream-level flow-control receive window <https://tools.ietf.org/html/draft-ietf-quic-transport-34#section-4.1>`_ size. Valid values range from 1 to 16777216 (2^24, maximum supported by QUICHE) and defaults to 16777216 (16 * 1024 * 1024). NOTE: 16384 (2^14) is the minimum window size supported in Google QUIC. If configured smaller than it, we will use 16384 instead. QUICHE IETF Quic implementation supports 1 bytes window. We only support increasing the default window size now, so it's also the minimum. This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the QUIC stream send and receive buffers. Once the buffer reaches this pointer, watermark callbacks will fire to stop the flow of data to the stream buffers.
optional initial_connection_window_size = 3
Similar to ``initial_stream_window_size``, but for connection-level flow-control. Valid values rage from 1 to 25165824 (24MB, maximum supported by QUICHE) and defaults to 25165824 (24 * 1024 * 1024). NOTE: 16384 (2^14) is the minimum window size supported in Google QUIC. We only support increasing the default window size now, so it's also the minimum.
optional num_timeouts_to_trigger_port_migration = 4
The number of timeouts that can occur before port migration is triggered for QUIC clients. This defaults to 4. If set to 0, port migration will not occur on path degrading. Timeout here refers to QUIC internal path degrading timeout mechanism, such as PTO. This has no effect on server sessions.
optional connection_keepalive = 5
Probes the peer at the configured interval to solicit traffic, i.e. ACK or PATH_RESPONSE, from the peer to push back connection idle timeout. If absent, use the default keepalive behavior of which a client connection sends PINGs every 15s, and a server connection doesn't do anything.
string connection_options = 6
A comma-separated list of strings representing QUIC connection options defined in `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>`_ and to be sent by upstream connections.
string client_connection_options = 7
A comma-separated list of strings representing QUIC client connection options defined in `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>`_ and to be sent by upstream connections.
optional idle_network_timeout = 8
The duration that a QUIC connection stays idle before it closes itself. If this field is not present, QUICHE default 600s will be applied. For internal corporate network, a long timeout is often fine. But for client facing network, 30s is usually a good choice.
optional max_packet_length = 9
Maximum packet length for QUIC connections. It refers to the largest size of a QUIC packet that can be transmitted over the connection. If not specified, one of the `default values in QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/quic_constants.h>`_ is used.
message
config_source.proto:144Rate Limit settings to be applied for discovery requests made by Envoy.
Used in:
optional max_tokens = 1
Maximum number of tokens to be used for rate limiting discovery request calls. If not set, a default value of 100 will be used.
optional fill_rate = 2
Rate at which tokens will be filled per second. If not set, a default fill rate of 10 tokens per second will be used. The minimal fill rate is once per year. Lower fill rates will be set to once per year.
message
base.proto:583The message specifies how to fetch data from remote and how to verify it.
Used in:
optional http_uri = 1
The HTTP URI to fetch the remote data.
string sha256 = 2
SHA256 string for verifying data.
optional retry_policy = 3
Retry policy for fetching remote data.
HTTP request method.
Used in: ,
METHOD_UNSPECIFIED = 0
GET = 1
HEAD = 2
POST = 3
PUT = 4
DELETE = 5
CONNECT = 6
OPTIONS = 7
TRACE = 8
PATCH = 9
message
base.proto:538The message specifies the retry policy of remote data source when fetching fails. [#next-free-field: 7]
Used in: , , , , , , , ,
optional retry_back_off = 1
Specifies parameters that control :ref:`retry backoff strategy <envoy_v3_api_msg_config.core.v3.BackoffStrategy>`. This parameter is optional, in which case the default base interval is 1000 milliseconds. The default maximum interval is 10 times the base interval.
optional num_retries = 2
Specifies the allowed number of retries. This parameter is optional and defaults to 1.
string retry_on = 3
For details, see :ref:`retry_on <envoy_v3_api_field_config.route.v3.RetryPolicy.retry_on>`.
optional retry_priority = 4
For details, see :ref:`retry_priority <envoy_v3_api_field_config.route.v3.RetryPolicy.retry_priority>`.
repeated retry_host_predicate = 5
For details, see :ref:`RetryHostPredicate <envoy_v3_api_field_config.route.v3.RetryPolicy.retry_host_predicate>`.
int64 host_selection_retry_max_attempts = 6
For details, see :ref:`host_selection_retry_max_attempts <envoy_v3_api_field_config.route.v3.RetryPolicy.host_selection_retry_max_attempts>`.
message
base.proto:551See :ref:`RetryHostPredicate <envoy_v3_api_field_config.route.v3.RetryPolicy.retry_host_predicate>`.
Used in:
string name = 1
oneof config_type
typed_config = 2
message
base.proto:542See :ref:`RetryPriority <envoy_v3_api_field_config.route.v3.RetryPolicy.retry_priority>`.
Used in:
string name = 1
oneof config_type
typed_config = 2
Envoy supports :ref:`upstream priority routing <arch_overview_http_routing_priority>` both at the route and the virtual cluster level. The current priority implementation uses different connection pool and circuit breaking settings for each priority level. This means that even for HTTP/2 requests, two physical connections will be used to an upstream host. In the future Envoy will likely support true HTTP/2 priority over a single upstream connection.
Used in: ,
DEFAULT = 0
HIGH = 1
message
base.proto:282Runtime derived double with a default when not specified.
Used in: , , , ,
double default_value = 1
Default value if runtime value is not available.
string runtime_key = 2
Runtime key to get value for comparison. This value is used if defined.
message
base.proto:293Runtime derived bool with a default when not specified.
Used in: , , , , , , , , , ,
optional default_value = 1
Default value if runtime value is not available.
string runtime_key = 2
Runtime key to get value for comparison. This value is used if defined. The boolean value must be represented via its `canonical JSON encoding <https://developers.google.com/protocol-buffers/docs/proto3#json>`_.
message
base.proto:643Runtime derived FractionalPercent with defaults for when the numerator or denominator is not specified via a runtime key. .. note:: Parsing of the runtime key's data is implemented such that it may be represented as a :ref:`FractionalPercent <envoy_v3_api_msg_type.v3.FractionalPercent>` proto represented as JSON/YAML and may also be represented as an integer with the assumption that the value is an integral percentage out of 100. For instance, a runtime key lookup returning the value "42" would parse as a ``FractionalPercent`` whose numerator is 42 and denominator is HUNDRED.
Used in: , , , , , , , , , , , , , ,
optional default_value = 1
Default value if the runtime value's for the numerator/denominator keys are not available.
string runtime_key = 2
Runtime key for a YAML representation of a FractionalPercent.
message
base.proto:273Runtime derived percentage with a default when not specified.
Used in:
optional default_value = 1
Default value if runtime value is not available.
string runtime_key = 2
Runtime key to get value for comparison. This value is used if defined.
message
base.proto:262Runtime derived uint32 with a default when not specified.
Used in: ,
uint32 default_value = 2
Default value if runtime value is not available.
string runtime_key = 3
Runtime key to get value for comparison. This value is used if defined.
message
protocol.proto:697A message to control transformations to the :scheme header
Used in:
oneof transformation
string scheme_to_overwrite = 1
Overwrite any Scheme header with the contents of this string. If set, takes precedence over match_upstream.
bool match_upstream = 2
Set the Scheme header to match the upstream transport protocol. For example, should a request be sent to the upstream over TLS, the scheme header will be set to "https". Should the request be sent over plaintext, the scheme header will be set to "http". If scheme_to_overwrite is set, this field is not used.
message
config_source.proto:135[#not-implemented-hide:] Self-referencing config source options. This is currently empty, but when set in :ref:`ConfigSource <envoy_v3_api_msg_config.core.v3.ConfigSource>` can be used to specify that other data can be obtained from the same server.
Used in:
ApiVersion transport_api_version = 1
API version for xDS transport protocol. This describes the xDS gRPC/REST endpoint and version of [Delta]DiscoveryRequest/Response used on the wire.
message
address.proto:54[#next-free-field: 8]
Used in: , , , , , ,
SocketAddress.Protocol protocol = 1
string address = 2
The address for this socket. :ref:`Listeners <config_listeners>` will bind to the address. An empty address is not allowed. Specify ``0.0.0.0`` or ``::`` to bind to any address. [#comment:TODO(zuercher) reinstate when implemented: It is possible to distinguish a Listener address via the prefix/suffix matching in :ref:`FilterChainMatch <envoy_v3_api_msg_config.listener.v3.FilterChainMatch>`.] When used within an upstream :ref:`BindConfig <envoy_v3_api_msg_config.core.v3.BindConfig>`, the address controls the source address of outbound connections. For :ref:`clusters <envoy_v3_api_msg_config.cluster.v3.Cluster>`, the cluster type determines whether the address must be an IP (``STATIC`` or ``EDS`` clusters) or a hostname resolved by DNS (``STRICT_DNS`` or ``LOGICAL_DNS`` clusters). Address resolution can be customized via :ref:`resolver_name <envoy_v3_api_field_config.core.v3.SocketAddress.resolver_name>`.
oneof port_specifier
uint32 port_value = 3
string named_port = 4
This is only valid if :ref:`resolver_name <envoy_v3_api_field_config.core.v3.SocketAddress.resolver_name>` is specified below and the named resolver is capable of named port resolution.
string resolver_name = 5
The name of the custom resolver. This must have been registered with Envoy. If this is empty, a context dependent default applies. If the address is a concrete IP address, no resolution will occur. If address is a hostname this should be set for resolution other than DNS. Specifying a custom resolver with ``STRICT_DNS`` or ``LOGICAL_DNS`` will generate an error at runtime.
bool ipv4_compat = 6
When binding to an IPv6 address above, this enables `IPv4 compatibility <https://tools.ietf.org/html/rfc3493#page-11>`_. Binding to ``::`` will allow both IPv4 and IPv6 connections, with peer IPv4 addresses mapped into IPv6 space as ``::FFFF:<IPv4-address>``.
string network_namespace_filepath = 7
The Linux network namespace to bind the socket to. If this is set, Envoy will create the socket in the specified network namespace. Only supported on Linux. [#not-implemented-hide:]
Used in:
TCP = 0
UDP = 1
message
socket_cmsg_headers.proto:19Configuration for socket cmsg headers. See `:ref:CMSG <https://man7.org/linux/man-pages/man3/cmsg.3.html>`_ for further information.
Used in:
optional level = 1
cmsg level. Default is unset.
optional type = 2
cmsg type. Default is unset.
uint32 expected_size = 3
Expected size of cmsg value. Default is zero.
message
socket_option.proto:40Generic socket option message. This would be used to set socket options that might not exist in upstream kernels or precompiled Envoy binaries. For example: .. code-block:: json { "description": "support tcp keep alive", "state": 0, "level": 1, "name": 9, "int_value": 1, } 1 means SOL_SOCKET and 9 means SO_KEEPALIVE on Linux. With the above configuration, `TCP Keep-Alives <https://www.freesoft.org/CIE/RFC/1122/114.htm>`_ can be enabled in socket with Linux, which can be used in :ref:`listener's<envoy_v3_api_field_config.listener.v3.Listener.socket_options>` or :ref:`admin's <envoy_v3_api_field_config.bootstrap.v3.Admin.socket_options>` socket_options etc. It should be noted that the name or level may have different values on different platforms. [#next-free-field: 8]
Used in: , , ,
string description = 1
An optional name to give this socket option for debugging, etc. Uniqueness is not required and no special meaning is assumed.
int64 level = 2
Corresponding to the level value passed to setsockopt, such as IPPROTO_TCP
int64 name = 3
The numeric name as passed to setsockopt
oneof value
int64 int_value = 4
Because many sockopts take an int value.
bytes buf_value = 5
Otherwise it's a byte buffer.
SocketOption.SocketState state = 6
The state in which the option will be applied. When used in BindConfig STATE_PREBIND is currently the only valid value.
optional type = 7
Apply the socket option to the specified `socket type <https://linux.die.net/man/2/socket>`_. If not specified, the socket option will be applied to all socket types.
Used in:
STATE_PREBIND = 0
Socket options are applied after socket creation but before binding the socket to a port
STATE_BOUND = 1
Socket options are applied after binding the socket to a port but before calling listen()
STATE_LISTENING = 2
Socket options are applied after calling listen()
message
socket_option.proto:61The `socket type <https://linux.die.net/man/2/socket>`_ to apply the socket option to. Only one field should be set. If multiple fields are set, the precedence order will determine the selected one. If none of the fields is set, the socket option will be applied to all socket types. For example: If :ref:`stream <envoy_v3_api_field_config.core.v3.SocketOption.SocketType.stream>` is set, it takes precedence over :ref:`datagram <envoy_v3_api_field_config.core.v3.SocketOption.SocketType.datagram>`.
Used in:
optional stream = 1
Apply the socket option to the stream socket type.
optional datagram = 2
Apply the socket option to the datagram socket type.
message
socket_option.proto:67The datagram socket type.
Used in:
(message has no fields)
message
socket_option.proto:63The stream socket type.
Used in:
(message has no fields)
message
socket_option.proto:106Used in: ,
repeated socket_options = 1
Configuration to use multiple :ref:`command operators <config_access_log_command_operators>` to generate a new string in either plain text or JSON format. [#next-free-field: 8]
Used in: , , , , , ,
oneof format
string text_format = 1
Specify a format with command operators to form a text string. Its details is described in :ref:`format string<config_access_log_format_strings>`. For example, setting ``text_format`` like below, .. validated-code-block:: yaml :type-name: envoy.config.core.v3.SubstitutionFormatString text_format: "%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%\n" generates plain text similar to: .. code-block:: text upstream connect error:503:path=/foo Deprecated in favor of :ref:`text_format_source <envoy_v3_api_field_config.core.v3.SubstitutionFormatString.text_format_source>`. To migrate text format strings, use the :ref:`inline_string <envoy_v3_api_field_config.core.v3.DataSource.inline_string>` field.
json_format = 2
Specify a format with command operators to form a JSON string. Its details is described in :ref:`format dictionary<config_access_log_format_dictionaries>`. Values are rendered as strings, numbers, or boolean values as appropriate. Nested JSON objects may be produced by some command operators (e.g. FILTER_STATE or DYNAMIC_METADATA). See the documentation for a specific command operator for details. .. validated-code-block:: yaml :type-name: envoy.config.core.v3.SubstitutionFormatString json_format: status: "%RESPONSE_CODE%" message: "%LOCAL_REPLY_BODY%" The following JSON object would be created: .. code-block:: json { "status": 500, "message": "My error message" }
text_format_source = 5
Specify a format with command operators to form a text string. Its details is described in :ref:`format string<config_access_log_format_strings>`. For example, setting ``text_format`` like below, .. validated-code-block:: yaml :type-name: envoy.config.core.v3.SubstitutionFormatString text_format_source: inline_string: "%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%\n" generates plain text similar to: .. code-block:: text upstream connect error:503:path=/foo
bool omit_empty_values = 3
If set to true, when command operators are evaluated to null, * for ``text_format``, the output of the empty operator is changed from ``-`` to an empty string, so that empty values are omitted entirely. * for ``json_format`` the keys with null values are omitted in the output structure. .. note:: This option does not work perfectly with ``json_format`` as keys with ``null`` values will still be included in the output. See https://github.com/envoyproxy/envoy/issues/37941 for more details.
string content_type = 4
Specify a ``content_type`` field. If this field is not set then ``text/plain`` is used for ``text_format`` and ``application/json`` is used for ``json_format``. .. validated-code-block:: yaml :type-name: envoy.config.core.v3.SubstitutionFormatString content_type: "text/html; charset=UTF-8"
repeated formatters = 6
Specifies a collection of Formatter plugins that can be called from the access log configuration. See the formatters extensions documentation for details. [#extension-category: envoy.formatter]
optional json_format_options = 7
If json_format is used, the options will be applied to the output JSON string.
message
address.proto:107Used in:
optional keepalive_probes = 1
Maximum number of keepalive probes to send without response before deciding the connection is dead. Default is to use the OS level configuration (unless overridden, Linux defaults to 9.)
optional keepalive_time = 2
The number of seconds a connection needs to be idle before keep-alive probes start being sent. Default is to use the OS level configuration (unless overridden, Linux defaults to 7200s (i.e., 2 hours.)
optional keepalive_interval = 3
The number of seconds between keep-alive probes. Default is to use the OS level configuration (unless overridden, Linux defaults to 75s.)
message
protocol.proto:28[#not-implemented-hide:]
(message has no fields)
message
proxy_protocol.proto:36Represents a single Type-Length-Value (TLV) entry.
Used in: , ,
uint32 type = 1
The type of the TLV. Must be a uint8 (0-255) as per the Proxy Protocol v2 specification.
bytes value = 2
The value of the TLV. Must be at least one byte long.
Identifies the direction of the traffic relative to the local Envoy.
Used in:
UNSPECIFIED = 0
Default option is unspecified.
INBOUND = 1
The transport is used for incoming traffic.
OUTBOUND = 2
The transport is used for outgoing traffic.
message
base.proto:615Configuration for transport socket in :ref:`listeners <config_listeners>` and :ref:`clusters <envoy_v3_api_msg_config.cluster.v3.Cluster>`. If the configuration is empty, a default transport socket implementation and configuration will be chosen based on the platform and existence of tls_context.
Used in: , , , , , , ,
string name = 1
The name of the transport socket to instantiate. The name must match a supported transport socket implementation.
oneof config_type
Implementation specific configuration which depends on the implementation being instantiated. See the supported transport socket implementations for further documentation.
typed_config = 3
message
extension.proto:20Message type for extension configuration. [#next-major-version: revisit all existing typed_config that doesn't use this wrapper.].
Used in: , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
string name = 1
The name of an extension. This is not used to select the extension, instead it serves the role of an opaque identifier.
optional typed_config = 2
The typed config for the extension. The type URL will be used to identify the extension. In the case that the type URL is ``xds.type.v3.TypedStruct`` (or, for historical reasons, ``udpa.type.v1.TypedStruct``), the inner type URL of ``TypedStruct`` will be utilized. See the :ref:`extension configuration overview <config_overview_extension_configuration>` for further details.
message
udp_socket_config.proto:19Generic UDP socket configuration.
Used in: ,
optional max_rx_datagram_size = 1
The maximum size of received UDP datagrams. Using a larger size will cause Envoy to allocate more memory per socket. Received datagrams above this size will be dropped. If not set defaults to 1500 bytes.
optional prefer_gro = 2
Configures whether Generic Receive Offload (GRO) <https://en.wikipedia.org/wiki/Large_receive_offload>_ is preferred when reading from the UDP socket. The default is context dependent and is documented where UdpSocketConfig is used. This option affects performance but not functionality. If GRO is not supported by the operating system, non-GRO receive will be used.
message
protocol.proto:118Used in: ,
bool auto_sni = 1
Set transport socket `SNI <https://en.wikipedia.org/wiki/Server_Name_Indication>`_ for new upstream connections based on the downstream HTTP host/authority header or any other arbitrary header when :ref:`override_auto_sni_header <envoy_v3_api_field_config.core.v3.UpstreamHttpProtocolOptions.override_auto_sni_header>` is set, as seen by the :ref:`router filter <config_http_filters_router>`. Does nothing if a filter before the http router filter sets the corresponding metadata. See :ref:`SNI configuration <start_quick_start_securing_sni_client>` for details on how this interacts with other validation options.
bool auto_san_validation = 2
Automatic validate upstream presented certificate for new upstream connections based on the downstream HTTP host/authority header or any other arbitrary header when :ref:`override_auto_sni_header <envoy_v3_api_field_config.core.v3.UpstreamHttpProtocolOptions.override_auto_sni_header>` is set, as seen by the :ref:`router filter <config_http_filters_router>`. This field is intended to be set with ``auto_sni`` field. Does nothing if a filter before the http router filter sets the corresponding metadata. See :ref:`validation configuration <start_quick_start_securing_validation>` for how this interacts with other validation options.
string override_auto_sni_header = 3
An optional alternative to the host/authority header to be used for setting the SNI value. It should be a valid downstream HTTP header, as seen by the :ref:`router filter <config_http_filters_router>`. If unset, host/authority header will be used for populating the SNI. If the specified header is not found or the value is empty, host/authority header will be used instead. This field is intended to be set with ``auto_sni`` and/or ``auto_san_validation`` fields. If none of these fields are set then setting this would be a no-op. Does nothing if a filter before the http router filter sets the corresponding metadata.
message
base.proto:493A directory that is watched for changes, e.g. by inotify on Linux. Move/rename events inside this directory trigger the watch.
Used in: , , ,
string path = 1
Directory path to watch.