Chiebot-Mirror
/
data-plane-api
mirror of https://github.com/envoyproxy/data-plane-api.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: HTTP connection manager (#256)

Browse Source 
I will defer RDS into another PR. I will also do another cleanup
pass over all of this later but want to get most of this in place
first.

Signed-off-by: Matt Klein <mklein@lyft.com>
pull/262/merge
Matt Klein 7 years ago committed by htuch
parent 069ae5dc5e
commit 24792bd944
10 changed files with 409 additions and 299 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 2
      .circleci/config.yml
  2. 133
      api/filter/http/http_connection_manager.proto
  3. 31
      api/protocol.proto
  4. 1
      docs/root/api-v1/api.rst
  5. 260
      docs/root/api-v1/http_filters/http_conn_man.rst
  6. 8
      docs/root/api-v1/http_filters/http_filters.rst
  7. 21
      docs/root/configuration/http_conn_man/filters.rst
  8. 211
      docs/root/configuration/http_conn_man/http_conn_man.rst
  9. 23
      docs/root/configuration/http_conn_man/tracing.rst
  10. 18
      tools/protodoc/protodoc.py

2
.circleci/config.yml
Unescape View File

@ -18,6 +18,8 @@ jobs:
- run: ci/do_ci.sh bazel.docs
- add_ssh_keys
- run: docs/publish.sh
- store_artifacts:
path: generated/docs
workflows:
version: 2

133
api/filter/http/http_connection_manager.proto
Unescape View File

