From 02b4a5ed05f7e9909417bfd82b0493c2835d3b9e Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Mon, 28 Aug 2017 12:39:48 -0700 Subject: [PATCH 01/12] lds: Add listener_filter_chain. Add listener_filter_chain to Listener, which is a list of individual listener filters that make up the filter chain for sockets accepted with the listener. These filters are run before any in the 'filter_chains', and these filters have the opportunity to manipulate and augment the connection metadata that is used in connection filter chain matching. Order matters as the filters are processed sequentially right after a socket has been accepted by the listener, and before a connection is created. As an example the functionality controlled by Listener options 'use_original_dst' and 'use_proxy_proto' can be implemented as listener filters instead of being hard-wired into Envoy's listener logic. This makes also extensions (like proxy protocol v2) easier to implement and deploy. Signed-off-by: Jarno Rajahalme --- api/lds.proto | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/api/lds.proto b/api/lds.proto index 8fdc97def..8f7ef00aa 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -103,6 +103,15 @@ message Listener { // The type of draining to perform at a listener-wide level. DrainType drain_type = 8; + + // A list of individual listener filters that make up the filter chain for + // sockets accepted with the listener. These filters are run before + // any in the 'filter_chains', and these filters have the opportunity + // to manipulate and augment the connection metadata that is used in + // connection filter chain matching. 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 Filter listener_filter_chain = 9; } message Filter { From 74a163a61bcf6f6f98a47f655c49215f874f4649 Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Fri, 5 Jan 2018 17:18:08 -0800 Subject: [PATCH 02/12] lds: Fix spacing. Remove over-enthusiastic spaces, re-fill comment. Signed-off-by: Jarno Rajahalme --- api/lds.proto | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/api/lds.proto b/api/lds.proto index 8f7ef00aa..02174f9a5 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -104,13 +104,11 @@ message Listener { // The type of draining to perform at a listener-wide level. DrainType drain_type = 8; - // A list of individual listener filters that make up the filter chain for - // sockets accepted with the listener. These filters are run before - // any in the 'filter_chains', and these filters have the opportunity - // to manipulate and augment the connection metadata that is used in - // connection filter chain matching. Order matters as the filters are - // processed sequentially right after a socket has been accepted by - // the listener, and before a connection is created. + // A list of individual listener filters that make up the filter chain for sockets accepted with + // the listener. These filters are run before any in the 'filter_chains', and these filters have + // the opportunity to manipulate and augment the connection metadata that is used in connection + // filter chain matching. 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 Filter listener_filter_chain = 9; } From 113052ead4e896db963c2a1482de87977c7f92c4 Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Wed, 10 Jan 2018 13:59:01 -0800 Subject: [PATCH 03/12] lds: Rename 'listener_filter_chain' to 'listener_filters' Suggested-by: Piotr Sikora Signed-off-by: Jarno Rajahalme --- api/lds.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/lds.proto b/api/lds.proto index 02174f9a5..173c3b489 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -109,7 +109,7 @@ message Listener { // the opportunity to manipulate and augment the connection metadata that is used in connection // filter chain matching. 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 Filter listener_filter_chain = 9; + repeated Filter listener_filters = 9; } message Filter { From 6f24f4d5972a7c282e79f6116137a31cd6e37af4 Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Wed, 10 Jan 2018 19:25:40 -0800 Subject: [PATCH 04/12] lds: link to filter_chains in comment. Signed-off-by: Jarno Rajahalme --- api/lds.proto | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/lds.proto b/api/lds.proto index 173c3b489..ecc0ca5d4 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -105,7 +105,8 @@ message Listener { DrainType drain_type = 8; // A list of individual listener filters that make up the filter chain for sockets accepted with - // the listener. These filters are run before any in the 'filter_chains', and these filters have + // the listener. These filters are run before any in the + // :ref:`filter_chains `, and these filters have // the opportunity to manipulate and augment the connection metadata that is used in connection // filter chain matching. Order matters as the filters are processed sequentially right after a // socket has been accepted by the listener, and before a connection is created. From 0dd802c14296e2f1f75b8b68e3260bfa3d392a18 Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Thu, 11 Jan 2018 09:08:55 -0800 Subject: [PATCH 05/12] lds: Rephrase the comment on 'listener_filters' Requested-by: Hong Zhang Signed-off-by: Jarno Rajahalme --- api/lds.proto | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/api/lds.proto b/api/lds.proto index ecc0ca5d4..01e0af719 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -104,12 +104,11 @@ message Listener { // The type of draining to perform at a listener-wide level. DrainType drain_type = 8; - // A list of individual listener filters that make up the filter chain for sockets accepted with - // the listener. These filters are run before any in the - // :ref:`filter_chains `, and these filters have - // the opportunity to manipulate and augment the connection metadata that is used in connection - // filter chain matching. Order matters as the filters are processed sequentially right after a - // socket has been accepted by the listener, and before a connection is created. + // 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 Filter listener_filters = 9; } From 2ce8e722cb801dce35c7267f9a0c94fea5eb3b1e Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Fri, 12 Jan 2018 18:56:03 -0800 Subject: [PATCH 06/12] lds: Define ListenerFilter message type. Use a distinct type for ListenerFilters. This allows future extensions independent of the network Filter message. ListenerFilter message type is v2 only, so it does not need v1 compatibility fields. Requested-by: Greg Greenway Signed-off-by: Jarno Rajahalme --- api/lds.proto | 16 +++++++++++++++- .../listener_filters/original_dst_filter.rst | 10 ++++++++++ .../listener_filters/proxy_protocol_filter.rst | 13 +++++++++++++ 3 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 docs/root/configuration/listener_filters/original_dst_filter.rst create mode 100644 docs/root/configuration/listener_filters/proxy_protocol_filter.rst diff --git a/api/lds.proto b/api/lds.proto index 01e0af719..1781cf10b 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -109,7 +109,7 @@ message Listener { // :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 Filter listener_filters = 9; + repeated ListenerFilter listener_filters = 9; } message Filter { @@ -212,3 +212,17 @@ 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.original_dst ` + // * :ref:`envoy.proxy_protocol ` + 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/configuration/listener_filters/original_dst_filter.rst b/docs/root/configuration/listener_filters/original_dst_filter.rst new file mode 100644 index 000000000..e1b2199ee --- /dev/null +++ b/docs/root/configuration/listener_filters/original_dst_filter.rst @@ -0,0 +1,10 @@ +.. _config_network_filters_echo: + +Echo +==== + +The echo is a trivial network filter mainly meant to demonstrate the network filter API. If +installed it will echo (write) all received data back to the connected downstream client. + +* :ref:`v1 API reference ` +* :ref:`v2 API reference ` diff --git a/docs/root/configuration/listener_filters/proxy_protocol_filter.rst b/docs/root/configuration/listener_filters/proxy_protocol_filter.rst new file mode 100644 index 000000000..fe1d9d744 --- /dev/null +++ b/docs/root/configuration/listener_filters/proxy_protocol_filter.rst @@ -0,0 +1,13 @@ +.. _config_listener_filters_proxy_protocol: + +Proxy Protocol +============== + +Proxy protocol filter processes the `PROXY protocol V1 +`_ header added by some load balancers +(e.g., AWL ELB) on new connections. With this the listener will assume that that remote address of +the connection is the one specified in the header. If this filter is not used, Envoy will use the +physical peer address of the connection as the remote address. Note that if the proxy protocol +header is present, further handling of the connection may fail if this filter is not used. + +* :ref:`v2 API reference ` From fd02c813ac15cb13ab8d94ff0598d302327caebc Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Mon, 15 Jan 2018 17:05:39 -0800 Subject: [PATCH 07/12] docs: Add basic listener filter documentation. Signed-off-by: Jarno Rajahalme --- docs/root/api-v1/listeners/listeners.rst | 4 ++-- .../listener_filters/listener_filters.rst | 12 ++++++++++++ .../listener_filters/original_dst_filter.rst | 15 +++++++++------ .../arch_overview/dynamic_configuration.rst | 2 +- .../intro/arch_overview/listener_filters.rst | 19 +++++++++++++++++++ docs/root/intro/arch_overview/listeners.rst | 5 +++++ 6 files changed, 48 insertions(+), 9 deletions(-) create mode 100644 docs/root/configuration/listener_filters/listener_filters.rst create mode 100644 docs/root/intro/arch_overview/listener_filters.rst 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/listener_filters/listener_filters.rst b/docs/root/configuration/listener_filters/listener_filters.rst new file mode 100644 index 000000000..30f37c483 --- /dev/null +++ b/docs/root/configuration/listener_filters/listener_filters.rst @@ -0,0 +1,12 @@ +.. _config_listener_filters: + +Listener filters +================ + +Envoy has the follow builtin listener filters. + +.. toctree:: + :maxdepth: 2 + + original_dst_filter + proxy_protocol_filter diff --git a/docs/root/configuration/listener_filters/original_dst_filter.rst b/docs/root/configuration/listener_filters/original_dst_filter.rst index e1b2199ee..bae339eb4 100644 --- a/docs/root/configuration/listener_filters/original_dst_filter.rst +++ b/docs/root/configuration/listener_filters/original_dst_filter.rst @@ -1,10 +1,13 @@ -.. _config_network_filters_echo: +.. _config_listener_filters_original_dst: -Echo -==== +Original Destination +==================== -The echo is a trivial network filter mainly meant to demonstrate the network filter API. If -installed it will echo (write) all received data back to the connected downstream client. +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:`v1 API reference ` * :ref:`v2 API reference ` 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..d13b5b0d9 --- /dev/null +++ b/docs/root/intro/arch_overview/listener_filters.rst @@ -0,0 +1,19 @@ +.. _arch_overview_listener_filters: + +Listener filters +================ + +As discussed in the :ref:`listener ` section, listener filters may be +used to manipulate connection metadata. In fact, Envoy implements :ref:`*use_original_dst* and +*bind_to_port* listener options ` internally by passing the newly accepted +connection through listener filters implementing these functions. Main purpose of listener filters +is to make adding further system integration functions easier by not requiring changes to Envoy +core functionlity, and also makes interaction between multiple such features more explicit. +filters: + +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) `. From 11d9ab47b8cd810fab4b9351ced1c4e6d44e5eeb Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Tue, 16 Jan 2018 09:42:40 -0800 Subject: [PATCH 08/12] docs: Add listener_filters/listener_filters to toctree. Signed-off-by: Jarno Rajahalme --- docs/root/configuration/configuration.rst | 1 + 1 file changed, 1 insertion(+) 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 From 362031f5b716b6019b1ec9c6df2bc41f0eec25a4 Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Tue, 16 Jan 2018 09:57:28 -0800 Subject: [PATCH 09/12] docs: Add arch_overview/listener_filters.rst to the toctree. Signed-off-by: Jarno Rajahalme --- docs/root/intro/arch_overview/arch_overview.rst | 1 + 1 file changed, 1 insertion(+) 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 From a7e6fdf9fbbb6d9a5f6b596060e67e4bf369c1c1 Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Thu, 18 Jan 2018 16:12:04 -0800 Subject: [PATCH 10/12] docs: Remove proxy protocol listener filter from the docs. Proxy protocol needs to be run after filter chain has been selected. Remove it from the list of built in filters. Signed-off-by: Jarno Rajahalme --- api/lds.proto | 3 +-- .../listener_filters/listener_filters.rst | 1 - .../listener_filters/proxy_protocol_filter.rst | 13 ------------- 3 files changed, 1 insertion(+), 16 deletions(-) delete mode 100644 docs/root/configuration/listener_filters/proxy_protocol_filter.rst diff --git a/api/lds.proto b/api/lds.proto index 1781cf10b..e98c1faf9 100644 --- a/api/lds.proto +++ b/api/lds.proto @@ -218,8 +218,7 @@ message ListenerFilter { // filter. The built-in filters are: // // [#comment:TODO(mattklein123): Auto generate the following list] - // * :ref:`envoy.original_dst ` - // * :ref:`envoy.proxy_protocol ` + // * :ref:`envoy.listener.original_dst ` string name = 1 [(validate.rules).string.min_bytes = 1]; // Filter specific configuration which depends on the filter being diff --git a/docs/root/configuration/listener_filters/listener_filters.rst b/docs/root/configuration/listener_filters/listener_filters.rst index 30f37c483..a61fd3ab2 100644 --- a/docs/root/configuration/listener_filters/listener_filters.rst +++ b/docs/root/configuration/listener_filters/listener_filters.rst @@ -9,4 +9,3 @@ Envoy has the follow builtin listener filters. :maxdepth: 2 original_dst_filter - proxy_protocol_filter diff --git a/docs/root/configuration/listener_filters/proxy_protocol_filter.rst b/docs/root/configuration/listener_filters/proxy_protocol_filter.rst deleted file mode 100644 index fe1d9d744..000000000 --- a/docs/root/configuration/listener_filters/proxy_protocol_filter.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _config_listener_filters_proxy_protocol: - -Proxy Protocol -============== - -Proxy protocol filter processes the `PROXY protocol V1 -`_ header added by some load balancers -(e.g., AWL ELB) on new connections. With this the listener will assume that that remote address of -the connection is the one specified in the header. If this filter is not used, Envoy will use the -physical peer address of the connection as the remote address. Note that if the proxy protocol -header is present, further handling of the connection may fail if this filter is not used. - -* :ref:`v2 API reference ` From d6f8842e5dab4caebc60fa1bf1e2fac0055a6227 Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Mon, 22 Jan 2018 14:21:37 -0800 Subject: [PATCH 11/12] docs: Review fixes. Signed-off-by: Jarno Rajahalme --- docs/root/intro/arch_overview/listener_filters.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/root/intro/arch_overview/listener_filters.rst b/docs/root/intro/arch_overview/listener_filters.rst index d13b5b0d9..74635afa3 100644 --- a/docs/root/intro/arch_overview/listener_filters.rst +++ b/docs/root/intro/arch_overview/listener_filters.rst @@ -4,12 +4,9 @@ Listener filters ================ As discussed in the :ref:`listener ` section, listener filters may be -used to manipulate connection metadata. In fact, Envoy implements :ref:`*use_original_dst* and -*bind_to_port* listener options ` internally by passing the newly accepted -connection through listener filters implementing these functions. Main purpose of listener filters -is to make adding further system integration functions easier by not requiring changes to Envoy -core functionlity, and also makes interaction between multiple such features more explicit. -filters: +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 From e2a201a77a759600f8bb863b009faee6e350db5b Mon Sep 17 00:00:00 2001 From: Jarno Rajahalme Date: Mon, 22 Jan 2018 16:58:45 -0800 Subject: [PATCH 12/12] lds: Deprecate 'use_original_dst' flag. Same functionality can be attained by other v2 API features, namely listener filters and filter chain match. Signed-off-by: Jarno Rajahalme --- api/lds.proto | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/api/lds.proto b/api/lds.proto index e98c1faf9..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).