UDP proxy

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

config/filter/udp/udp_proxy/v2alpha/udp_proxy.proto

This extension may be referenced by the qualified name envoy.filters.udp_listener.udp_proxy

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

• envoy.filters.udp_listener

UDP proxy configuration overview.

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig proto]

Configuration for the UDP proxy filter.

{
  "stat_prefix": "...",
  "cluster": "...",
  "idle_timeout": "{...}",
  "use_original_src_ip": "...",
  "hash_policies": [],
  "upstream_socket_config": "{...}"
}

stat_prefix

(string, REQUIRED) The stat prefix used when emitting UDP proxy filter stats.

cluster

(string, REQUIRED) The upstream cluster to connect to.

idle_timeout

(Duration) The idle timeout for sessions. Idle is defined as no datagrams between received or sent by the session. The default if not specified is 1 minute.

use_original_src_ip

(bool) Use the remote downstream IP address as the sender IP address when sending packets to upstream hosts. This option requires Envoy to be run with the CAP_NET_ADMIN capability on Linux. And the IPv6 stack must be enabled on Linux kernel. This option does not preserve the remote downstream port. If this option is enabled, the IP address of sent datagrams will be changed to the remote downstream IP address. This means that Envoy will not receive packets that are sent by upstream hosts because the upstream hosts will send the packets with the remote downstream IP address as the destination. All packets will be routed to the remote downstream directly if there are route rules on the upstream host side. There are two options to return the packets back to the remote downstream. The first one is to use DSR (Direct Server Return). The other one is to configure routing rules on the upstream hosts to forward all packets back to Envoy and configure iptables rules on the host running Envoy to forward all packets from upstream hosts to the Envoy process so that Envoy can forward the packets to the downstream. If the platform does not support this option, Envoy will raise a configuration error.

hash_policies

(repeated extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.HashPolicy) Optional configuration for UDP proxy hash policies. If hash_policies is not set, the hash-based load balancing algorithms will select a host randomly. Currently the number of hash policies is limited to 1.

upstream_socket_config

(config.core.v3.UdpSocketConfig) UDP socket configuration for upstream sockets. The default for prefer_gro is true for upstream sockets as the assumption is datagrams will be received from a single source.

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.HashPolicy

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.HashPolicy proto]

Specifies the UDP hash policy. The packets can be routed by hash policy.

{
  "source_ip": "...",
  "key": "..."
}

source_ip

(bool) The source IP will be used to compute the hash used by hash-based load balancing algorithms.

Precisely one of source_ip, key must be set.

key

(string) A given key will be used to compute the hash used by hash-based load balancing algorithms. In certain cases there is a need to direct different UDP streams jointly towards the selected set of endpoints. A possible use-case is VoIP telephony, where media (RTP) and its corresponding control (RTCP) belong to the same logical session, although they travel in separate streams. To ensure that these pair of streams are load-balanced on session level (instead of individual stream level), dynamically created listeners can use the same hash key for each stream in the session.

Precisely one of source_ip, key must be set.