upstream_proxy_protocol: Introduce custom TLV support

api/envoy/config/core/v3/proxy_protocol.proto

@@ -32,6 +32,15 @@ message ProxyProtocolPassThroughTLVs {
   repeated uint32 tlv_type = 2 [(validate.rules).repeated = {items {uint32 {lt: 256}}}];
 }
 
+// Represents a single Type-Length-Value (TLV) entry.
+message TlvEntry {
+  // The type of the TLV. Must be a uint8 (0-255) as per the Proxy Protocol v2 specification.
+  uint32 type = 1 [(validate.rules).uint32 = {lt: 256}];
+
+  // The value of the TLV. Must be at least one byte long.
+  bytes value = 2 [(validate.rules).bytes = {min_len: 1}];
+}
+
 message ProxyProtocolConfig {
   enum Version {
     // PROXY protocol version 1. Human readable format.
@@ -47,4 +56,40 @@ message ProxyProtocolConfig {
   // This config controls which TLVs can be passed to upstream if it is Proxy Protocol
   // V2 header. If there is no setting for this field, no TLVs will be passed through.
   ProxyProtocolPassThroughTLVs pass_through_tlvs = 2;
+
+  // This config allows additional TLVs to be included in the upstream PROXY protocol
+  // V2 header. Unlike ``pass_through_tlvs``, which passes TLVs from the downstream request,
+  // ``added_tlvs`` provides an extension mechanism for defining new TLVs that are included
+  // with the upstream request. These TLVs may not be present in the downstream request and
+  // can be defined at either the transport socket level or the host level to provide more
+  // granular control over the TLVs that are included in the upstream request.
+  //
+  // Host-level TLVs are specified in the ``metadata.typed_filter_metadata`` field under the
+  // ``envoy.transport_sockets.proxy_protocol`` namespace.
+  //
+  // .. code-block:: yaml
+  //
+  //  clusters:
+  //    - name: cluster_0
+  //      load_assignment:
+  //        endpoints:
+  //          - lbEndpoints:
+  //              - metadata:
+  //                  typed_filter_metadata:
+  //                    envoy.transport_sockets.proxy_protocol:
+  //                      "@type": type.googleapis.com/envoy.config.core.v3.ProxyProtocolConfig
+  //                      added_tlvs:
+  //                        - type: 0xD7
+  //                          value: b3Zy
+  //                        - type: 0xD8
+  //                          value: bmV3
+  //
+  // **Precedence behavior**:
+  //
+  // - When a TLV is defined at both the host level and the transport socket level, the value
+  //   from the host level configuration takes precedence. This allows users to define default TLVs
+  //   at the transport socket level and override them at the host level.
+  // - Any TLV defined in the ``pass_through_tlvs`` field will be overridden by either the host-level
+  //   or transport socket-level TLV.
+  repeated TlvEntry added_tlvs = 3;
 }

changelogs/current.yaml

@@ -84,6 +84,13 @@ new_features:
   change: |
     Adding support for a new body mode: FULL_DUPLEX_STREAMED in the ext_proc filter
     :ref:`processing_mode <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExternalProcessor.processing_mode>`.
+- area: proxy_protocol
+  change: |
+    Added support for injecting custom Type-Length-Value (TLV) entries into the Proxy Protocol v2 header for upstream
+    transport sockets. Custom TLVs can be defined both in the endpoint host's typed metadata under the
+    ``envoy.transport_sockets.proxy_protocol`` namespace and at the configuration level via the ``ProxyProtocolConfig``'s
+    ``added_tlvs`` field. Host-level TLV definitions override config-level entries when the same type is specified, allowing
+    default TLVs to be set globally, while enabling further per-endpoint customizations.
 - area: http
   change: |
     Added :ref:`max_metadata_size <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.max_metadata_size>` to make

source/common/config/well_known_names.h

@@ -34,6 +34,9 @@ class MetadataFilterValues {
   const std::string ENVOY_LB = "envoy.lb";
   // Filter namespace for built-in transport socket match in cluster.
   const std::string ENVOY_TRANSPORT_SOCKET_MATCH = "envoy.transport_socket_match";
+  // Filter namespace for storing custom upstream PP TLVs in metadata.
+  const std::string ENVOY_TRANSPORT_SOCKETS_PROXY_PROTOCOL =
+      "envoy.transport_sockets.proxy_protocol";
   // Proxy address configuration namespace for HTTP/1.1 proxy transport sockets.
   const std::string ENVOY_HTTP11_PROXY_TRANSPORT_SOCKET_ADDR =
       "envoy.http11_proxy_transport_socket.proxy_address";

source/extensions/common/proxy_protocol/proxy_protocol_header.cc

@@ -111,19 +111,47 @@ void generateV2Header(const Network::Address::Ip& source_address,
 }
 
 bool generateV2Header(const Network::ProxyProtocolData& proxy_proto_data, Buffer::Instance& out,
-                      bool pass_all_tlvs, const absl::flat_hash_set<uint8_t>& pass_through_tlvs) {
-  uint64_t extension_length = 0;
-  for (auto&& tlv : proxy_proto_data.tlv_vector_) {
+                      bool pass_all_tlvs, const absl::flat_hash_set<uint8_t>& pass_through_tlvs,
+                      const std::vector<Envoy::Network::ProxyProtocolTLV>& custom_tlvs) {
+  std::vector<Envoy::Network::ProxyProtocolTLV> combined_tlv_vector;
+  std::vector<Envoy::Network::ProxyProtocolTLV> final_tlvs;
+  combined_tlv_vector.reserve(custom_tlvs.size() + proxy_proto_data.tlv_vector_.size());
+
+  absl::flat_hash_set<uint8_t> seen_types;
+  for (const auto& tlv : custom_tlvs) {
+    ASSERT(!seen_types.contains(tlv.type));
+    combined_tlv_vector.emplace_back(tlv);
+    seen_types.insert(tlv.type);
+  }
+
+  // Combine TLVs from the proxy_proto_data with the custom TLVs.
+  for (const auto& tlv : proxy_proto_data.tlv_vector_) {
     if (!pass_all_tlvs && !pass_through_tlvs.contains(tlv.type)) {
+      // Skip any TLV that is not in the set of passthrough TLVs.
       continue;
     }
-    extension_length += PROXY_PROTO_V2_TLV_TYPE_LENGTH_LEN + tlv.value.size();
-    if (extension_length > std::numeric_limits<uint16_t>::max()) {
-      ENVOY_LOG_MISC(
-          warn, "Generating Proxy Protocol V2 header: TLVs exceed length limit {}, already got {}",
-          std::numeric_limits<uint16_t>::max(), extension_length);
-      return false;
+    if (seen_types.contains(tlv.type)) {
+      // Skip any duplicate TLVs from being added to the combined TLV vector.
+      ENVOY_LOG_EVERY_POW_2_MISC(info, "Skipping duplicate TLV type {}", tlv.type);
+      continue;
     }
+    seen_types.insert(tlv.type);
+    combined_tlv_vector.emplace_back(tlv);
+  }
+
+  // Filter out TLVs that would exceed the 65535 limit.
+  uint64_t extension_length = 0;
+  bool skipped_tlvs = false;
+  for (auto&& tlv : combined_tlv_vector) {
+    uint64_t new_size = extension_length + PROXY_PROTO_V2_TLV_TYPE_LENGTH_LEN + tlv.value.size();
+    if (new_size > std::numeric_limits<uint16_t>::max()) {
+      ENVOY_LOG_MISC(warn, "Skipping TLV type {} because adding it would exceed the 65535 limit.",
+                     tlv.type);
+      skipped_tlvs = true;
+      continue;
+    }
+    extension_length = new_size;
+    final_tlvs.push_back(tlv);
   }
 
   ASSERT(extension_length <= std::numeric_limits<uint16_t>::max());
@@ -141,17 +169,16 @@ bool generateV2Header(const Network::ProxyProtocolData& proxy_proto_data, Buffer
   generateV2Header(src.addressAsString(), dst.addressAsString(), src.port(), dst.port(),
                    src.version(), static_cast<uint16_t>(extension_length), out);
 
-  // Generate the TLV vector.
-  for (auto&& tlv : proxy_proto_data.tlv_vector_) {
-    if (!pass_all_tlvs && !pass_through_tlvs.contains(tlv.type)) {
-      continue;
-    }
+  for (auto&& tlv : combined_tlv_vector) {
     out.add(&tlv.type, 1);
     uint16_t size = htons(static_cast<uint16_t>(tlv.value.size()));
     out.add(&size, sizeof(uint16_t));
     out.add(&tlv.value.front(), tlv.value.size());
   }
-  return true;
+
+  // return true if no TLVs were skipped, otherwise false to increment the counter
+  // in the upstream proxy protocol transport socket stats.
+  return !skipped_tlvs;
 }
 
 void generateProxyProtoHeader(const envoy::config::core::v3::ProxyProtocolConfig& config,

source/extensions/common/proxy_protocol/proxy_protocol_header.h

@@ -70,7 +70,8 @@ void generateV2LocalHeader(Buffer::Instance& out);
 
 // Generates the v2 PROXY protocol header including the TLV vector into the specified buffer.
 bool generateV2Header(const Network::ProxyProtocolData& proxy_proto_data, Buffer::Instance& out,
-                      bool pass_all_tlvs, const absl::flat_hash_set<uint8_t>& pass_through_tlvs);
+                      bool pass_all_tlvs, const absl::flat_hash_set<uint8_t>& pass_through_tlvs,
+                      const std::vector<Envoy::Network::ProxyProtocolTLV>& custom_tlvs);
 
 } // namespace ProxyProtocol
 } // namespace Common

source/extensions/filters/listener/proxy_protocol/proxy_protocol.cc

@@ -612,6 +612,10 @@ ReadOrParseState Filter::readExtensions(Network::ListenerFilterBuffer& buffer) {
   auto raw_slice = buffer.rawSlice();
   // waiting for more data if there is no enough data for extensions.
   if (raw_slice.len_ < (proxy_protocol_header_.value().wholeHeaderLength())) {
+    ENVOY_LOG(
+        trace,
+        "waiting for more data to read extensions. Buffer length: {}, extension header length {}",
+        raw_slice.len_, proxy_protocol_header_.value().wholeHeaderLength());
     return ReadOrParseState::TryAgainLater;
   }
 

source/extensions/transport_sockets/proxy_protocol/BUILD

@@ -34,9 +34,11 @@ envoy_cc_library(
         "//source/common/common:hex_lib",
         "//source/common/common:scalar_to_byte_vector_lib",
         "//source/common/common:utility_lib",
+        "//source/common/config:well_known_names",
         "//source/common/network:address_lib",
         "//source/extensions/common/proxy_protocol:proxy_protocol_header_lib",
         "//source/extensions/transport_sockets/common:passthrough_lib",
         "@envoy_api//envoy/config/core/v3:pkg_cc_proto",
+        "@envoy_api//envoy/extensions/transport_sockets/proxy_protocol/v3:pkg_cc_proto",
     ],
 )

source/extensions/transport_sockets/proxy_protocol/proxy_protocol.cc

@@ -3,13 +3,17 @@
 #include <sstream>
 
 #include "envoy/config/core/v3/proxy_protocol.pb.h"
+#include "envoy/extensions/transport_sockets/proxy_protocol/v3/upstream_proxy_protocol.pb.h"
+#include "envoy/extensions/transport_sockets/proxy_protocol/v3/upstream_proxy_protocol.pb.validate.h"
 #include "envoy/network/transport_socket.h"
 
 #include "source/common/buffer/buffer_impl.h"
 #include "source/common/common/hex.h"
 #include "source/common/common/scalar_to_byte_vector.h"
 #include "source/common/common/utility.h"
+#include "source/common/config/well_known_names.h"
 #include "source/common/network/address_impl.h"
+#include "source/common/protobuf/utility.h"
 #include "source/extensions/common/proxy_protocol/proxy_protocol_header.h"
 
 using envoy::config::core::v3::ProxyProtocolConfig;
@@ -36,6 +40,11 @@ UpstreamProxyProtocolSocket::UpstreamProxyProtocolSocket(
       pass_through_tlvs_.insert(0xFF & tlv_type);
     }
   }
+  for (const auto& entry : config.added_tlvs()) {
+    added_tlvs_.push_back(Network::ProxyProtocolTLV{
+        static_cast<uint8_t>(entry.type()),
+        std::vector<unsigned char>(entry.value().begin(), entry.value().end())});
+  }
 }
 
 void UpstreamProxyProtocolSocket::setTransportSocketCallbacks(
@@ -91,9 +100,11 @@ void UpstreamProxyProtocolSocket::generateHeaderV2() {
   if (!options_ || !options_->proxyProtocolOptions().has_value()) {
     Common::ProxyProtocol::generateV2LocalHeader(header_buffer_);
   } else {
+    std::vector<Envoy::Network::ProxyProtocolTLV> custom_tlvs = buildCustomTLVs();
+
     const auto options = options_->proxyProtocolOptions().value();
     if (!Common::ProxyProtocol::generateV2Header(options, header_buffer_, pass_all_tlvs_,
-                                                 pass_through_tlvs_)) {
+                                                 pass_through_tlvs_, custom_tlvs)) {
       // There is a warn log in generateV2Header method.
       stats_.v2_tlvs_exceed_max_length_.inc();
     }
@@ -165,6 +176,56 @@ void UpstreamProxyProtocolSocketFactory::hashKey(
   }
 }
 
+std::vector<Envoy::Network::ProxyProtocolTLV> UpstreamProxyProtocolSocket::buildCustomTLVs() const {
+  std::vector<Envoy::Network::ProxyProtocolTLV> custom_tlvs;
+  absl::flat_hash_set<uint8_t> processed_tlv_types;
+
+  // Attempt to parse host-level TLVs first.
+  const auto& upstream_info = callbacks_->connection().streamInfo().upstreamInfo();
+  if (upstream_info && upstream_info->upstreamHost()) {
+    auto metadata = upstream_info->upstreamHost()->metadata();
+    if (metadata) {
+      const auto filter_it = metadata->typed_filter_metadata().find(
+          Envoy::Config::MetadataFilters::get().ENVOY_TRANSPORT_SOCKETS_PROXY_PROTOCOL);
+      if (filter_it != metadata->typed_filter_metadata().end()) {
+        ProxyProtocolConfig host_tlv_metadata;
+        auto status = MessageUtil::unpackTo(filter_it->second, host_tlv_metadata);
+        if (!status.ok()) {
+          ENVOY_LOG(warn,
+                    "Failed to unpack custom TLVs from upstream host metadata for host {}. "
+                    "Error: {}. Will still use config-level TLVs.",
+                    upstream_info->upstreamHost()->address()->asString(), status.message());
+        } else {
+          // Insert host-level TLVs
+          for (const auto& entry : host_tlv_metadata.added_tlvs()) {
+            if (processed_tlv_types.contains(entry.type())) {
+              ENVOY_LOG_EVERY_POW_2_MISC(info, "Skipping duplicate TLV type from host metadata {}",
+                                         entry.type());
+              continue;
+            }
+            custom_tlvs.push_back(Network::ProxyProtocolTLV{
+                static_cast<uint8_t>(entry.type()),
+                std::vector<unsigned char>(entry.value().begin(), entry.value().end())});
+            processed_tlv_types.insert(entry.type());
+          }
+        }
+      }
+    }
+  }
+
+  // If host-level parse failed or was not present, we still read config-level TLVs
+  for (const auto& tlv : added_tlvs_) {
+    if (processed_tlv_types.contains(tlv.type)) {
+      ENVOY_LOG_EVERY_POW_2_MISC(info, "Skipping duplicate TLV type from added_tlvs {}", tlv.type);
+      continue;
+    }
+    custom_tlvs.push_back(tlv);
+    processed_tlv_types.insert(tlv.type);
+  }
+
+  return custom_tlvs;
+}
+
 } // namespace ProxyProtocol
 } // namespace TransportSockets
 } // namespace Extensions

source/extensions/transport_sockets/proxy_protocol/proxy_protocol.h

@@ -43,6 +43,10 @@ class UpstreamProxyProtocolSocket : public TransportSockets::PassthroughSocket,
   void generateHeader();
   void generateHeaderV1();
   void generateHeaderV2();
+  // Combine host-level and config-level TLVs, with fallback if metadata fails to unpack.
+  // Host-level has precedence over config-level TLVs.
+  // If we fail to parse host metadata, we still read config TLVs.
+  std::vector<Envoy::Network::ProxyProtocolTLV> buildCustomTLVs() const;
   Network::IoResult writeHeader();
 
   Network::TransportSocketOptionsConstSharedPtr options_;
@@ -52,6 +56,7 @@ class UpstreamProxyProtocolSocket : public TransportSockets::PassthroughSocket,
   const UpstreamProxyProtocolStats& stats_;
   const bool pass_all_tlvs_;
   absl::flat_hash_set<uint8_t> pass_through_tlvs_{};
+  std::vector<Envoy::Network::ProxyProtocolTLV> added_tlvs_{};
 };
 
 class UpstreamProxyProtocolSocketFactory : public PassthroughFactory {