listeners: add unified matcher for filter chains #20110
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| static_resources: | ||
| listeners: | ||
| - name: outbound | ||
| address: | ||
| socket_address: | ||
| protocol: TCP | ||
| address: 0.0.0.0 | ||
| port_value: 15000 | ||
| listener_filters: | ||
| - name: original_dst | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.listener.original_dst.v3.OriginalDst | ||
| traffic_direction: OUTBOUND | ||
| filter_chains: | ||
| - name: http | ||
| filters: | ||
| - name: http_connection_manager | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager | ||
| stat_prefix: ingress_http | ||
| route_config: | ||
| name: local_route | ||
| virtual_hosts: | ||
| - name: local_service | ||
| domains: ["*"] | ||
| routes: | ||
| - match: | ||
| prefix: "/" | ||
| route: | ||
| cluster: some_service | ||
| http_filters: | ||
| - name: router | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router | ||
| - name: internal | ||
| filters: | ||
| - name: tcp_proxy | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy | ||
| stat_prefix: internal | ||
| cluster: some_service | ||
| - name: tls | ||
| transport_socket: | ||
| name: tls | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext | ||
| common_tls_context: | ||
| tls_certificates: | ||
| - certificate_chain: {filename: "certs/servercert.pem"} | ||
| private_key: {filename: "certs/serverkey.pem"} | ||
| filters: | ||
| - name: tcp_proxy | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy | ||
| stat_prefix: tls | ||
| cluster: some_service | ||
| # Snippet: 58-102 | ||
| filter_chain_matcher: | ||
| matcher_tree: | ||
| input: | ||
| name: port | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.network.v3.DestinationPortInput | ||
| exact_match_map: | ||
| map: | ||
| "80": | ||
| action: | ||
| name: http | ||
| typed_config: | ||
| "@type": type.googleapis.com/google.protobuf.StringValue | ||
| value: http | ||
| "443": | ||
| matcher: | ||
| matcher_tree: | ||
| input: | ||
| name: ip | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.network.v3.SourceIPInput | ||
htuch marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| custom_match: | ||
| name: ip-matcher | ||
| typed_config: | ||
| "@type": type.googleapis.com/xds.type.matcher.v3.IPMatcher | ||
| range_matchers: | ||
| - ranges: | ||
| - address_prefix: 192.0.0.0 | ||
| prefix_len: 2 | ||
| - address_prefix: 10.0.0.0 | ||
| prefix_len: 24 | ||
| on_match: | ||
| action: | ||
| name: internal | ||
| typed_config: | ||
| "@type": type.googleapis.com/google.protobuf.StringValue | ||
| value: internal | ||
| - ranges: | ||
| - address_prefix: 0.0.0.0 | ||
| on_match: | ||
| action: | ||
| name: tls | ||
| typed_config: | ||
| "@type": type.googleapis.com/google.protobuf.StringValue | ||
| value: tls | ||
|
|
||
| clusters: | ||
| - name: some_service | ||
| load_assignment: | ||
| cluster_name: some_service | ||
| endpoints: | ||
| - lb_endpoints: | ||
| - endpoint: | ||
| address: | ||
| socket_address: | ||
| address: 10.1.2.10 | ||
| port_value: 10002 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| static_resources: | ||
| listeners: | ||
| - name: outbound | ||
| address: | ||
| socket_address: | ||
| protocol: TCP | ||
| address: 0.0.0.0 | ||
| port_value: 8443 | ||
| listener_filters: | ||
| - name: tls_inspector | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector | ||
| filter_chains: | ||
| - name: tls | ||
| transport_socket: | ||
| name: tls | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext | ||
| common_tls_context: | ||
| tls_certificates: | ||
| - certificate_chain: {filename: "certs/servercert.pem"} | ||
| private_key: {filename: "certs/serverkey.pem"} | ||
| filters: | ||
| - name: tcp_proxy | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy | ||
| stat_prefix: tls | ||
| cluster: some_service | ||
| - name: plaintext | ||
| filters: | ||
| - name: tcp_proxy | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy | ||
| stat_prefix: plaintext | ||
| cluster: some_service | ||
| # Snippet: 37-56 | ||
| filter_chain_matcher: | ||
| matcher_tree: | ||
| input: | ||
| name: transport | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.network.v3.TransportProtocolInput | ||
| exact_match_map: | ||
| map: | ||
| "tls": | ||
| action: | ||
| name: tls | ||
| typed_config: | ||
| "@type": type.googleapis.com/google.protobuf.StringValue | ||
| value: tls | ||
|
Comment on lines
+46
to
+50
There was a problem hiding this comment. Maybe I am missing some context, but could this be simplified to just have the There was a problem hiding this comment. There is a proposal cncf/xds#28. |
||
| on_no_match: | ||
| action: | ||
| name: plaintext | ||
| typed_config: | ||
| "@type": type.googleapis.com/google.protobuf.StringValue | ||
| value: plaintext | ||
|
|
||
| clusters: | ||
| - name: some_service | ||
| load_assignment: | ||
| cluster_name: some_service | ||
| endpoints: | ||
| - lb_endpoints: | ||
| - endpoint: | ||
| address: | ||
| socket_address: | ||
| address: 10.1.2.10 | ||
| port_value: 10002 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| static_resources: | ||
| listeners: | ||
| - name: outbound | ||
| address: | ||
| socket_address: | ||
| protocol: TCP | ||
| address: 0.0.0.0 | ||
| port_value: 15000 | ||
| listener_filters: | ||
| - name: proxy_protocol | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol | ||
| filter_chains: | ||
| - name: vip | ||
| filters: | ||
| - name: tcp_proxy | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy | ||
| stat_prefix: vip | ||
| cluster: original_dst | ||
| - name: default | ||
| filters: | ||
| - name: tcp_proxy | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy | ||
| stat_prefix: default | ||
| cluster: original_dst | ||
| # Snippet: 29-48 | ||
| filter_chain_matcher: | ||
| matcher_tree: | ||
| input: | ||
| name: destination_ip | ||
| typed_config: | ||
| "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.network.v3.DestinationIPInput | ||
| prefix_match_map: | ||
| map: | ||
| "10.0.0.": | ||
| action: | ||
| name: vip | ||
| typed_config: | ||
| "@type": type.googleapis.com/google.protobuf.StringValue | ||
| value: vip | ||
| on_no_match: | ||
| action: | ||
| name: default | ||
| typed_config: | ||
| "@type": type.googleapis.com/google.protobuf.StringValue | ||
| value: default | ||
|
|
||
| clusters: | ||
| - name: original_dst | ||
| type: ORIGINAL_DST | ||
| lb_policy: CLUSTER_PROVIDED |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,3 +5,4 @@ Generic Matching | |
| :maxdepth: 2 | ||
|
|
||
| matching_api | ||
| matching_listener | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| .. _arch_overview_matching_listener: | ||
|
|
||
| Matching Filter Chains in Listeners | ||
| =================================== | ||
|
|
||
| Envoy listeners implement the :ref:`matching API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>` for selecting a filter | ||
| chain based on a collection of :ref:`network inputs <extension_category_envoy.matching.network.input>`. Matching is done | ||
| once per connection. Connections are drained when the associated named filter chain configuration changes, but not when | ||
| the filter chain matcher is the only updated field in a listener. | ||
|
|
||
| The action in the matcher API must be a string value corresponding to the name of the filter chain. If there is no | ||
| filter chain with the given name, the match fails, and the :ref:`default filter chain | ||
| <envoy_v3_api_field_config.listener.v3.Listener.default_filter_chain>` is used if specified, or the connection is | ||
| rejected. Filter chain matcher requires that all filter chains in a listener are uniquely named. | ||
|
|
||
| The matcher API replaces the existing filter :ref:`filter_chain_match | ||
| <envoy_v3_api_field_config.listener.v3.FilterChain.filter_chain_match>` field. When using the matcher API, the filter | ||
| chain match field is ignored and should not be set. | ||
|
Comment on lines
+16
to
+18
There was a problem hiding this comment. Should this be exposed to the user in some way? ie fail the config or at the very least log something? There was a problem hiding this comment. Added a debug log. Failing might complicate migration IMHO, so just ignoring the field seems reasonable as it is an opt-in feature. |
||
|
|
||
| Examples | ||
| ######## | ||
|
|
||
| Detect TLS traffic | ||
| ****************** | ||
|
|
||
| The following examples uses :ref:`tls_inspector <config_listener_filters_tls_inspector>` listener filter to detect | ||
| whether the transport appears to be TLS, in which case the matcher in the listener selects the filter chain ``tls``. | ||
| Otherwise, the filter chain ``plaintext`` is used. | ||
|
|
||
| .. literalinclude:: _include/listener_tls.yaml | ||
| :language: yaml | ||
| :lines: 37-56 | ||
|
There was a problem hiding this comment. if we are going to include it would also be good to include a caption so users can get the entire file: There was a problem hiding this comment. Done. I removed the line numbers, don't seem essential. There was a problem hiding this comment. i think they are a helpful guide to the user - both visually that there is a full file that the snippet is taken from and for quickly finding the snippet in the config i wont block on it tho as usage is inconsistent elsewhere |
||
| :caption: :download:`listener_tls.yaml <_include/listener_tls.yaml>` | ||
|
|
||
| Match Against the Destination IP | ||
| ******************************** | ||
|
|
||
| The following example assumes :ref:`PROXY protocol <config_listener_filters_proxy_protocol>` is used for incoming | ||
| traffic. If the recovered destination IP is in CIDR ``10.0.0.0/24``, then the filter chain ``vip`` is used. Otherwise, | ||
| the filter chain ``default`` is used. | ||
|
|
||
| .. literalinclude:: _include/listener_vip.yaml | ||
| :language: yaml | ||
| :lines: 29-48 | ||
| :caption: :download:`listener_vip.yaml <_include/listener_vip.yaml>` | ||
|
|
||
| Match Against the Destination Port and the Source IP | ||
| **************************************************** | ||
|
|
||
| The following example uses :ref:`original_dst <config_listener_filters_original_dst>` listener filter to recover the | ||
| original destination port. The matcher in the listener selects one of the three filter chains ``http``, ``internal``, | ||
| and ``tls`` as follows: | ||
|
|
||
| * If the destination port is ``80``, then the filter chain ``http`` accepts the connection. | ||
| * If the destination port is ``443`` and the source IP is in the range ``192.0.0.0/2`` or ``10.0.0.0/24``, then the | ||
| filter chain ``internal`` accepts the connection. If the source IP is not in the ranges then the filter chain ``tls`` | ||
| accepts the connection. | ||
| * Otherwise, the connection is rejected, because there is no default filter chain. | ||
|
|
||
| .. literalinclude:: _include/listener_complicated.yaml | ||
| :language: yaml | ||
| :lines: 58-102 | ||
| :caption: :download:`listener_complicated.yaml <_include/listener_complicated.yaml>` | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What happens if both are defined?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The filter chain match is ignored when listener matcher is defined. I added a debug log to warn on listener construction.