From 24792bd944cb238dd35f13817e76f27d66fb0a7c Mon Sep 17 00:00:00 2001 From: Matt Klein Date: Tue, 21 Nov 2017 12:45:18 -0800 Subject: [PATCH] docs: HTTP connection manager (#256) 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 --- .circleci/config.yml | 2 + api/filter/http/http_connection_manager.proto | 133 ++++++--- api/protocol.proto | 31 +++ docs/root/api-v1/api.rst | 1 + .../api-v1/http_filters/http_conn_man.rst | 260 ++++++++++++++++++ .../root/api-v1/http_filters/http_filters.rst | 8 + .../configuration/http_conn_man/filters.rst | 21 -- .../http_conn_man/http_conn_man.rst | 211 +------------- .../configuration/http_conn_man/tracing.rst | 23 -- tools/protodoc/protodoc.py | 18 +- 10 files changed, 409 insertions(+), 299 deletions(-) create mode 100644 docs/root/api-v1/http_filters/http_conn_man.rst create mode 100644 docs/root/api-v1/http_filters/http_filters.rst delete mode 100644 docs/root/configuration/http_conn_man/filters.rst delete mode 100644 docs/root/configuration/http_conn_man/tracing.rst diff --git a/.circleci/config.yml b/.circleci/config.yml index 2e4db0b9..009008e5 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -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 diff --git a/api/filter/http/http_connection_manager.proto b/api/filter/http/http_connection_manager.proto index 016d92bc..bb8aa8a8 100644 --- a/api/filter/http/http_connection_manager.proto +++ b/api/filter/http/http_connection_manager.proto @@ -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 `. + 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 ` + // * :ref:`envoy.cors ` + // * :ref:`envoy.fault ` + // * :ref:`envoy.http_dynamo_filter ` + // * :ref:`envoy.grpc_http1_bridge ` + // * :ref:`envoy.grpc_json_transcoder ` + // * :ref:`envoy.grpc_web ` + // * :ref:`envoy.health_check ` + // * :ref:`envoy.lua ` + // * :ref:`envoy.ip_tagging ` + // * :ref:`envoy.rate_limit ` + // * :ref:`envoy.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 ` 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 ` data to the :ref:`configured tracing provider + // `. 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 `. 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 ` + // 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 + // ` 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 + // ` 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; } diff --git a/api/protocol.proto b/api/protocol.proto index e5ed3790..4205d72b 100644 --- a/api/protocol.proto +++ b/api/protocol.proto @@ -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 `_ + // (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 `_ + // 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 + // `_ 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; } diff --git a/docs/root/api-v1/api.rst b/docs/root/api-v1/api.rst index 1981649b..4d7f060d 100644 --- a/docs/root/api-v1/api.rst +++ b/docs/root/api-v1/api.rst @@ -6,3 +6,4 @@ Envoy v1 API reference :maxdepth: 2 network_filters/network_filters + http_filters/http_filters diff --git a/docs/root/api-v1/http_filters/http_conn_man.rst b/docs/root/api-v1/http_filters/http_conn_man.rst new file mode 100644 index 00000000..9ea104a9 --- /dev/null +++ b/docs/root/api-v1/http_filters/http_conn_man.rst @@ -0,0 +1,260 @@ +.. _config_http_filters_http_conn_man_v1: + +HTTP connection manager +======================= + +* HTTP connection manager :ref:`architecture overview `. +* HTTP protocols :ref:`architecture overview `. + +.. 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 ` documentation + for more information. + +.. _config_http_conn_man_rds_option: + +:ref:`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 ` for more + information. + +.. _config_http_conn_man_route_config: + +:ref:`route_config ` + *(sometimes required, object)* The connection manager configuration must specify one of *rds* or + *route_config*. If *route_config* is specified, the :ref:`route table ` + for the connection manager is static and is specified in this property. + +:ref:`filters ` + *(required, array)* A list of individual :ref:`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 ` + *(optional, object)* Presence of the object defines whether the connection manager + emits :ref:`tracing ` data to the :ref:`configured tracing provider + `. + +.. _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 `_ + (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 + `_ + 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 + `_ 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 + `, but for connection-level flow-control + window. Currently , this has the same minimum/maximum/default as :ref:`initial_stream_window_size + `. + + These are the same options available in the upstream cluster :ref:`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: + +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 ` + *(optional, array)* Configuration for :ref:`HTTP 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 `. + +.. code-block:: json + + { + "name": "...", + "config": "{...}" + } + +name + *(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported + filter `. + +config + *(required, object)* Filter specific configuration which depends on the filter being + instantiated. See the :ref:`supported filters ` for further documentation. diff --git a/docs/root/api-v1/http_filters/http_filters.rst b/docs/root/api-v1/http_filters/http_filters.rst new file mode 100644 index 00000000..f859e409 --- /dev/null +++ b/docs/root/api-v1/http_filters/http_filters.rst @@ -0,0 +1,8 @@ +HTTP filters +============ + +.. toctree:: + :glob: + :maxdepth: 2 + + * diff --git a/docs/root/configuration/http_conn_man/filters.rst b/docs/root/configuration/http_conn_man/filters.rst deleted file mode 100644 index 1bbea3de..00000000 --- a/docs/root/configuration/http_conn_man/filters.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _config_http_conn_man_filters: - -Filters -======= - -HTTP filter :ref:`architecture overview `. - -.. code-block:: json - - { - "name": "...", - "config": "{...}" - } - -name - *(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported - filter `. - -config - *(required, object)* Filter specific configuration which depends on the filter being - instantiated. See the :ref:`supported filters ` for further documentation. diff --git a/docs/root/configuration/http_conn_man/http_conn_man.rst b/docs/root/configuration/http_conn_man/http_conn_man.rst index 60784e9c..12943cac 100644 --- a/docs/root/configuration/http_conn_man/http_conn_man.rst +++ b/docs/root/configuration/http_conn_man/http_conn_man.rst @@ -5,220 +5,13 @@ HTTP connection manager * HTTP connection manager :ref:`architecture overview `. * HTTP protocols :ref:`architecture overview `. - -.. 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 ` documentation - for more information. - -.. _config_http_conn_man_rds_option: - -:ref:`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 ` for more - information. - -.. _config_http_conn_man_route_config: - -:ref:`route_config ` - *(sometimes required, object)* The connection manager configuration must specify one of *rds* or - *route_config*. If *route_config* is specified, the :ref:`route table ` - for the connection manager is static and is specified in this property. - -:ref:`filters ` - *(required, array)* A list of individual :ref:`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 ` - *(optional, object)* Presence of the object defines whether the connection manager - emits :ref:`tracing ` data to the :ref:`configured tracing provider `. - -.. _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 `_ - (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 - `_ - 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 - `_ 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 - `, but for connection-level flow-control - window. Currently , this has the same minimum/maximum/default as :ref:`initial_stream_window_size - `. - - These are the same options available in the upstream cluster :ref:`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: - -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 ` - *(optional, array)* Configuration for :ref:`HTTP 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 ` +* :ref:`v2 API reference ` .. toctree:: :hidden: route_config/route_config - filters - tracing headers header_sanitizing stats diff --git a/docs/root/configuration/http_conn_man/tracing.rst b/docs/root/configuration/http_conn_man/tracing.rst deleted file mode 100644 index c263aeef..00000000 --- a/docs/root/configuration/http_conn_man/tracing.rst +++ /dev/null @@ -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. - diff --git a/tools/protodoc/protodoc.py b/tools/protodoc/protodoc.py index a9a2c64e..cccaf722 100755 --- a/tools/protodoc/protodoc.py +++ b/tools/protodoc/protodoc.py @@ -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'