tcp_proxy: added changes to support ppv2 tlvs to be merged when downstream proxy protocol values are present by ivpr · Pull Request #42824 · envoyproxy/envoy

ivpr · 2026-01-02T06:55:18Z

Currently proxy_protocol_tlvs field in tcp_proxy ignores the TLVs specified when downstream has proxy protocol data. This change adds support to be able to merge the TLVs through an explicit enum field proxy_protocol_tlv_merge_policy.
Added support for 3 options

ADD_IF_ABSENT (default): Add configured TLVs only if no PROXY protocol state exists (e.g., no downstream TLVs). If state exists, ignore configured TLVs and use only the existing TLVs. This is the default for backward compatibility.
OVERWRITE_BY_TYPE_IF_EXISTS_OR_ADD: Overwrite existing TLVs (e.g., downstream TLVs) by type with configured TLVs. Non-conflicting TLVs from both sources are preserved. If no state exists, add all configured TLVs. Source/destination addresses from existing state are preserved..
APPEND_IF_EXISTS_OR_ADD: Append configured TLVs to existing TLVs (e.g., downstream TLVs), preserving all TLVs from both sources (PROXY protocol v2 allows duplicate types). If no state exists, add all configured TLVs. Source/destination addresses from existing state are preserved.

Commit Message: tcp_proxy: added changes to support ppv2 tlvs to be merged when downstream proxy protocol values are present
Additional Description: Currently proxy_protocol_tlvs field in tcp_proxy ignores the TLVs specified when downstream has proxy protocol data. This changes adds support to merge the TLVs through an explicit field proxy_protocol_tlv_merge_policy .
Risk Level: Low
Testing: Unit tests
Docs Changes: Added
Release Notes: Added
Platform Specific Features: N/A
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Fixes commit #PR or SHA]
[Optional Deprecated:]
[Optional API Considerations:]

…tocol values are present Signed-off-by: Prasad I V <prasad.iv@databricks.com>

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

repokitteh-read-only · 2026-01-02T06:55:28Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @markdroth
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #42824 was opened by ivpr.

see: more, trace.

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

agrawroh · 2026-01-06T16:00:31Z

+  // When set to true and the connection already contains ``PROXY`` protocol state
+  // (including TLVs) from a downstream proxy protocol listener filter, the TLVs
+  // specified in ``proxy_protocol_tlvs`` are merged with the downstream TLVs.
+  //
+  // **Precedence behavior**:
+  //
+  // - TLVs specified in ``proxy_protocol_tlvs`` take precedence over downstream TLVs
+  //   with the same type.
+  // - This allows adding or overriding specific TLV values while preserving
+  //   other downstream TLVs.
+  // - The source/destination addresses from the downstream ``PROXY`` protocol state
+  //   are preserved (not modified).
+  //
+  // When set to false (default), the ``proxy_protocol_tlvs`` are ignored if
+  // downstream ``PROXY`` protocol state already exists.
+  bool merge_proxy_protocol_tlvs = 23;


I would suggest calling it merge_with_downstream_tlvs to be more clear and also add more info to the docs.

Suggested change

// When set to true and the connection already contains ``PROXY`` protocol state

// (including TLVs) from a downstream proxy protocol listener filter, the TLVs

// specified in ``proxy_protocol_tlvs`` are merged with the downstream TLVs.

//

// **Precedence behavior**:

//

// - TLVs specified in ``proxy_protocol_tlvs`` take precedence over downstream TLVs

// with the same type.

// - This allows adding or overriding specific TLV values while preserving

// other downstream TLVs.

// - The source/destination addresses from the downstream ``PROXY`` protocol state

// are preserved (not modified).

//

// When set to false (default), the ``proxy_protocol_tlvs`` are ignored if

// downstream ``PROXY`` protocol state already exists.

bool merge_proxy_protocol_tlvs = 23;

// Controls whether TLVs specified in ``proxy_protocol_tlvs`` are merged with downstream

// ``PROXY`` protocol TLVs when downstream ``PROXY`` protocol state already exists.

//

// When set to ``true`` and the connection already contains ``PROXY`` protocol state

// (including TLVs) from a downstream proxy protocol listener filter, the TLVs

// specified in ``proxy_protocol_tlvs`` are merged with the downstream TLVs.

//

