package envoy.api.v2.core
Get desktop application:
View/edit binary Protocol Buffers messages
message
address.proto:117Addresses 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
message
config_source.proto:102Aggregated Discovery Service (ADS) options. This is currently empty, but when set in :ref:`ConfigSource <envoy_api_msg_core.ConfigSource>` can be used to specify that ADS is to be used.
Used in:
(message has no fields)
message
config_source.proto:42API configuration source. This identifies the API type and cluster that Envoy will use to fetch an xDS API. [#next-free-field: 9]
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.
APIs may be fetched via either REST or gRPC.
Used in:
UNSUPPORTED_REST_LEGACY = 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
gRPC v2 API.
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.
xDS API 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 v2, to ease migration to Envoy's stable API versioning. If a client does not support v2 (e.g. due to deprecation), this is an invalid value.
V2 = 1
Use xDS v2 API.
V3 = 2
Use xDS v3 API.
message
base.proto:328Async data source which support async data fetch.
oneof specifier
local = 1
Local async data source.
remote = 2
Remote async data source.
message
backoff.proto:21Configuration 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_api_field_core.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_api_field_core.BackoffStrategy.base_interval>` if set. The default is 10 times the :ref:`base_interval <envoy_api_field_core.BackoffStrategy.base_interval>`.
message
address.proto:96Used 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_api_field_UpstreamBindConfig.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.
message
base.proto:91BuildVersion 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:129CidrRange 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:133Configuration for :ref:`listeners <config_listeners>`, :ref:`clusters <config_cluster_manager>`, :ref:`routes <envoy_api_msg_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: 7]
Used in: , , , , , , , ,
oneof config_source_specifier
string path = 1
Path on the filesystem to source and watch for configuration updates. When sourcing configuration for :ref:`secret <envoy_api_msg_auth.Secret>`, the certificate and key files are also watched for updates. .. note:: The path to the source must exist at config load time. .. note:: Envoy will only 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.
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_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:377Identifies 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:288Data source consisting of either a file or an inline value.
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.
message
event_service_config.proto:20[#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:102Version and identification for an Envoy extension. [#next-free-field: 6]
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.
message
grpc_method_list.proto:19A list of gRPC methods which can be used as an allowlist, for example.
Used in:
repeated services = 1
message
grpc_method_list.proto:20Used 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:296[#not-implemented-hide:]
optional http2_protocol_options = 1
message
grpc_service.proto:29gRPC service configuration. This is used by :ref:`ApiConfigSource <envoy_api_msg_core.ApiConfigSource>` and filter configurations. [#next-free-field: 6]
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.
message
grpc_service.proto:30Used in:
string cluster_name = 1
The name of the upstream gRPC cluster. SSL credentials will be supplied in the :ref:`Cluster <envoy_api_msg_Cluster>` :ref:`transport_socket <envoy_api_field_Cluster.transport_socket>`.
message
grpc_service.proto:38[#next-free-field: 7]
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_api_field_core.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.
message
grpc_service.proto:72[#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:79Used in:
string authorization_token = 1
string authority_selector = 2
message
grpc_service.proto:85Used in:
string name = 1
oneof config_type
config = 2
typed_config = 3
message
grpc_service.proto:73Used in:
string json_key = 1
uint64 token_lifetime_seconds = 2
message
grpc_service.proto:100Security 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:58See 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:53Local 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:40See 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:283Wrapper for a set of headers.
Used in:
repeated headers = 1
message
base.proto:256Header 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 `-`.
message
base.proto:273Header 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.
message
health_check.proto:60[#next-free-field: 23]
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 503 this threshold is ignored and the host is considered unhealthy immediately.
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 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>`. If empty, no event log will be written.
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.
optional tls_options = 21
This allows overriding the cluster TLS settings, just for health check connections.
message
health_check.proto:172Custom 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.
config = 2
typed_config = 3
message
health_check.proto:156`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_api_field_endpoint.Endpoint.HealthCheckConfig.hostname>` field.
message
health_check.proto:75[#next-free-field: 12]
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_api_field_endpoint.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.
optional receive = 4
[#not-implemented-hide:] HTTP specific response.
string service_name = 5
An optional service name parameter which is used to validate the identity of the health checked cluster. See the :ref:`architecture overview <arch_overview_health_checking_identity>` for more information. .. attention:: This field has been deprecated in favor of `service_name_matcher` for better flexibility over matching with service-cluster name.
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.
bool use_http2 = 7
If set, health checks will be made using http/2. Deprecated, use :ref:`codec_client_type <envoy_api_field_core.HealthCheck.HttpHealthCheck.codec_client_type>` instead.
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_api_msg_type.Int64Range>`. The start and end of each range are required. Only statuses in the range [100, 600) are allowed.
type.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_api_msg_type.matcher.StringMatcher>`. See the :ref:`architecture overview <arch_overview_health_checking_identity>` for more information.
message
health_check.proto:62Describes 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
[#not-implemented-hide:] Binary payload.
message
health_check.proto:144string 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:134Used 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 binary block must be found, and in the order specified, but not necessarily contiguous.
message
health_check.proto:189Health 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_api_msg_listener.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
protocol.proto:98[#next-free-field: 6]
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.
message
protocol.proto:99Used 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".
message
protocol.proto:100Used in:
(message has no fields)
message
protocol.proto:149[#next-free-field: 14]
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).
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 metadata. 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. [#comment:TODO: implement same limits for upstream outbound frames as well.]
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. [#comment:TODO: implement same limits for upstream outbound frames as well.]
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. [#comment:TODO: implement same limits for upstream inbound frames as well.]
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 + inbound_streams) the connection is terminated. The ``http2.inbound_priority_frames_flood`` stat tracks the number of connections terminated due to flood mitigation. The default limit is 100. [#comment:TODO: implement same limits for upstream inbound frames as well.]
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:: 1 + 2 * (inbound_streams + max_inbound_window_update_frames_per_data_frame_sent * outbound_data_frames) the connection is terminated. The ``http2.inbound_priority_frames_flood`` stat tracks the number of connections terminated due to flood mitigation. The default limit 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. [#comment:TODO: implement same limits for upstream inbound frames as well.]
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. 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.
message
protocol.proto:152Defines 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:39[#next-free-field: 6]
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_api_field_config.filter.network.http_connection_manager.v2.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.
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 connection will be closed. Drain sequence will occur prior to closing the connection if if's applicable. See :ref:`drain_timeout <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.drain_timeout>`. Note: not implemented for upstream connections.
optional max_headers_count = 2
The maximum number of headers. If unconfigured, the default maximum number of request headers allowed is 100. Requests that exceed this limit will receive a 431 response for HTTP/1.x and cause a stream reset for HTTP/2.
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.
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 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_uri.proto:21Envoy 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.
message
base.proto:69Identifies location of where either Envoy runs or where upstream hosts run.
Used in: , , , ,
string region = 1
Region this :ref:`zone <envoy_api_field_core.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_api_field_endpoint.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:220Metadata 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.
message
base.proto:132Identifies 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: 12]
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_api_field_core.HealthCheck.HttpHealthCheck.service_name_matcher>`, :ref:`runtime override directory <envoy_api_msg_config.bootstrap.v2.Runtime>`, :ref:`user agent addition <envoy_api_field_config.filter.network.http_connection_manager.v2.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.
optional locality = 4
Locality specifying where the Envoy instance is running.
string build_version = 5
This is motivated by informing a management server during canary which version of Envoy is being tested in a heterogeneous fleet. This will be set by Envoy in management server RPCs. This field is deprecated in favor of the user_agent_name and user_agent_version values.
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
address.proto:22Used 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
config_source.proto:116Rate 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.
message
base.proto:316The 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:304The message specifies the retry policy of remote data source when fetching fails.
Used in:
optional retry_back_off = 1
Specifies parameters that control :ref:`retry backoff strategy <envoy_api_msg_core.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.
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:236Runtime derived double with a default when not specified.
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:245Runtime 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:368Runtime 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_api_msg_type.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:227Runtime 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
config_source.proto:109[#not-implemented-hide:] Self-referencing config source options. This is currently empty, but when set in :ref:`ConfigSource <envoy_api_msg_core.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:34[#next-free-field: 7]
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_api_msg_listener.FilterChainMatch>`.] When used within an upstream :ref:`BindConfig <envoy_api_msg_core.BindConfig>`, the address controls the source address of outbound connections. For :ref:`clusters <envoy_api_msg_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_api_field_core.SocketAddress.resolver_name>`.
oneof port_specifier
uint32 port_value = 3
string named_port = 4
This is only valid if :ref:`resolver_name <envoy_api_field_core.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>``.
Used in:
TCP = 0
UDP = 1
message
socket_option.proto:21Generic socket option message. This would be used to set socket options that might not exist in upstream kernels or precompiled Envoy binaries. [#next-free-field: 7]
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.
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
address.proto:80Used 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:22[#not-implemented-hide:]
(message has no fields)
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:344Configuration for transport socket in :ref:`listeners <config_listeners>` and :ref:`clusters <envoy_api_msg_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.
config = 2
typed_config = 3
message
protocol.proto:25Used 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, as seen by the :ref:`router filter <config_http_filters_router>`.
bool auto_san_validation = 2
Automatic validate upstream presented certificate for new upstream connections based on the downstream HTTP host/authority header, as seen by the :ref:`router filter <config_http_filters_router>`. This field is intended to set with `auto_sni` field.