reverse_tunnels: Add EventReporter for reverse tunnel connection reporting by aakugan · Pull Request #44342 · envoyproxy/envoy

aakugan · 2026-04-09T04:23:22Z

BUILDS ON #44327, depends on the protos introduced there.
Incremental DIFFS

Commit Message

Add EventReporter for reverse tunnel connection reporting

Additional Description:

Adds the EventReporter contrib extension, which aggregates reverse tunnel connection/disconnection events and fans them out to pluggable clients.

Key components:

ReverseTunnelReporterWithState / ReverseTunnelReporterClient: interfaces allowing multiple transport clients to share connection state from a single reporter. Clients receive incremental diffs and can request a full state snapshot so they dont have to be "stateful" other than the protocol they manage.
EventReporter: A basic implementation which does refcounting of connections by the name and stores in a map for interfacing with the clients.

Risk Level: Low, opt in extension.

Testing

Unit tests.

phlax · 2026-04-13T09:47:54Z

its not immediately clear to me why - but docs build is failing with

[97](https://github.com/envoyproxy/envoy/actions/runs/24177797097/job/70563146913#step:19:511)
/tmp/tmpfytzszml/generated/rst/api-v3/config/bootstrap/v3/bootstrap.proto.rst:396: WARNING: undefined label: 'extension_envoy.bootstrap.reverse_tunnel.reverse_tunnel_reporting_service' [ref.ref]
/tmp/tmpfytzszml/generated/rst/intro/arch_overview/security/secpos_requires_trusted_downstream_and_upstream.rst:6: WARNING: undefined label: 'extension_envoy.bootstrap.reverse_tunnel.reverse_tunnel_reporting_service' [ref.ref]
/tmp/tmpfytzszml/generated/rst/intro/arch_overview/security/secpos_requires_trusted_downstream_and_upstream.rst:6: WARNING: undefined label: 'extension_envoy.bootstrap.reverse_tunnel.reverse_tunnel_reporting_service' [ref.ref]

phlax

some initial docs review - would like to view it rendered - can help if needed to resolve the build problem

phlax · 2026-04-13T09:39:00Z

+// Configuration for the connection event reporter.
+message EventReporterConfig {
+  // Stat prefix for this reporter's metrics.
+  // Metrics will be emitted as "{stat_prefix}.events_pushed", etc.


Suggested change

// Metrics will be emitted as "{stat_prefix}.events_pushed", etc.

// Metrics will be emitted as ``{stat_prefix}.events_pushed``, etc.

phlax · 2026-04-13T09:40:17Z

+// Represents a single reverse tunnel connection with its metadata.
+message ReverseTunnel {
+  // Unique name to identify this tunnel connection.
+  // Typically formatted as "{node_id}|{cluster_id}" or similar.


Suggested change

// Typically formatted as "{node_id}|{cluster_id}" or similar.

// Typically formatted as ``{node_id}|{cluster_id}`` or similar.

phlax · 2026-04-13T09:40:48Z

+// Detailed information about a reverse tunnel connection.
+message ReverseTunnelInfo {
+  // Identity information of the tunnel initiator (downstream Envoy).
+  // Contains node_id, cluster_id, and tenant_id for proper identification.


Suggested change

// Contains node_id, cluster_id, and tenant_id for proper identification.

// Contains ``node_id``, ``cluster_id``, and ``tenant_id`` for proper identification.

aakugan · 2026-04-17T04:25:08Z

Thanks for taking a look!
I made the changes and fixed the docs build

phlax · 2026-04-17T07:21:17Z

/docs

repokitteh-read-only · 2026-04-17T07:21:22Z

Docs for this Pull Request will be rendered here:

https://storage.googleapis.com/envoy-cncf-pr/44342/docs/index.html

The docs are (re-)rendered each time the CI Envoy/Prechecks (docs) job completes.

🐱

Caused by: a #44342 (comment) was created by @phlax.

see: more, trace.

ivpr · 2026-04-17T13:48:21Z

+void EventReporter::addConnection(std::shared_ptr<ReverseTunnelEvent::Connected>&& connection) {
+  ASSERT(context_.mainThreadDispatcher().isThreadSafe());
+
+  ENVOY_LOG(info, "EventReporter: Accepted a new connection. Node: {}, Cluster: {}, Tenant: {}",


Add ReverseTunnel prefix to logs. EventReporter feels pretty generic name

We get the entire path in the log ig I will remove the prefix 😅

agrawroh · 2026-04-17T16:29:27Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a new contrib extension for reverse tunnel reporting, providing a mechanism for Envoy instances to report connection state changes to a management server. It includes the API definitions for a gRPC-based reporting service, the implementation of an EventReporter that aggregates and de-duplicates connection events, and comprehensive unit tests. Review feedback suggests adding lower-bound validation to the reporting interval to prevent potential resource exhaustion, utilizing try_emplace for more efficient map insertions, and optimizing batch event processing by using move iterators.

basundhara-c · 2026-04-19T07:06:42Z

+void EventReporter::reportConnectionEvent(absl::string_view node_id, absl::string_view cluster_id,
+                                          absl::string_view tenant_id) {
+  auto ptr = std::make_shared<ReverseTunnelEvent::Connected>(
+      ReverseTunnelEvent::Connected{std::string(node_id), std::string(cluster_id),
+                                    std::string(tenant_id), Envoy::SystemTime::clock::now()});
+
+  context_.mainThreadDispatcher().post(
+      [this, ptr = std::move(ptr)]() mutable { this->addConnection(std::move(ptr)); });
+}
+
+void EventReporter::reportDisconnectionEvent(absl::string_view node_id, absl::string_view) {
+  absl::string_view name = ReverseTunnelEvent::getName(node_id);


getName() returns the node_id right? How does this work for tenant scoped nodes?

basundhara-c · 2026-04-19T07:56:07Z

+using SharedConnections = std::vector<std::shared_ptr<Connected>>;
+using SharedDisconnections = std::vector<std::shared_ptr<Disconnected>>;
+
+struct BatchedEvents {


BatchedEvents sounds misleading because we aren't adding a 'batch', maybe we can call it Events/TunnelUpdates

basundhara-c · 2026-04-19T07:56:34Z

+}
+
+void EventReporter::reportDisconnectionEvent(absl::string_view node_id, absl::string_view) {
+  absl::string_view name = ReverseTunnelEvent::getName(node_id);


getName() returns the node_id right? How does this work for tenant scoped nodes?

Yea so I kinda expect node_id to be of the format tenant:node in the tenant isolation case.
I have added some comments above the function I will make the changes and add some integ tests to pin it some followup PRs.

basundhara-c · 2026-04-19T08:01:38Z

+  explicit Disconnected(absl::string_view n) : name(n) {}
+};
+
+using SharedConnections = std::vector<std::shared_ptr<Connected>>;


Nit: SharedConnections -> Connections/ConnectionList
SharedDisconnections -> Disconnections/DisconnectionList

basundhara-c · 2026-04-19T08:06:47Z

+
+  std::size_t size() const { return connections.size() + disconnections.size(); }
+
+  void operator+=(BatchedEvents&& events) {


This does not seem to be used anywhere?

Oh I needed it for some followup PRs thought of adding it here as it is part of the struct 😅

basundhara-c · 2026-04-19T08:17:55Z

+
+  virtual void onServerInitialized(ReverseTunnelReporterWithState* reporter) PURE;
+
+  virtual void receiveEvents(ReverseTunnelEvent::BatchedEvents events) PURE;


Why not use const ReverseTunnelEvent::BatchedEvents& events here? Does receiveEvents() mutate events?

So I wanted the copy to be explicit as the clients may have to buffer the events or something, the struct is just a bunch of shared_ptrs so copy is cheap the real risk is if some event comes which deletes the entry from the map which has the original shared_ptr.
As for the const ig there is better value in making it shared_ptr<const> I will look into that part.

basundhara-c · 2026-04-19T08:22:52Z

+  absl::string_view name = ReverseTunnelEvent::getName(connection->node_id);
+  auto [it, inserted] = connections_.try_emplace(std::move(name), std::move(connection), 1);


Using absl::string as the key in connection is fragile, let's use an owned std::string here.

Signed-off-by: aakugan <aakashganapathy2@gmail.com>

aakugan changed the title ~~Reverse tunnel reporter~~ reverse_tunnels: Add EventReporter for reverse tunnel connection reporting Apr 9, 2026

aakugan force-pushed the reverse_tunnel_reporter branch from e36b38c to 66d9466 Compare April 9, 2026 04:53

aakugan mentioned this pull request Apr 9, 2026

reverse_tunnels: add gRPC streaming client for reverse tunnel reporting #44344

Open

aakugan force-pushed the reverse_tunnel_reporter branch from 66d9466 to e9ef353 Compare April 9, 2026 07:18

aakugan mentioned this pull request Apr 9, 2026

Add integration tests and examples for reverse tunnel reporter #44345

Draft

phlax assigned agrawroh Apr 13, 2026

phlax self-assigned this Apr 13, 2026

phlax reviewed Apr 16, 2026

View reviewed changes

aakugan force-pushed the reverse_tunnel_reporter branch 2 times, most recently from 75ee2d3 to 0f8c02a Compare April 17, 2026 03:27

aakugan requested a review from phlax April 17, 2026 04:25

ivpr reviewed Apr 17, 2026

View reviewed changes

Comment thread contrib/reverse_tunnel_reporter/source/reverse_tunnel_event_types.h Outdated

ivpr reviewed Apr 17, 2026

View reviewed changes

Comment thread contrib/reverse_tunnel_reporter/source/reverse_tunnel_event_types.h Outdated

gemini-code-assist bot reviewed Apr 17, 2026

View reviewed changes

aakugan force-pushed the reverse_tunnel_reporter branch from 0f8c02a to 1f23b5c Compare April 18, 2026 03:31

basundhara-c reviewed Apr 19, 2026

View reviewed changes

basundhara-c suggested changes Apr 19, 2026

View reviewed changes

aakugan force-pushed the reverse_tunnel_reporter branch 2 times, most recently from 9b327d8 to a4a1eaa Compare April 19, 2026 20:22

Event Reporter with interface for multiple clients

af15b08

Signed-off-by: aakugan <aakashganapathy2@gmail.com>

aakugan force-pushed the reverse_tunnel_reporter branch from a4a1eaa to af15b08 Compare April 19, 2026 20:23

aakugan requested review from basundhara-c and ivpr April 20, 2026 03:34

basundhara-c approved these changes Apr 20, 2026

View reviewed changes

	// Metrics will be emitted as "{stat_prefix}.events_pushed", etc.
	// Metrics will be emitted as ``{stat_prefix}.events_pushed``, etc.

	// Typically formatted as "{node_id}\|{cluster_id}" or similar.
	// Typically formatted as ``{node_id}\|{cluster_id}`` or similar.

	// Contains node_id, cluster_id, and tenant_id for proper identification.
	// Contains ``node_id``, ``cluster_id``, and ``tenant_id`` for proper identification.


		std::size_t size() const { return connections.size() + disconnections.size(); }

		void operator+=(BatchedEvents&& events) {


		virtual void onServerInitialized(ReverseTunnelReporterWithState* reporter) PURE;

		virtual void receiveEvents(ReverseTunnelEvent::BatchedEvents events) PURE;

		absl::string_view name = ReverseTunnelEvent::getName(connection->node_id);
		auto [it, inserted] = connections_.try_emplace(std::move(name), std::move(connection), 1);

Conversation

aakugan commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Commit Message

Additional Description:

Testing

Uh oh!

phlax commented Apr 13, 2026

Uh oh!

phlax 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!

aakugan commented Apr 17, 2026

Uh oh!

phlax commented Apr 17, 2026

Uh oh!

repokitteh-read-only bot commented Apr 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

agrawroh commented Apr 17, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aakugan commented Apr 9, 2026 •

edited

Loading