// When set to ``false`` (default), the TLVs specified in ``proxy_protocol_tlvs`` are

// ignored if downstream ``PROXY`` protocol state already exists. In this case, only

// the downstream TLVs are forwarded to the upstream.

//

// **Precedence behavior**:

//

// - TLVs specified in ``proxy_protocol_tlvs`` take precedence over downstream TLVs

// with the same type. This allows adding or overriding specific TLV values while

// preserving other downstream TLVs.

// - The source/destination addresses from the downstream ``PROXY`` protocol state

// are preserved (not modified).

// - TLVs with types that do not conflict are combined, resulting in a merged set

// of TLVs from both sources.

//

// .. note::

// This field only takes effect when downstream ``PROXY`` protocol state exists.

// If the TCP proxy filter is creating new ``PROXY`` protocol state, this field

// has no effect and the TLVs specified in ``proxy_protocol_tlvs`` are always

// included.

//

// .. note::

// To ensure the merged TLVs are allowed in the upstream ``PROXY`` protocol header,

// you must also configure passthrough TLVs on the upstream proxy protocol transport.

// See :ref:`core.v3.ProxyProtocolConfig.pass_through_tlvs <envoy_v3_api_field_config.core.v3.ProxyProtocolConfig.pass_through_tlvs>`

// for details.

bool merge_with_downstream_tlvs = 23;

Makes sense. I've made the changes to rename the field along with the doc suggestions

agrawroh · 2026-01-06T16:01:56Z

/assign @ggreenway

…ith_downstream_tlvs Signed-off-by: Prasad I V <prasad.iv@databricks.com>

ggreenway

/wait

ggreenway · 2026-01-06T19:36:32Z

+  //   you must also configure passthrough TLVs on the upstream proxy protocol transport.
+  //   See :ref:`core.v3.ProxyProtocolConfig.pass_through_tlvs <envoy_v3_api_field_config.core.v3.ProxyProtocolConfig.pass_through_tlvs>`
+  //   for details.
+  bool merge_with_downstream_tlvs = 23;


I think we need to be careful with how we handle merge vs override, when considering #42075. Would it ever make sense to add an additional TLV of the same key? Maybe we should use an enum instead of a bool here so that if different behaviors are needed in the future we can easily add it to the API.

Makes sense to add the enum config option. I've now updated the code to use enum downstream_tlv_merge_policy with 3 different options(KEEP_DOWNSTREAM_ONLY, OVERRIDE_DOWNSTREAM_TLVS_BY_TYPE, APPEND_TO_DOWNSTREAM_TLVS)

ggreenway · 2026-01-06T19:38:21Z

+
+    // Add downstream TLVs that don't conflict with tcp_proxy TLVs.
+    for (const auto& tlv : existing_data.tlv_vector_) {
+      if (!seen_types.contains(tlv.type)) {


This will introduce the bug reported in #42075 to tcp_proxy.

Fixed this now with explicit enum values

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

ivpr · 2026-01-12T05:04:45Z

@ggreenway I've addressed the review comments. Can you please have a look

tyxia · 2026-01-15T19:14:49Z

Gentle ping @ggreenway from maintainer oncall. Please merge main to resolve the conflict as well @ivpr

Thanks!

ggreenway · 2026-01-15T23:30:40Z

Apologies; I've been very busy and haven't had time to review this yet. I'm hoping to get to it early next week.

Signed-off-by: ivpr <ivijayprasad@gmail.com>

ggreenway

Apologies for the delayed review.

This looks good at a high level, but there's a little bit of clarifying/simplifying the docs and semantics to do.

/wait

ggreenway · 2026-01-21T17:18:50Z

+  // Keep only the downstream TLVs and ignore the TLVs specified in ``proxy_protocol_tlvs``
+  // if downstream PROXY protocol state already exists. Only the downstream TLVs are forwarded
+  // to the upstream. This is the default behavior for backward compatibility.


But if there is no downstream PROXY protocol, then the configured TLVs are used instead. Please document/clarify this behavior.

ggreenway · 2026-01-21T17:20:51Z

+  // - ``KEEP_DOWNSTREAM_ONLY`` (default): The TLVs specified in ``proxy_protocol_tlvs`` are
+  //   ignored if downstream ``PROXY`` protocol state already exists. Only the downstream TLVs
+  //   are forwarded to the upstream.
+  //
+  // - ``OVERRIDE_DOWNSTREAM_TLVS_BY_TYPE``: TLVs specified in ``proxy_protocol_tlvs`` override
+  //   downstream TLVs with the same type. TLVs with non-conflicting types from both sources are
+  //   preserved. The source/destination addresses from the downstream ``PROXY`` protocol state
+  //   are preserved (not modified).
+  //
+  // - ``APPEND_TO_DOWNSTREAM_TLVS``: The TLVs specified in ``proxy_protocol_tlvs`` are appended
+  //   to the downstream TLVs. This preserves all downstream TLVs and adds the tcp_proxy TLVs.
+  //   The PROXY protocol v2 specification allows multiple TLVs with the same type, so this mode
+  //   preserves all TLVs from both sources.


These docs should all be in the enum definition above; no need to duplicate here

ggreenway · 2026-01-21T17:26:17Z

+  // .. note::
+  //   This field only takes effect when downstream ``PROXY`` protocol state exists.
+  //   If the TCP proxy filter is creating new ``PROXY`` protocol state, this field
+  //   has no effect and the TLVs specified in ``proxy_protocol_tlvs`` are always
+  //   included.


This is confusing behavior.

I think it would be clearer if the default option was something like ADD_IF_ABSENT (taken from https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-enum-config-core-v3-headervalueoption-headerappendaction), and the other two options then can be said to be in effect, regardless of whether there's downstream TLVs or not (because if there aren't, both of those options just add all the configured TLVs).

I think the net effect is the same, but the mental model for how it works is simpler. WDYT?

ggreenway · 2026-01-21T17:28:25Z

        parseTLVs(config.proxy_protocol_tlvs(), context, dynamic_tlv_formatters_);
  }
