Skip to content

reverse_tunnel: propagate initiator worker and connection ids#46232

Open
roll-no-21 wants to merge 1 commit into
envoyproxy:mainfrom
roll-no-21:reverse-tunnel-worker-connection-id
Open

reverse_tunnel: propagate initiator worker and connection ids#46232
roll-no-21 wants to merge 1 commit into
envoyproxy:mainfrom
roll-no-21:reverse-tunnel-worker-connection-id

Conversation

@roll-no-21

Copy link
Copy Markdown
Contributor

Commit Message: reverse_tunnel: propagate initiator worker and connection ids

Additional Description:
The reverse-tunnel handshake carried no way to distinguish tunnels opened by different worker threads or connections of the same initiator. This adds two optional handshake headers and surfaces them on both ends so operators can tell tunnels apart and correlate a tunnel across the initiator and acceptor.

Downstream (initiator). RCConnectionWrapper::connect() now sends x-envoy-reverse-tunnel-worker-id (the initiator worker dispatcher name, e.g. worker_2) and x-envoy-reverse-tunnel-connection-id (the initiator's per-connection id). Both are exposed in the initiator access log via the new worker_id and connection_id fields of the envoy.reverse_tunnel.initiator dynamic metadata namespace. The connection id is captured at socket handoff so it is still available for the connection_closed event after the connection object is gone.

Upstream (acceptor). The envoy.filters.network.reverse_tunnel filter parses the two headers (best-effort; empty for older initiators) and threads them through addConnectionSocket into ReverseTunnelLifecycleInfo. They are emitted on every reverse-tunnel lifecycle event as the initiator_worker_id and initiator_connection_id fields of the envoy.reverse_tunnel.lifecycle dynamic metadata namespace, and as the envoy.reverse_tunnel.initiator_worker_id / envoy.reverse_tunnel.initiator_connection_id connection filter-state keys. These are distinct from the acceptor's own worker field.

Both directions are additive and backward compatible: an initiator that does not send the headers yields empty values, and no configuration changes are required.

Risk Level: Low
Testing: Unit tests added/updated across the downstream initiator, the acceptor socket manager, the lifecycle filter, and the network filter parse path. Full //test/extensions/bootstrap/reverse_tunnel/..., //test/extensions/filters/network/reverse_tunnel/..., and //test/extensions/clusters/reverse_connection/... suites pass.
Docs Changes: Updated docs/root/configuration/other_features/reverse_tunnel.rst (lifecycle metadata fields + filter-state keys, initiator access-log field table) and the initiator example config.
Release Notes: Added a new_features changelog entry.

This pull request and its description were written by Isaac.

The reverse-tunnel handshake carried no way to tell apart tunnels opened
by different workers or connections of the same initiator. Add two
optional handshake headers, x-envoy-reverse-tunnel-worker-id (the
initiator worker dispatcher name, e.g. worker_2) and
x-envoy-reverse-tunnel-connection-id (the initiator's per-connection id),
and surface them on both ends.

Downstream (initiator): the identifiers are sent in the handshake and
exposed in the initiator access log via the new worker_id and
connection_id fields of the envoy.reverse_tunnel.initiator dynamic
metadata namespace. The connection id is captured at socket handoff so it
is available for the connection_closed event after the connection object
is gone.

Upstream (acceptor): the network filter parses the two headers (best
effort; empty for older initiators) and threads them into the
ReverseTunnelLifecycleInfo. They are surfaced on every lifecycle event as
the initiator_worker_id and initiator_connection_id fields of the
envoy.reverse_tunnel.lifecycle dynamic metadata namespace and as the
envoy.reverse_tunnel.initiator_worker_id /
envoy.reverse_tunnel.initiator_connection_id connection filter-state keys,
distinct from the acceptor's own worker field.

Signed-off-by: Krishna Sharma <k.sharma@databricks.com>

Co-authored-by: Isaac
Signed-off-by: Krishna Sharma <krishnagpl2001@gmail.com>
@repokitteh-read-only

Copy link
Copy Markdown

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #46232 was opened by roll-no-21.

see: more, trace.

@roll-no-21
roll-no-21 marked this pull request as ready for review July 17, 2026 14:33
@roll-no-21

Copy link
Copy Markdown
Contributor Author

@basundhara-c @ivpr

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant