TCP Proxy

TCP Proxy configuration overview.

config.filter.network.tcp_proxy.v2.TcpProxy

[config.filter.network.tcp_proxy.v2.TcpProxy proto]

{
  "stat_prefix": "...",
  "cluster": "...",
  "weighted_clusters": "{...}",
  "metadata_match": "{...}",
  "idle_timeout": "{...}",
  "access_log": [],
  "deprecated_v1": "{...}",
  "max_connect_attempts": "{...}"
}
stat_prefix
(string, REQUIRED) The prefix to use when emitting statistics.
cluster

(string) The upstream cluster to connect to.

Note

Complex routing (based on connection properties) is being implemented in listeners. Once fully implemented, this field (or weighted_clusters) will be the only way to configure the target cluster. In the interim, complex routing requires using a deprecated_v1 configuration. This field is ignored if a deprecated_v1 configuration is set.

Precisely one of cluster, weighted_clusters must be set.

weighted_clusters

(config.filter.network.tcp_proxy.v2.TcpProxy.WeightedCluster) Multiple upstream clusters can be specified for a given route. The request is routed to one of the upstream clusters based on weights assigned to each cluster.

Note

This field is ignored if the deprecated_v1 configuration is set.

Precisely one of cluster, weighted_clusters must be set.

metadata_match
(core.Metadata) Optional endpoint metadata match criteria. Only endpoints in the upstream cluster with metadata matching that set in metadata_match will be considered. The filter name should be specified as envoy.lb.
idle_timeout
(Duration) The idle timeout for connections managed by the TCP proxy filter. The idle timeout is defined as the period in which there are no bytes sent or received on either the upstream or downstream connection. If not set, connections will never be closed by the TCP proxy due to being idle.
access_log
(config.filter.accesslog.v2.AccessLog) Configuration for access logs emitted by the this tcp_proxy.
deprecated_v1

(config.filter.network.tcp_proxy.v2.TcpProxy.DeprecatedV1) TCP Proxy filter configuration using deprecated V1 format. This is required for complex routing until filter chain matching in the listener is implemented.

Example:

- name: "envoy.tcp_proxy"
  config:
    deprecated_v1: true
    value:
      stat_prefix: "prefix"
      access_log:
        - ...
      route_config:
        routes:
          - cluster: "cluster"
            destination_ip_list:
              - "10.1.0.0/8"
            destination_ports: "8080"
            source_ip_list:
              - "10.1.0.0/16"
              - "2001:db8::/32"
            source_ports: "8000,9000-9999"

Attention

Using the deprecated V1 configuration excludes the use of any V2 configuration options. Only the V1 configuration is used. All available fields are shown in the example, although the access log configuration is omitted for simplicity. The access log configuration uses the deprecated V1 access log configuration.

Attention

In the deprecated V1 configuration, source and destination CIDR ranges are specified as a list of strings with each string in CIDR notation. Source and destination ports are specified as single strings containing a comma-separated list of ports and/or port ranges.

max_connect_attempts
(UInt32Value) The maximum number of unsuccessful connection attempts that will be made before giving up. If the parameter is not specified, 1 connection attempt will be made.

config.filter.network.tcp_proxy.v2.TcpProxy.DeprecatedV1

[config.filter.network.tcp_proxy.v2.TcpProxy.DeprecatedV1 proto]

TCP Proxy filter configuration using V1 format, until Envoy gets the ability to match source/destination at the listener level (called filter chain match).

{
  "routes": []
}
routes
(config.filter.network.tcp_proxy.v2.TcpProxy.DeprecatedV1.TCPRoute, REQUIRED) The route table for the filter. All filter instances must have a route table, even if it is empty.

config.filter.network.tcp_proxy.v2.TcpProxy.DeprecatedV1.TCPRoute

[config.filter.network.tcp_proxy.v2.TcpProxy.DeprecatedV1.TCPRoute proto]

A TCP proxy route consists of a set of optional L4 criteria and the name of a cluster. If a downstream connection matches all the specified criteria, the cluster in the route is used for the corresponding upstream connection. Routes are tried in the order specified until a match is found. If no match is found, the connection is closed. A route with no criteria is valid and always produces a match.

{
  "cluster": "...",
  "destination_ip_list": [],
  "destination_ports": "...",
  "source_ip_list": [],
  "source_ports": "..."
}
cluster
(string, REQUIRED) The cluster to connect to when a the downstream network connection matches the specified criteria.
destination_ip_list
(core.CidrRange) An optional list of IP address subnets in the form “ip_address/xx”. The criteria is satisfied if the destination IP address of the downstream connection is contained in at least one of the specified subnets. If the parameter is not specified or the list is empty, the destination IP address is ignored. The destination IP address of the downstream connection might be different from the addresses on which the proxy is listening if the connection has been redirected.
destination_ports
(string) An optional string containing a comma-separated list of port numbers or ranges. The criteria is satisfied if the destination port of the downstream connection is contained in at least one of the specified ranges. If the parameter is not specified, the destination port is ignored. The destination port address of the downstream connection might be different from the port on which the proxy is listening if the connection has been redirected.
source_ip_list
(core.CidrRange) An optional list of IP address subnets in the form “ip_address/xx”. The criteria is satisfied if the source IP address of the downstream connection is contained in at least one of the specified subnets. If the parameter is not specified or the list is empty, the source IP address is ignored.
source_ports
(string) An optional string containing a comma-separated list of port numbers or ranges. The criteria is satisfied if the source port of the downstream connection is contained in at least one of the specified ranges. If the parameter is not specified, the source port is ignored.

config.filter.network.tcp_proxy.v2.TcpProxy.WeightedCluster

[config.filter.network.tcp_proxy.v2.TcpProxy.WeightedCluster proto]

Allows for specification of multiple upstream clusters along with weights that indicate the percentage of traffic to be forwarded to each cluster. The router selects an upstream cluster based on these weights.

{
  "clusters": []
}
clusters
(config.filter.network.tcp_proxy.v2.TcpProxy.WeightedCluster.ClusterWeight, REQUIRED) Specifies one or more upstream clusters associated with the route.

config.filter.network.tcp_proxy.v2.TcpProxy.WeightedCluster.ClusterWeight

[config.filter.network.tcp_proxy.v2.TcpProxy.WeightedCluster.ClusterWeight proto]

{
  "name": "...",
  "weight": "..."
}
name
(string, REQUIRED) Name of the upstream cluster.
weight
(uint32) When a request matches the route, the choice of an upstream cluster is determined by its weight. The sum of weights across all entries in the clusters array determines the total weight.