+
+  downstream_tlv_merge_policy_ = config.downstream_tlv_merge_policy();


This should be set in the initializer list at the top of the constructor, because it has no validation or complicated conversion logic.

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

Signed-off-by: ivpr <ivijayprasad@gmail.com>

ggreenway

/wait

ggreenway · 2026-02-04T20:39:02Z

+* ``ADD_IF_ABSENT`` (default): Add configured TLVs only if no state exists.
+* ``OVERWRITE_BY_TYPE_IF_EXISTS_OR_ADD``: Overwrite existing TLVs by type with configured TLVs.
+  Non-conflicting TLVs from both sources are preserved.
+* ``APPEND_IF_EXISTS_OR_ADD``: Append configured TLVs to existing TLVs, preserving all
+  TLVs from both sources (allows duplicate types per PROXY protocol v2 spec).
+


I don't think you need to repeat this from the proto docs; just link to the enum type

Makes sense. done

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

Signed-off-by: ivpr <ivijayprasad@gmail.com>

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

ivpr · 2026-02-10T03:29:42Z

/retest

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

Signed-off-by: ivpr <ivijayprasad@gmail.com>

ivpr · 2026-02-11T08:18:06Z

/retest

ggreenway

LGTM. @markdroth can you review API please?

markdroth · 2026-02-13T22:12:17Z

/lgtm api

