| Attachment | Type URL (@type) | Per-route override | Build feature |
|---|---|---|---|
Filter chain (filters, terminal) | type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy | Not applicable | None |
What it does
The TCP proxy forwards the connection's bytes verbatim to an upstream cluster — no HTTP parsing, no request-level filters. Use it for any non-HTTP protocol, or for TLS passthrough where the filter chain is selected by SNI and the encrypted stream is relayed untouched. Like the HTTP connection manager, it is a terminal filter: exactly one ends each filter chain.
Minimal configuration
The fragment sits under filter_chains[].filters of a listener:
- name: tcp
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
cluster: backendFields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
cluster / weighted_clusters | oneof | Yes | — | Target cluster, or a weighted split (see below). |
stat_prefix | string | No | — | Accepted for Envoy compatibility but ignored; Arion logs a warning. |
access_log | list | No | empty | Connection access loggers; see access logs. |
All other Envoy TCP proxy fields — idle timeouts, max_connect_attempts, hash policies, tunneling — are unsupported, and a configuration that sets them is refused at startup.
Weighted clusters
Traffic can be split across clusters by weight; each entry needs a name and a weight greater than zero:
weighted_clusters:
clusters:
- name: backend-v1
weight: 90
- name: backend-v2
weight: 10Ordering and interactions
The TCP proxy runs after network RBAC, rate limit and connection limit filters have admitted the connection; declaring any of them after the TCP proxy in the same chain is a startup error. When the listener has a TLS inspector, filter_chain_match.server_names routes different SNIs to different TCP proxy chains — a pattern the Route TCP at L4 guide extends in its production notes.