@ -12,29 +12,53 @@ import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
import "validate/validate.proto";
// [#protodoc-title: HTTP connection manager]
// HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
message Rds {
// Configuration source specifier for RDS.
ConfigSource config_source = 1;
ConfigSource config_source = 1 [(validate.rules).message.required = true];
// 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.
string route_config_name = 2;
string route_config_name = 2 [(validate.rules).string.min_len = 1];
}
message HttpFilter {
// The name of the filter to instantiate. The name must match a supported
// filter.
string name = 1;
// filter. The built-in filters are:
//
// [#comment:TODO(mattklein123): Auto generate the following list]
// * :ref:`envoy.buffer <config_http_filters_buffer>`
// * :ref:`envoy.cors <config_http_filters_cors>`
// * :ref:`envoy.fault <config_http_filters_fault_injection>`
// * :ref:`envoy.http_dynamo_filter <config_http_filters_dynamo>`
// * :ref:`envoy.grpc_http1_bridge <config_http_filters_grpc_bridge>`
// * :ref:`envoy.grpc_json_transcoder <config_http_filters_grpc_json_transcoder>`
// * :ref:`envoy.grpc_web <config_http_filters_grpc_web>`
// * :ref:`envoy.health_check <config_http_filters_health_check>`
// * :ref:`envoy.lua <config_http_filters_lua>`
// * :ref:`envoy.ip_tagging <config_http_filters_ip_tagging>`
// * :ref:`envoy.rate_limit <config_http_filters_rate_limit>`
// * :ref:`envoy.router <config_http_filters_router>`
string name = 1 [(validate.rules).string.min_len = 1];
// Filter specific configuration which depends on the filter being
// instantiated. See the supported filters for further documentation.
google.protobuf.Struct config = 2;
// [#not-implemented-hide:]
// This is hidden as type has been deprecated and is no longer required.
message DeprecatedV1 {
string type = 1;
}
// [#not-implemented-hide:]
// This is hidden as type has been deprecated and is no longer required.
DeprecatedV1 deprecated_v1 = 3;
}
@ -46,25 +70,31 @@ message HttpConnectionManager {
// is preferred, otherwise protocol inference is used. In almost all cases,
// this is the right option to choose for this setting.
AUTO = 0;
// The connection manager will assume that the client is speaking HTTP/1.1.
HTTP1 = 1;
// 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).
HTTP2 = 2;
}
CodecType codec_type = 1;
// Supplies the type of codec that the connection manager should use.
CodecType codec_type = 1 [(validate.rules).enum.defined_only = true];
// The human readable prefix to use when emitting statistics for the
// connection manager. See the statistics documentation for more information.
string stat_prefix = 2;
// connection manager. See the :ref:`statistics documentation <config_http_conn_man_stats>` for
// more information.
string stat_prefix = 2 [(validate.rules).string.min_len = 1];
oneof route_specifier {
// The connection manager’s route table will be dynamically loaded via the
// RDS API
option (validate.required) = true;
// The connection manager’s route table will be dynamically loaded via the RDS API.
Rds rds = 3;
// The route table for the connection manager is static and is specified in
// this property.
// The route table for the connection manager is static and is specified in this property.
RouteConfiguration route_config = 4;
}
@ -73,31 +103,42 @@ message HttpConnectionManager {
// processed sequentially as request events happen.
repeated HttpFilter http_filters = 5;
// 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.
// Whether the connection manager manipulates the :ref:`config_http_conn_man_headers_user-agent`
// and :ref:`config_http_conn_man_headers_downstream-service-cluster` headers. See the linked
// documentation for more information. Defaults to false.
google.protobuf.BoolValue add_user_agent = 6;
message Tracing {
// Span name will be derived from operation_name.
enum OperationName {
// The HTTP listener is used for ingress/incoming requests.
INGRESS = 0;
// The HTTP listener is used for egress/outgoing requests.
EGRESS = 1;
}
OperationName operation_name = 1;
// 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.
// The span name will be derived from this field.
OperationName operation_name = 1 [(validate.rules).enum.defined_only = true];
// 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.
repeated string request_headers_for_tags = 2;
}
// Presence of the object defines whether the connection manager
// emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider
// <config_tracing>`.
Tracing tracing = 7;
// Additional HTTP/1 settings that are passed to the HTTP/1 codec.
Http1ProtocolOptions http_protocol_options = 8;
// Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
Http2ProtocolOptions http2_protocol_options = 9;
// An optional override that the connection manager will write to the server
// header in responses. If not set, the default is envoy.
// header in responses. If not set, the default is *envoy*.
string server_name = 10;
// The idle timeout for connections managed by the connection manager. The
@ -105,7 +146,7 @@ message HttpConnectionManager {
// 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.
// :ref:`drain_timeout <envoy_api_field_filter.http.HttpConnectionManager.drain_timeout>`.
google.protobuf.Duration idle_timeout = 11;
// The time that Envoy will wait between sending an HTTP/2 “shutdown
@ -119,26 +160,27 @@ message HttpConnectionManager {
// option is not specified.
google.protobuf.Duration drain_timeout = 12;
// Configuration for HTTP access logs emitted by the connection manager.
// Configuration for :ref:`HTTP access logs <arch_overview_access_logs>`
// emitted by the connection manager.
repeated AccessLog access_log = 13;
// 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.
// TODO(mattklein123): Clean this up, see also discussion in
// https://github.com/lyft/envoy/issues/794.
// 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
// :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header. See the documentation for
// :ref:`config_http_conn_man_headers_x-forwarded-for`,
// :ref:`config_http_conn_man_headers_x-envoy-internal`, and
// :ref:`config_http_conn_man_headers_x-envoy-external-address` for more information.
google.protobuf.BoolValue use_remote_address = 14;
// 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.
// Whether the connection manager will generate the :ref:`x-request-id
// <config_http_conn_man_headers_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.
google.protobuf.BoolValue generate_request_id = 15;
// How to handle the x-forwarded-client-cert (XFCC) HTTP header.
// How to handle the :ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP
// header.
enum ForwardClientCertDetails {
// Do not send the XFCC header to the next hop. This is the default value.
SANITIZE = 0;
@ -155,16 +197,25 @@ message HttpConnectionManager {
// client connection is mTLS.
ALWAYS_FORWARD_ONLY = 4;
};
ForwardClientCertDetails forward_client_cert_details = 16;
// This field is valid only when forward_client_cert 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 SAN value.
// How to handle the :ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP
// header.
ForwardClientCertDetails forward_client_cert_details = 16
[(validate.rules).enum.defined_only = true];
message SetCurrentClientCertDetails {
// Whether to forward the subject of the client cert. Defaults to false.
google.protobuf.BoolValue subject = 1;
// Whether to forward the SAN of the client cert. Defaults to false.
google.protobuf.BoolValue san = 2;
};
// This field is valid only when :ref:`forward_client_cert_details
// <envoy_api_field_filter.http.HttpConnectionManager.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
// :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, *Hash* is always set, and
// *By* is always set when the client certificate presents the SAN value.
SetCurrentClientCertDetails set_current_client_cert_details = 17;
}

31
api/protocol.proto
Unescape View File

@ -4,20 +4,51 @@ package envoy.api.v2;
import "google/protobuf/wrappers.proto";
// [#protodoc-title: Protocol options]
// [#not-implemented-hide:]
message TcpProtocolOptions {
}
message Http1ProtocolOptions {
// 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.
google.protobuf.BoolValue allow_absolute_url = 1;
}
message Http2ProtocolOptions {
// `Maximum table size <http://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.
google.protobuf.UInt32Value hpack_table_size = 1;
// `Maximum concurrent streams <http://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.
google.protobuf.UInt32Value max_concurrent_streams = 2;
// `Initial stream-level flow-control window
// <http://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.
google.protobuf.UInt32Value initial_stream_window_size = 3;
// 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*.
google.protobuf.UInt32Value initial_connection_window_size = 4;
}
// [#not-implemented-hide:]
message GrpcProtocolOptions {
Http2ProtocolOptions http2_protocol_options = 1;
}

1
docs/root/api-v1/api.rst
Unescape View File

@ -6,3 +6,4 @@ Envoy v1 API reference
:maxdepth: 2
network_filters/network_filters
http_filters/http_filters

260
docs/root/api-v1/http_filters/http_conn_man.rst
Unescape View File

@ -0,0 +1,260 @@
.. _config_http_filters_http_conn_man_v1:
HTTP connection manager
=======================
* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`.
* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`.
.. code-block:: json
{
"name": "http_connection_manager",
"config": {
"codec_type": "...",
"stat_prefix": "...",
"rds": "{...}",
"route_config": "{...}",
"filters": [],
"add_user_agent": "...",
"tracing": "{...}",
"http1_settings": "{...}",
"http2_settings": "{...}",
"server_name": "...",
"idle_timeout_s": "...",
"drain_timeout_ms": "...",
"access_log": [],
"use_remote_address": "...",
"forward_client_cert": "...",
"set_current_client_cert": "...",
"generate_request_id": "..."
}
}
.. _config_http_conn_man_codec_type:
codec_type
*(required, string)* Supplies the type of codec that the connection manager should use. Possible
values are:
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).
auto
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.
.. _config_http_conn_man_stat_prefix:
stat_prefix
*(required, string)* The human readable prefix to use when emitting statistics for the
connection manager. See the :ref:`statistics <config_http_conn_man_stats>` documentation
for more information.
.. _config_http_conn_man_rds_option:
:ref:`rds <config_http_conn_man_rds>`
*(sometimes required, object)* The connection manager configuration must specify one of *rds* or
*route_config*. If *rds* is specified, the connection manager's route table will be dynamically
loaded via the RDS API. See the :ref:`documentation <config_http_conn_man_rds>` for more
information.
.. _config_http_conn_man_route_config:
:ref:`route_config <config_http_conn_man_route_table>`
*(sometimes required, object)* The connection manager configuration must specify one of *rds* or
*route_config*. If *route_config* is specified, the :ref:`route table <arch_overview_http_routing>`
for the connection manager is static and is specified in this property.
:ref:`filters <config_http_conn_man_filters>`
*(required, array)* A list of individual :ref:`HTTP filters <arch_overview_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.
.. _config_http_conn_man_add_user_agent:
add_user_agent
*(optional, boolean)* Whether the connection manager manipulates the
:ref:`config_http_conn_man_headers_user-agent` and
:ref:`config_http_conn_man_headers_downstream-service-cluster` headers. See the linked
documentation for more information. Defaults to false.
:ref:`tracing <config_http_conn_man_tracing>`
*(optional, object)* Presence of the object defines whether the connection manager
emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider
<config_tracing>`.
.. _config_http_conn_man_http1_settings:
http1_settings
*(optional, object)* Additional HTTP/1 settings that are passed to the HTTP/1 codec.
allow_absolute_url
*(optional, boolean)* 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.
.. _config_http_conn_man_http2_settings:
http2_settings
*(optional, object)* Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
Currently supported settings are:
hpack_table_size
*(optional, integer)* `Maximum table size <http://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.
max_concurrent_streams
*(optional, integer)* `Maximum concurrent streams
<http://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.
.. _config_http_conn_man_http2_settings_initial_stream_window_size:
initial_stream_window_size
*(optional, integer)* `Initial stream-level flow-control window
<http://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.
initial_connection_window_size
*(optional, integer)* Similar to :ref:`initial_stream_window_size
<config_http_conn_man_http2_settings_initial_stream_window_size>`, but for connection-level flow-control
window. Currently , this has the same minimum/maximum/default as :ref:`initial_stream_window_size
<config_http_conn_man_http2_settings_initial_stream_window_size>`.
These are the same options available in the upstream cluster :ref:`http2_settings
<config_cluster_manager_cluster_http2_settings>` option.
.. _config_http_conn_man_server_name:
server_name
*(optional, string)* An optional override that the connection manager will write to the
:ref:`config_http_conn_man_headers_server` header in responses. If not set, the default is
*envoy*.
idle_timeout_s
*(optional, integer)* The idle timeout in seconds 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 :ref:`drain_timeout_ms <config_http_conn_man_drain_timeout_ms>`.
.. _config_http_conn_man_drain_timeout_ms:
drain_timeout_ms
*(optional, integer)* The time in milliseconds 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.
:ref:`access_log <config_access_log>`
*(optional, array)* Configuration for :ref:`HTTP access logs <arch_overview_access_logs>`
emitted by the connection manager.
.. _config_http_conn_man_use_remote_address:
use_remote_address
*(optional, boolean)* 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
:ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header. See the documentation for
:ref:`config_http_conn_man_headers_x-forwarded-for`,
:ref:`config_http_conn_man_headers_x-envoy-internal`, and
:ref:`config_http_conn_man_headers_x-envoy-external-address` for more information.
.. _config_http_conn_man_forward_client_cert:
forward_client_cert
*(optional, string)* How to handle the
:ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP header.
Possible values are:
1. **sanitize**: Do not send the XFCC header to the next hop. This is the default value.
2. **forward_only**: When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
3. **always_forward_only**: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
4. **append_forward**: When the client connection is mTLS, append the client certificate information to the request's XFCC header and forward it.
5. **sanitize_set**: When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
For the format of the XFCC header, please refer to
:ref:`config_http_conn_man_headers_x-forwarded-client-cert`.
.. _config_http_conn_man_set_current_client_cert_details:
set_current_client_cert_details
*(optional, array)* A list of strings, possible values are *Subject* and *SAN*. This field is
valid only when *forward_client_cert* 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 :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, `Hash` is always set,
and `By` is always set when the client certificate presents the SAN value.
generate_request_id
*(optional, boolean)* Whether the connection manager will generate the
:ref:`config_http_conn_man_headers_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.
.. _config_http_conn_man_tracing:
Tracing
-------
.. code-block:: json
{
"tracing": {
"operation_name": "...",
"request_headers_for_tags": []
}
}
operation_name
*(required, string)* Span name will be derived from operation_name. "ingress" and "egress"
are the only supported values.
request_headers_for_tags
*(optional, array)* 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.
.. _config_http_conn_man_filters:
Filters
-------
HTTP filter :ref:`architecture overview <arch_overview_http_filters>`.
.. code-block:: json
{
"name": "...",
"config": "{...}"
}
name
*(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
filter <config_http_filters>`.
config
*(required, object)* Filter specific configuration which depends on the filter being
instantiated. See the :ref:`supported filters <config_http_filters>` for further documentation.

8
docs/root/api-v1/http_filters/http_filters.rst
Unescape View File

@ -0,0 +1,8 @@
HTTP filters
============
.. toctree::
:glob:
:maxdepth: 2
*

21
docs/root/configuration/http_conn_man/filters.rst
Unescape View File

@ -1,21 +0,0 @@
.. _config_http_conn_man_filters:
Filters
=======
HTTP filter :ref:`architecture overview <arch_overview_http_filters>`.
.. code-block:: json
{
"name": "...",
"config": "{...}"
}
name
*(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
filter <config_http_filters>`.
config
*(required, object)* Filter specific configuration which depends on the filter being
instantiated. See the :ref:`supported filters <config_http_filters>` for further documentation.

211
docs/root/configuration/http_conn_man/http_conn_man.rst
Unescape View File

@ -5,220 +5,13 @@ HTTP connection manager
* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`.
* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`.
.. code-block:: json
{
"name": "http_connection_manager",
"config": {
"codec_type": "...",
"stat_prefix": "...",
"rds": "{...}",
"route_config": "{...}",
"filters": [],
"add_user_agent": "...",
"tracing": "{...}",
"http1_settings": "{...}",
"http2_settings": "{...}",
"server_name": "...",
"idle_timeout_s": "...",
"drain_timeout_ms": "...",
"access_log": [],
"use_remote_address": "...",
"forward_client_cert": "...",
"set_current_client_cert": "...",
"generate_request_id": "..."
}
}
.. _config_http_conn_man_codec_type:
codec_type
*(required, string)* Supplies the type of codec that the connection manager should use. Possible
values are:
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).
auto
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.
.. _config_http_conn_man_stat_prefix:
stat_prefix
*(required, string)* The human readable prefix to use when emitting statistics for the
connection manager. See the :ref:`statistics <config_http_conn_man_stats>` documentation
for more information.
.. _config_http_conn_man_rds_option:
:ref:`rds <config_http_conn_man_rds>`
*(sometimes required, object)* The connection manager configuration must specify one of *rds* or
*route_config*. If *rds* is specified, the connection manager's route table will be dynamically
loaded via the RDS API. See the :ref:`documentation <config_http_conn_man_rds>` for more
information.
.. _config_http_conn_man_route_config:
:ref:`route_config <config_http_conn_man_route_table>`
*(sometimes required, object)* The connection manager configuration must specify one of *rds* or
*route_config*. If *route_config* is specified, the :ref:`route table <arch_overview_http_routing>`
for the connection manager is static and is specified in this property.
:ref:`filters <config_http_conn_man_filters>`
*(required, array)* A list of individual :ref:`HTTP filters <arch_overview_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.
.. _config_http_conn_man_add_user_agent:
add_user_agent
*(optional, boolean)* Whether the connection manager manipulates the
:ref:`config_http_conn_man_headers_user-agent` and
:ref:`config_http_conn_man_headers_downstream-service-cluster` headers. See the linked
documentation for more information. Defaults to false.
:ref:`tracing <config_http_conn_man_tracing>`
*(optional, object)* Presence of the object defines whether the connection manager
emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider <config_tracing>`.
.. _config_http_conn_man_http1_settings:
http1_settings
*(optional, object)* Additional HTTP/1 settings that are passed to the HTTP/1 codec.
allow_absolute_url
*(optional, boolean)* 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.
.. _config_http_conn_man_http2_settings:
http2_settings
*(optional, object)* Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
Currently supported settings are:
hpack_table_size
*(optional, integer)* `Maximum table size <http://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.
max_concurrent_streams
*(optional, integer)* `Maximum concurrent streams
<http://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.
.. _config_http_conn_man_http2_settings_initial_stream_window_size:
initial_stream_window_size
*(optional, integer)* `Initial stream-level flow-control window
<http://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.
initial_connection_window_size
*(optional, integer)* Similar to :ref:`initial_stream_window_size
<config_http_conn_man_http2_settings_initial_stream_window_size>`, but for connection-level flow-control
window. Currently , this has the same minimum/maximum/default as :ref:`initial_stream_window_size
<config_http_conn_man_http2_settings_initial_stream_window_size>`.
These are the same options available in the upstream cluster :ref:`http2_settings
<config_cluster_manager_cluster_http2_settings>` option.
.. _config_http_conn_man_server_name:
server_name
*(optional, string)* An optional override that the connection manager will write to the
:ref:`config_http_conn_man_headers_server` header in responses. If not set, the default is
*envoy*.
idle_timeout_s
*(optional, integer)* The idle timeout in seconds 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 :ref:`drain_timeout_ms <config_http_conn_man_drain_timeout_ms>`.
.. _config_http_conn_man_drain_timeout_ms:
drain_timeout_ms
*(optional, integer)* The time in milliseconds 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.
:ref:`access_log <config_access_log>`
*(optional, array)* Configuration for :ref:`HTTP access logs <arch_overview_access_logs>`
emitted by the connection manager.
.. _config_http_conn_man_use_remote_address:
use_remote_address
*(optional, boolean)* 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
:ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header. See the documentation for
:ref:`config_http_conn_man_headers_x-forwarded-for`,
:ref:`config_http_conn_man_headers_x-envoy-internal`, and
:ref:`config_http_conn_man_headers_x-envoy-external-address` for more information.
.. _config_http_conn_man_forward_client_cert:
forward_client_cert
*(optional, string)* How to handle the
:ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP header.
Possible values are:
1. **sanitize**: Do not send the XFCC header to the next hop. This is the default value.
2. **forward_only**: When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
3. **always_forward_only**: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
4. **append_forward**: When the client connection is mTLS, append the client certificate information to the request's XFCC header and forward it.
5. **sanitize_set**: When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
For the format of the XFCC header, please refer to
:ref:`config_http_conn_man_headers_x-forwarded-client-cert`.
.. _config_http_conn_man_set_current_client_cert_details:
set_current_client_cert_details
*(optional, array)* A list of strings, possible values are *Subject* and *SAN*. This field is
valid only when *forward_client_cert* 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 :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, `Hash` is always set,
and `By` is always set when the client certificate presents the SAN value.
generate_request_id
*(optional, boolean)* Whether the connection manager will generate the
:ref:`config_http_conn_man_headers_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.
* :ref:`v1 API reference <config_http_filters_http_conn_man_v1>`
* :ref:`v2 API reference <envoy_api_msg_filter.http.HttpConnectionManager>`
.. toctree::
:hidden:
route_config/route_config
filters
tracing
headers
header_sanitizing
stats

23
docs/root/configuration/http_conn_man/tracing.rst
Unescape View File

@ -1,23 +0,0 @@
.. _config_http_conn_man_tracing:
Tracing
=======
.. code-block:: json
{
"tracing": {
"operation_name": "...",
"request_headers_for_tags": []
}
}
operation_name
*(required, string)* Span name will be derived from operation_name. "ingress" and "egress"
are the only supported values.
request_headers_for_tags
*(optional, array)* 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.

18
tools/protodoc/protodoc.py
Unescape View File

@ -35,12 +35,16 @@ NOT_IMPLEMENTED_WARN_ANNOTATION = 'not-implemented-warn'
# field.
NOT_IMPLEMENTED_HIDE_ANNOTATION = 'not-implemented-hide'
# Comment. Just used for adding text that will not go into the docs at all.
COMMENT_ANNOTATION = 'comment'
# Where v2 differs from v1..
V2_API_DIFF_ANNOTATION = 'v2-api-diff'
VALID_ANNOTATIONS = set([
DOC_TITLE_ANNOTATION, NOT_IMPLEMENTED_WARN_ANNOTATION,
NOT_IMPLEMENTED_HIDE_ANNOTATION, V2_API_DIFF_ANNOTATION
NOT_IMPLEMENTED_HIDE_ANNOTATION, V2_API_DIFF_ANNOTATION,
COMMENT_ANNOTATION
])
@ -240,10 +244,14 @@ def FormatMessageAsJson(type_context, msg):
Return:
RST formatted pseudo-JSON string representation of message definition.
"""
lines = [
'"%s": %s' % (f.name, FormatFieldTypeAsJson(type_context, f))
for f in msg.field
]
lines = []
for index, field in enumerate(msg.field):
field_type_context = type_context.Extend([2, index], field.name)
leading_comment, comment_annotations = field_type_context.LeadingCommentPathLookup()
if NOT_IMPLEMENTED_HIDE_ANNOTATION in comment_annotations:
continue
lines.append('"%s": %s' % (field.name, FormatFieldTypeAsJson(type_context, field)))
return '.. code-block:: json\n\n {\n' + ',\n'.join(IndentLines(
4, lines)) + '\n }\n\n'

Write Preview
Loading…
Cancel
Save