…tream proxy protocol values are present (envoyproxy#42824) Signed-off-by: nick <nickshokri@google.com>

…tream proxy protocol values are present (envoyproxy#42824)

birenroy · 2026-03-31T14:17:14Z

-          Network::ProxyProtocolFilterState::key())) {
-    // Evaluate dynamic TLVs with the connection's stream info.
+
+  auto* existing_state = filter_state->getDataMutable<Network::ProxyProtocolFilterState>(


This assumes that the ProxyProtocolFilterState was added as a mutable element. What behavior do you expect if it was added as an immutable element?

…tream proxy protocol values are present (envoyproxy#42824)

Prasad I V added 2 commits December 30, 2025 16:46

tcp_proxy: added changes to merge ppv2 tlvs when downstream proxy pro…

1b18da1

…tocol values are present Signed-off-by: Prasad I V <prasad.iv@databricks.com>

tcp_proxy: add the documentation and changelogs

e22781c

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

repokitteh-read-only Bot added the api label Jan 2, 2026

repokitteh-read-only Bot assigned markdroth Jan 2, 2026

Prasad I V added 3 commits January 5, 2026 08:51

tcp_proxy: format fixes

706e959

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

tcp_proxy: fixed spellcheck errors

2e54602

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

tcp_proxy: fixed spellcheck errors

33337f1

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

agrawroh reviewed Jan 6, 2026

View reviewed changes

repokitteh-read-only Bot assigned ggreenway Jan 6, 2026

tcp_proxy: addressed review comments and renamed the filed to merge_w…

a242b1e

…ith_downstream_tlvs Signed-off-by: Prasad I V <prasad.iv@databricks.com>

ggreenway requested changes Jan 6, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Jan 6, 2026

tcp_proxy: changed the filed option to enum based on review comments

4e20e8c

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

repokitteh-read-only Bot removed the waiting label Jan 7, 2026

Merge branch 'main' into feat-tcp-proxy-ppv2-merge

3efe858

Signed-off-by: ivpr <ivijayprasad@gmail.com>

ggreenway requested changes Jan 21, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Jan 21, 2026

made changes to address review comments

0597576

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

repokitteh-read-only Bot removed the waiting label Feb 4, 2026

Merge branch 'main' into feat-tcp-proxy-ppv2-merge

9795c05

Signed-off-by: ivpr <ivijayprasad@gmail.com>

ggreenway requested changes Feb 4, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Feb 4, 2026

tcp_proxy - made changes to address review comments

a7ef38d

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

repokitteh-read-only Bot removed the waiting label Feb 9, 2026

Merge branch 'main' into feat-tcp-proxy-ppv2-merge

35dcd74

Signed-off-by: ivpr <ivijayprasad@gmail.com>

Prasad I V added 2 commits February 9, 2026 18:28

tcp_proxy - fix tests

6b19c8a

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

tcp_proxy - fix tests

63c3b93

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

Prasad I V and others added 3 commits February 10, 2026 03:56

tcp_proxy - fix comment

1d5bf6f

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

tcp_proxy - fix formatting

670648e

Signed-off-by: Prasad I V <prasad.iv@databricks.com>

Merge branch 'main' into feat-tcp-proxy-ppv2-merge

8851d64

Signed-off-by: ivpr <ivijayprasad@gmail.com>

ggreenway approved these changes Feb 11, 2026

View reviewed changes

repokitteh-read-only Bot removed the api label Feb 13, 2026

agrawroh merged commit 4d8363f into envoyproxy:main Feb 13, 2026
28 checks passed

nickshokri pushed a commit to nickshokri/envoy that referenced this pull request Mar 17, 2026

tcp_proxy: added changes to support ppv2 tlvs to be merged when downs…

e8195a7

…tream proxy protocol values are present (envoyproxy#42824) Signed-off-by: nick <nickshokri@google.com>

nickshokri pushed a commit to nickshokri/envoy that referenced this pull request Mar 17, 2026

tcp_proxy: added changes to support ppv2 tlvs to be merged when downs…

d19768e

…tream proxy protocol values are present (envoyproxy#42824) Signed-off-by: nick <nickshokri@google.com>

fishcakez pushed a commit to fishcakez/envoy that referenced this pull request Mar 25, 2026

tcp_proxy: added changes to support ppv2 tlvs to be merged when downs…

c86a6b3

…tream proxy protocol values are present (envoyproxy#42824)

birenroy reviewed Mar 31, 2026

View reviewed changes

adisuissa mentioned this pull request Apr 7, 2026

filter-state: make ProxyProtocolFilterState mutable #44308

Merged

krinkinmu pushed a commit to grnmeira/envoy that referenced this pull request Apr 20, 2026

tcp_proxy: added changes to support ppv2 tlvs to be merged when downs…

3646ea7

…tream proxy protocol values are present (envoyproxy#42824)

Conversation

ivpr commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

repokitteh-read-only Bot commented Jan 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agrawroh commented Jan 6, 2026

Uh oh!

ggreenway left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ivpr Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ivpr commented Jan 12, 2026

Uh oh!

tyxia commented Jan 15, 2026

Uh oh!

ggreenway commented Jan 15, 2026

Uh oh!

ggreenway left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ggreenway left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ivpr commented Feb 10, 2026

Uh oh!

ivpr commented Feb 11, 2026

Uh oh!

ggreenway left a comment

Choose a reason for hiding this comment

Uh oh!

markdroth commented Feb 13, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ivpr commented Jan 2, 2026 •

edited

Loading

ivpr Jan 7, 2026 •

edited

Loading