Reverse Tunnel Network Filter (proto)

This extension has the qualified name envoy.filters.network.reverse_tunnel

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

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

envoy.filters.network

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.filters.network.reverse_tunnel.v3.ReverseTunnel

Reverse Tunnel Network Filter configuration overview.

extensions.filters.network.reverse_tunnel.v3.Validation

[extensions.filters.network.reverse_tunnel.v3.Validation proto]

Validation configuration for reverse tunnel identifiers. Validates the node ID, cluster ID, and tenant ID extracted from reverse tunnel handshake headers against expected values specified using format strings.

{
  "node_id_format": ...,
  "cluster_id_format": ...,
  "tenant_id_format": ...,
  "emit_dynamic_metadata": ...,
  "dynamic_metadata_namespace": ...
}

node_id_format

(string) Format string to extract the expected node identifier for validation. The formatted value is compared against the x-envoy-reverse-tunnel-node-id header from the incoming handshake request. If they do not match, the connection is rejected with HTTP 403 Forbidden.

Supports Envoy’s command operators:

%DYNAMIC_METADATA(namespace:key)%: Extract expected value from dynamic metadata.
%FILTER_STATE(key)%: Extract expected value from filter state.
%DOWNSTREAM_REMOTE_ADDRESS%: Use downstream connection IP address.
Plain strings: Use a static expected value.

If empty, node ID validation is skipped.

Example using dynamic metadata allowlist:

node_id_format: "%DYNAMIC_METADATA(envoy.reverse_tunnel.allowlist:expected_node_id)%"

cluster_id_format

(string) Format string to extract the expected cluster identifier for validation. The formatted value is compared against the x-envoy-reverse-tunnel-cluster-id header from the incoming handshake request. If they do not match, the connection is rejected with HTTP 403 Forbidden.

Supports the same command operators as node_id_format.

If empty, cluster ID validation is skipped.

Example using filter state:

cluster_id_format: "%FILTER_STATE(expected_cluster_id)%"

tenant_id_format

(string) Format string to extract the expected tenant identifier for validation. The formatted value is compared against the x-envoy-reverse-tunnel-tenant-id header from the incoming handshake request. If they do not match, the connection is rejected with HTTP 403 Forbidden.

Supports the same command operators as node_id_format.

If empty, tenant ID validation is skipped.

emit_dynamic_metadata

(bool) Whether to emit validation results as dynamic metadata. When enabled, the filter emits metadata under the namespace specified by dynamic_metadata_namespace containing:

node_id: The actual node ID from the handshake request.
cluster_id: The actual cluster ID from the handshake request.
tenant_id: The actual tenant ID from the handshake request.
validation_result: Either allowed or denied.

This metadata can be used by subsequent filters or for access logging. Defaults to false.

dynamic_metadata_namespace: (string) Namespace for emitted dynamic metadata when emit_dynamic_metadata is true. If not specified, defaults to envoy.filters.network.reverse_tunnel.

extensions.filters.network.reverse_tunnel.v3.ReverseTunnel

[extensions.filters.network.reverse_tunnel.v3.ReverseTunnel proto]

Configuration for the reverse tunnel network filter. This filter handles reverse tunnel connection acceptance and rejection by processing HTTP requests where required identification values are provided via HTTP headers.

{
  "ping_interval": {...},
  "auto_close_connections": ...,
  "request_path": ...,
  "request_method": ...,
  "validation": {...},
  "required_cluster_name": ...
}

ping_interval: (Duration) Ping interval for health checks on established reverse tunnel connections. If not specified, defaults to 2 seconds.

auto_close_connections

(bool) Whether to automatically close connections after processing reverse tunnel requests.

When set to true, connections are closed after acceptance or rejection.
When set to false, connections remain open for potential reuse.

Defaults to false.

request_path: (string, REQUIRED) HTTP path to match for reverse tunnel requests. If not specified, defaults to /reverse_connections/request.

request_method: (config.core.v3.RequestMethod) HTTP method to match for reverse tunnel requests. If not specified (METHOD_UNSPECIFIED), this defaults to GET.

validation: (extensions.filters.network.reverse_tunnel.v3.Validation) Optional validation configuration for node, cluster, and tenant identifiers. If specified, the filter validates the x-envoy-reverse-tunnel-node-id, x-envoy-reverse-tunnel-cluster-id, and x-envoy-reverse-tunnel-tenant-id headers against expected values extracted using format strings. Requests that fail validation are rejected with HTTP 403 Forbidden.

required_cluster_name: (string) Required cluster name for validating reverse tunnel connection initiations. When set, the filter validates that the upstream cluster of the initiator envoy matches this name via x-envoy-reverse-tunnel-upstream-cluster-name header. Connections with mismatched or missing cluster names are rejected with HTTP 400 Bad Request. When empty, no cluster name validation is performed.