HTTP connection manager¶
HTTP connection manager configuration overview.
config.filter.network.http_connection_manager.v2.HttpConnectionManager¶
[config.filter.network.http_connection_manager.v2.HttpConnectionManager proto]
{
"codec_type": "...",
"stat_prefix": "...",
"rds": "{...}",
"route_config": "{...}",
"http_filters": [],
"add_user_agent": "{...}",
"tracing": "{...}",
"http_protocol_options": "{...}",
"http2_protocol_options": "{...}",
"server_name": "...",
"idle_timeout": "{...}",
"stream_idle_timeout": "{...}",
"request_timeout": "{...}",
"drain_timeout": "{...}",
"delayed_close_timeout": "{...}",
"access_log": [],
"use_remote_address": "{...}",
"xff_num_trusted_hops": "...",
"internal_address_config": "{...}",
"skip_xff_append": "...",
"via": "...",
"generate_request_id": "{...}",
"forward_client_cert_details": "...",
"set_current_client_cert_details": "{...}",
"proxy_100_continue": "...",
"represent_ipv4_remote_address_as_ipv4_mapped_ipv6": "...",
"upgrade_configs": [],
"bugfix_reverse_encode_order": "{...}",
"normalize_path": "{...}"
}
- codec_type
- (config.filter.network.http_connection_manager.v2.HttpConnectionManager.CodecType) Supplies the type of codec that the connection manager should use.
- stat_prefix
- (string, REQUIRED) The human readable prefix to use when emitting statistics for the connection manager. See the statistics documentation for more information.
- rds
(config.filter.network.http_connection_manager.v2.Rds) The connection manager’s route table will be dynamically loaded via the RDS API.
Precisely one of rds, route_config must be set.
- route_config
(RouteConfiguration) The route table for the connection manager is static and is specified in this property.
Precisely one of rds, route_config must be set.
- http_filters
- (config.filter.network.http_connection_manager.v2.HttpFilter) A list of individual HTTP filters that make up the filter chain for requests made to the connection manager. Order matters as the filters are processed sequentially as request events happen.
- add_user_agent
- (BoolValue) Whether the connection manager manipulates the user-agent and x-envoy-downstream-service-cluster headers. See the linked documentation for more information. Defaults to false.
- tracing
- (config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing) Presence of the object defines whether the connection manager emits tracing data to the configured tracing provider.
- http_protocol_options
- (core.Http1ProtocolOptions) Additional HTTP/1 settings that are passed to the HTTP/1 codec.
- http2_protocol_options
- (core.Http2ProtocolOptions) Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
- server_name
- (string) An optional override that the connection manager will write to the server header in responses. If not set, the default is envoy.
- idle_timeout
- (Duration) The idle timeout for connections managed by the connection manager. The idle timeout is defined as the period in which there are no active requests. If not set, there is no idle timeout. When the idle timeout is reached the connection will be closed. If the connection is an HTTP/2 connection a drain sequence will occur prior to closing the connection. See drain_timeout.
- stream_idle_timeout
(Duration) The stream idle timeout for connections managed by the connection manager. If not specified, this defaults to 5 minutes. The default value was selected so as not to interfere with any smaller configured timeouts that may have existed in configurations prior to the introduction of this feature, while introducing robustness to TCP connections that terminate without a FIN.
This idle timeout applies to new streams and is overridable by the route-level idle_timeout. Even on a stream in which the override applies, prior to receipt of the initial request headers, the stream_idle_timeout applies. Each time an encode/decode event for headers or data is processed for the stream, the timer will be reset. If the timeout fires, the stream is terminated with a 408 Request Timeout error code if no upstream response header has been received, otherwise a stream reset occurs.
Note that it is possible to idle timeout even if the wire traffic for a stream is non-idle, due to the granularity of events presented to the connection manager. For example, while receiving very large request headers, it may be the case that there is traffic regularly arriving on the wire while the connection manage is only able to observe the end-of-headers event, hence the stream may still idle timeout.
A value of 0 will completely disable the connection manager stream idle timeout, although per-route idle timeout overrides will continue to apply.
- request_timeout
- (Duration) A timeout for idle requests managed by the connection manager. The timer is activated when the request is initiated, and is disarmed when the last byte of the request is sent upstream (i.e. all decoding filters have processed the request), OR when the response is initiated. If not specified or set to 0, this timeout is disabled.
- drain_timeout
- (Duration) The time that Envoy will wait between sending an HTTP/2 “shutdown notification” (GOAWAY frame with max stream ID) and a final GOAWAY frame. This is used so that Envoy provides a grace period for new streams that race with the final GOAWAY frame. During this grace period, Envoy will continue to accept new streams. After the grace period, a final GOAWAY frame is sent and Envoy will start refusing new streams. Draining occurs both when a connection hits the idle timeout or during general server draining. The default grace period is 5000 milliseconds (5 seconds) if this option is not specified.
- delayed_close_timeout
(Duration) The delayed close timeout is for downstream connections managed by the HTTP connection manager. It is defined as a grace period after connection close processing has been locally initiated during which Envoy will flush the write buffers for the connection and await the peer to close (i.e., a TCP FIN/RST is received by Envoy from the downstream connection).
Delaying Envoy’s connection close and giving the peer the opportunity to initate the close sequence mitigates a race condition that exists when downstream clients do not drain/process data in a connection’s receive buffer after a remote close has been detected via a socket write(). This race leads to such clients failing to process the response code sent by Envoy, which could result in erroneous downstream processing.
If the timeout triggers, Envoy will close the connection’s socket.
The default timeout is 1000 ms if this option is not specified.
A value of 0 will completely disable delayed close processing, and the downstream connection’s socket will be closed immediately after the write flush is completed.
- access_log
- (config.filter.accesslog.v2.AccessLog) Configuration for HTTP access logs emitted by the connection manager.
- use_remote_address
- (BoolValue) If set to true, the connection manager will use the real remote address of the client connection when determining internal versus external origin and manipulating various headers. If set to false or absent, the connection manager will use the x-forwarded-for HTTP header. See the documentation for x-forwarded-for, x-envoy-internal, and x-envoy-external-address for more information.
- xff_num_trusted_hops
- (uint32) The number of additional ingress proxy hops from the right side of the x-forwarded-for HTTP header to trust when determining the origin client’s IP address. The default is zero if this option is not specified. See the documentation for x-forwarded-for for more information.
- internal_address_config
- (config.filter.network.http_connection_manager.v2.HttpConnectionManager.InternalAddressConfig) Configures what network addresses are considered internal for stats and header sanitation purposes. If unspecified, only RFC1918 IP addresses will be considered internal. See the documentation for x-envoy-internal for more information about internal/external addresses.
- skip_xff_append
- (bool) If set, Envoy will not append the remote address to the x-forwarded-for HTTP header. This may be used in conjunction with HTTP filters that explicitly manipulate XFF after the HTTP connection manager has mutated the request headers. While use_remote_address will also suppress XFF addition, it has consequences for logging and other Envoy uses of the remote address, so skip_xff_append should be used when only an elision of XFF addition is intended.
- via
- (string) Via header value to append to request and response headers. If this is empty, no via header will be appended.
- generate_request_id
- (BoolValue) Whether the connection manager will generate the x-request-id header if it does not exist. This defaults to true. Generating a random UUID4 is expensive so in high throughput scenarios where this feature is not desired it can be disabled.
- forward_client_cert_details
- (config.filter.network.http_connection_manager.v2.HttpConnectionManager.ForwardClientCertDetails) How to handle the x-forwarded-client-cert (XFCC) HTTP header.
- set_current_client_cert_details
- (config.filter.network.http_connection_manager.v2.HttpConnectionManager.SetCurrentClientCertDetails) This field is valid only when forward_client_cert_details is APPEND_FORWARD or SANITIZE_SET and the client connection is mTLS. It specifies the fields in the client certificate to be forwarded. Note that in the x-forwarded-client-cert header, Hash is always set, and By is always set when the client certificate presents the URI type Subject Alternative Name value.
- proxy_100_continue
- (bool) If proxy_100_continue is true, Envoy will proxy incoming “Expect: 100-continue” headers upstream, and forward “100 Continue” responses downstream. If this is false or not set, Envoy will instead strip the “Expect: 100-continue” header, and send a “100 Continue” response itself.
- represent_ipv4_remote_address_as_ipv4_mapped_ipv6
- (bool) If use_remote_address is true and represent_ipv4_remote_address_as_ipv4_mapped_ipv6 is true and the remote address is an IPv4 address, the address will be mapped to IPv6 before it is appended to x-forwarded-for. This is useful for testing compatibility of upstream services that parse the header value. For example, 50.0.0.1 is represented as ::FFFF:50.0.0.1. See IPv4-Mapped IPv6 Addresses for details. This will also affect the x-envoy-external-address header. See http_connection_manager.represent_ipv4_remote_address_as_ipv4_mapped_ipv6 for runtime control.
- upgrade_configs
- (config.filter.network.http_connection_manager.v2.HttpConnectionManager.UpgradeConfig)
- bugfix_reverse_encode_order
- (BoolValue) If true, the order of encoder filters will be reversed to that of filters configured in the HTTP filter chain. Otherwise, it will keep the existing order. Note: this is a bug fix for Envoy, which is designed to have the reversed order of encode filters to that of decode ones, (see https://github.com/envoyproxy/envoy/issues/4599 for details). When we remove this field, envoy will have the same behavior when it sets true.
- normalize_path
- (BoolValue) Should paths be normalized according to RFC 3986 before any processing of requests by HTTP filters or routing? This affects the upstream :path header as well. For paths that fail this check, Envoy will respond with 400 to paths that are malformed. This defaults to false currently but will default true in the future. When not specified, this value may be overridden by the runtime variable http_connection_manager.normalize_path. See Normalization and Comparison <https://tools.ietf.org/html/rfc3986#section-6> for details of normalization. Note that Envoy does not perform case normalization <https://tools.ietf.org/html/rfc3986#section-6.2.2.1>
config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing¶
[config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing proto]
{
"operation_name": "...",
"request_headers_for_tags": [],
"client_sampling": "{...}",
"random_sampling": "{...}",
"overall_sampling": "{...}"
}
- operation_name
- (config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing.OperationName) The span name will be derived from this field.
- request_headers_for_tags
- (string) A list of header names used to create tags for the active span. The header name is used to populate the tag name, and the header value is used to populate the tag value. The tag is created if the specified header name is present in the request’s headers.
- client_sampling
- (type.Percent) Target percentage of requests managed by this HTTP connection manager that will be force traced if the x-client-trace-id header is set. This field is a direct analog for the runtime variable ‘tracing.client_sampling’ in the HTTP Connection Manager. Default: 100%
- random_sampling
- (type.Percent) Target percentage of requests managed by this HTTP connection manager that will be randomly selected for trace generation, if not requested by the client or not forced. This field is a direct analog for the runtime variable ‘tracing.random_sampling’ in the HTTP Connection Manager. Default: 100%
- overall_sampling
- (type.Percent) Target percentage of requests managed by this HTTP connection manager that will be traced after all other sampling checks have been applied (client-directed, force tracing, random sampling). This field functions as an upper limit on the total configured sampling rate. For instance, setting client_sampling to 100% but overall_sampling to 1% will result in only 1% of client requests with the appropriate headers to be force traced. This field is a direct analog for the runtime variable ‘tracing.global_enabled’ in the HTTP Connection Manager. Default: 100%
Enum config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing.OperationName¶
[config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing.OperationName proto]
- INGRESS
- (DEFAULT) The HTTP listener is used for ingress/incoming requests.
- EGRESS
- The HTTP listener is used for egress/outgoing requests.
config.filter.network.http_connection_manager.v2.HttpConnectionManager.InternalAddressConfig¶
[config.filter.network.http_connection_manager.v2.HttpConnectionManager.InternalAddressConfig proto]
{
"unix_sockets": "..."
}
- unix_sockets
- (bool) Whether unix socket addresses should be considered internal.
config.filter.network.http_connection_manager.v2.HttpConnectionManager.SetCurrentClientCertDetails¶
{
"subject": "{...}",
"cert": "...",
"dns": "...",
"uri": "..."
}
- subject
- (BoolValue) Whether to forward the subject of the client cert. Defaults to false.
- cert
- (bool) Whether to forward the entire client cert in URL encoded PEM format. This will appear in the XFCC header comma separated from other values with the value Cert=”PEM”. Defaults to false.
- dns
- (bool) Whether to forward the DNS type Subject Alternative Names of the client cert. Defaults to false.
- uri
- (bool) Whether to forward the URI type Subject Alternative Name of the client cert. Defaults to false.
config.filter.network.http_connection_manager.v2.HttpConnectionManager.UpgradeConfig¶
[config.filter.network.http_connection_manager.v2.HttpConnectionManager.UpgradeConfig proto]
The configuration for HTTP upgrades. For each upgrade type desired, an UpgradeConfig must be added.
Warning
The current implementation of upgrade headers does not handle multi-valued upgrade headers. Support for multi-valued headers may be added in the future if needed.
Warning
The current implementation of upgrade headers does not work with HTTP/2 upstreams.
{
"upgrade_type": "...",
"filters": [],
"enabled": "{...}"
}
- upgrade_type
- (string) The case-insensitive name of this upgrade, e.g. “websocket”. For each upgrade type present in upgrade_configs, requests with Upgrade: [upgrade_type] will be proxied upstream.
- filters
- (config.filter.network.http_connection_manager.v2.HttpFilter) If present, this represents the filter chain which will be created for this type of upgrade. If no filters are present, the filter chain for HTTP connections will be used for this upgrade type.
- enabled
- (BoolValue) Determines if upgrades are enabled or disabled by default. Defaults to true. This can be overriden on a per-route basis with cluster as documented in the upgrade documentation.
Enum config.filter.network.http_connection_manager.v2.HttpConnectionManager.CodecType¶
[config.filter.network.http_connection_manager.v2.HttpConnectionManager.CodecType proto]
- AUTO
- (DEFAULT) For every new connection, the connection manager will determine which codec to use. This mode supports both ALPN for TLS listeners as well as protocol inference for plaintext listeners. If ALPN data is available, it is preferred, otherwise protocol inference is used. In almost all cases, this is the right option to choose for this setting.
- HTTP1
- The connection manager will assume that the client is speaking HTTP/1.1.
- HTTP2
- The connection manager will assume that the client is speaking HTTP/2 (Envoy does not require HTTP/2 to take place over TLS or to use ALPN. Prior knowledge is allowed).
Enum config.filter.network.http_connection_manager.v2.HttpConnectionManager.ForwardClientCertDetails¶
How to handle the x-forwarded-client-cert (XFCC) HTTP header.
- SANITIZE
- (DEFAULT) Do not send the XFCC header to the next hop. This is the default value.
- FORWARD_ONLY
- When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
- APPEND_FORWARD
- When the client connection is mTLS, append the client certificate information to the request’s XFCC header and forward it.
- SANITIZE_SET
- When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
- ALWAYS_FORWARD_ONLY
- Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
config.filter.network.http_connection_manager.v2.Rds¶
[config.filter.network.http_connection_manager.v2.Rds proto]
{
"config_source": "{...}",
"route_config_name": "..."
}
- config_source
- (core.ConfigSource, REQUIRED) Configuration source specifier for RDS.
- route_config_name
- (string, REQUIRED) The name of the route configuration. This name will be passed to the RDS API. This allows an Envoy configuration with multiple HTTP listeners (and associated HTTP connection manager filters) to use different route configurations.
config.filter.network.http_connection_manager.v2.HttpFilter¶
[config.filter.network.http_connection_manager.v2.HttpFilter proto]
{
"name": "...",
"config": "{...}"
}
- name
(string, REQUIRED) The name of the filter to instantiate. The name must match a supported filter. The built-in filters are:
- config
- (Struct) Filter specific configuration which depends on the filter being instantiated. See the supported filters for further documentation.