diff --git a/api/lds.proto b/api/lds.proto index 8fdc97def..fc2b9dc3b 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -66,7 +66,17 @@ message Listener { // true, the listener hands off redirected connections to the listener associated with the // original destination address. If there is no listener associated with the original destination // address, the connection is handled by the listener that receives it. Defaults to false. - google.protobuf.BoolValue use_original_dst = 4; + // + // .. attention:: + // + // This field is deprecated. Use :ref:`an original_dst ` + // :ref:`listener filter ` instead. + // + // Note that hand off to another listener is *NOT* performed without this flag. Once + // :ref:`FilterChainMatch ` is implemented this flag will be + // removed, as filter chain matching can be used to select a filter chain based on the restored + // destination address. + google.protobuf.BoolValue use_original_dst = 4 [deprecated = true]; // Soft limit on size of the listener’s new connection read and write buffers. // If unspecified, an implementation defined default is applied (1MiB). @@ -103,6 +113,13 @@ message Listener { // The type of draining to perform at a listener-wide level. DrainType drain_type = 8; + + // Listener filters have the opportunity to manipulate and augment the connection metadata that + // is used in connection filter chain matching, for example. These filters are run before any in + // :ref:`filter_chains `. Order matters as the filters + // are processed sequentially right after a socket has been accepted by the listener, and before + // a connection is created. + repeated ListenerFilter listener_filters = 9; } message Filter { @@ -205,3 +222,16 @@ message FilterChain { // [#not-implemented-hide:] See base.TransportSocket description. TransportSocket transport_socket = 6; } + +message ListenerFilter { + // The name of the filter to instantiate. The name must match a supported + // filter. The built-in filters are: + // + // [#comment:TODO(mattklein123): Auto generate the following list] + // * :ref:`envoy.listener.original_dst ` + string name = 1 [(validate.rules).string.min_bytes = 1]; + + // Filter specific configuration which depends on the filter being + // instantiated. See the supported filters for further documentation. + google.protobuf.Struct config = 2; +} diff --git a/docs/root/api-v1/listeners/listeners.rst b/docs/root/api-v1/listeners/listeners.rst index 5d799b540..a2fc95770 100644 --- a/docs/root/api-v1/listeners/listeners.rst +++ b/docs/root/api-v1/listeners/listeners.rst @@ -36,7 +36,7 @@ address listeners are supported, e.g., "tcp://127.0.0.1:80". Note, "tcp://0.0.0.0:80" is the wild card match for any IPv4 address with port 80. -:ref:`filters ` +:ref:`filters ` *(required, array)* A list of individual :ref:`network filters ` that make up the filter chain for connections established with the listener. Order matters as the filters are processed sequentially as connection events happen. @@ -80,7 +80,7 @@ drain_type and *modify_only*. See the :ref:`draining ` architecture overview for more information. -.. _config_listener_filters: +.. _config_listener_network_filters: Filters ------- diff --git a/docs/root/configuration/configuration.rst b/docs/root/configuration/configuration.rst index 962ca058f..a15f8c71a 100644 --- a/docs/root/configuration/configuration.rst +++ b/docs/root/configuration/configuration.rst @@ -10,6 +10,7 @@ Configuration reference overview/v1_overview overview/v2_overview listeners/listeners + listener_filters/listener_filters network_filters/network_filters http_conn_man/http_conn_man http_filters/http_filters diff --git a/docs/root/configuration/listener_filters/listener_filters.rst b/docs/root/configuration/listener_filters/listener_filters.rst new file mode 100644 index 000000000..a61fd3ab2 --- /dev/null +++ b/docs/root/configuration/listener_filters/listener_filters.rst @@ -0,0 +1,11 @@ +.. _config_listener_filters: + +Listener filters +================ + +Envoy has the follow builtin listener filters. + +.. toctree:: + :maxdepth: 2 + + original_dst_filter diff --git a/docs/root/configuration/listener_filters/original_dst_filter.rst b/docs/root/configuration/listener_filters/original_dst_filter.rst new file mode 100644 index 000000000..bae339eb4 --- /dev/null +++ b/docs/root/configuration/listener_filters/original_dst_filter.rst @@ -0,0 +1,13 @@ +.. _config_listener_filters_original_dst: + +Original Destination +==================== + +Original destination listener filter reads the SO_ORIGINAL_DST socket option set when a connection +has been redirected by iptables REDIRECT. Later processing in Envoy sees the restored destination +address as the connection's local address, rather than the address at which the listener is +listening at. Furthermore, :ref:`an original destination cluster +` may be used to forward HTTP requests +or TCP connections to the restored destination address. + +* :ref:`v2 API reference ` diff --git a/docs/root/intro/arch_overview/arch_overview.rst b/docs/root/intro/arch_overview/arch_overview.rst index e147985e5..0b5e7d9b7 100644 --- a/docs/root/intro/arch_overview/arch_overview.rst +++ b/docs/root/intro/arch_overview/arch_overview.rst @@ -7,6 +7,7 @@ Architecture overview terminology threading_model listeners + listener_filters network_filters http_connection_management http_filters diff --git a/docs/root/intro/arch_overview/dynamic_configuration.rst b/docs/root/intro/arch_overview/dynamic_configuration.rst index bbce93e0c..ceb4be0ef 100644 --- a/docs/root/intro/arch_overview/dynamic_configuration.rst +++ b/docs/root/intro/arch_overview/dynamic_configuration.rst @@ -18,7 +18,7 @@ Fully static ------------ In a fully static configuration, the implementor provides a set of :ref:`listeners -` (and :ref:`filter chains `), :ref:`clusters +` (and :ref:`filter chains `), :ref:`clusters `, and optionally :ref:`HTTP route configurations `. Dynamic host discovery is only possible via DNS based :ref:`service discovery `. Configuration reloads must take place diff --git a/docs/root/intro/arch_overview/listener_filters.rst b/docs/root/intro/arch_overview/listener_filters.rst new file mode 100644 index 000000000..74635afa3 --- /dev/null +++ b/docs/root/intro/arch_overview/listener_filters.rst @@ -0,0 +1,16 @@ +.. _arch_overview_listener_filters: + +Listener filters +================ + +As discussed in the :ref:`listener ` section, listener filters may be +used to manipulate connection metadata. The main purpose of listener filters is to make adding +further system integration functions easier by not requiring changes to Envoy core functionality, +and also make interaction between multiple such features more explicit. + +The API for listener filters is relatively simple since ultimately these filters operate on newly +accepted sockets. Filters in the chain can stop and subsequently continue iteration to +further filters. This allows for more complex scenarios such as calling a :ref:`rate limiting +service `, etc. Envoy already includes several listener filters that +are documented in this architecture overview as well as the :ref:`configuration reference +`. diff --git a/docs/root/intro/arch_overview/listeners.rst b/docs/root/intro/arch_overview/listeners.rst index c34a5683a..30717b380 100644 --- a/docs/root/intro/arch_overview/listeners.rst +++ b/docs/root/intro/arch_overview/listeners.rst @@ -17,6 +17,11 @@ used for (e.g., :ref:`rate limiting `, :ref:`TLS clien MongoDB :ref:`sniffing `, raw :ref:`TCP proxy `, etc.). +Listeners are optionally also configured with some number of :ref:`listener filters +`. These filters are processed before the network level filters, +and have the opportunity to manipulate the connection metadata, usually to influence how the +connection is processed later filters or clusters. + Listeners can also be fetched dynamically via the :ref:`listener discovery service (LDS) `.