ip-tagging filter: add support for an optional ip-tag-header field

api/envoy/extensions/filters/http/ip_tagging/v3/ip_tagging.proto

@@ -18,6 +18,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // IP tagging :ref:`configuration overview <config_http_filters_ip_tagging>`.
 // [#extension: envoy.filters.http.ip_tagging]
 
+// [#next-free-field: 6]
 message IPTagging {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.http.ip_tagging.v2.IPTagging";
@@ -52,11 +53,48 @@ message IPTagging {
     repeated config.core.v3.CidrRange ip_list = 2;
   }
 
+  // Specify to which header the tags will be written.
+  message IpTagHeader {
+    // Describes how to apply the tags to the headers.
+    enum HeaderAction {
+      // (DEFAULT) The header specified in :ref:`ip_tag_header <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.ip_tag_header>`
+      // will be dropped, before the tags are applied. The incoming header will be "sanitized" regardless of whether the request is internal or external.
+      //
+      // Note that the header will be visible unsanitized to any filters that are invoked before the ip-tag-header filter, unless it has an *x-envoy* prefix.
+      SANITIZE = 0;
+
+      // Tags will be appended to the header specified in
+      // :ref:`ip_tag_header <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.ip_tag_header>`.
+      //
+      // Please note that this could cause the header to retain values set by the http client regardless of whether the request is internal or external.
+      APPEND_IF_EXISTS_OR_ADD = 1;
+    }
+
+    // Header to use for ip-tagging.
+    //
+    // This header will be sanitized based on the config in
+    // :ref:`action <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.IpTagHeader.action>`
+    // rather than the defaults for x-envoy prefixed headers.
+    string header = 1
+        [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
+
+    // Control if the :ref:`header <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.IpTagHeader.header>`
+    // will be sanitized, or be appended to.
+    //
+    // Default: *SANITIZE*.
+    HeaderAction action = 2;
+  }
+
   // The type of request the filter should apply to.
   RequestType request_type = 1 [(validate.rules).enum = {defined_only: true}];
 
   // [#comment:TODO(ccaraman): Extend functionality to load IP tags from file system.
   // Tracked by issue https://github.com/envoyproxy/envoy/issues/2695]
   // The set of IP tags for the filter.
   repeated IPTag ip_tags = 4 [(validate.rules).repeated = {min_items: 1}];
+
+  // Specify to which header the tags will be written.
+  //
+  // If left unspecified, the tags will be appended to the ``x-envoy-ip-tags`` header.
+  IpTagHeader ip_tag_header = 5;
 }

changelogs/current.yaml

@@ -171,5 +171,10 @@ new_features:
   change: |
     Added :ref:`attribute <arch_overview_attributes>` ``upstream.request_attempt_count``
     to get the number of times a request is attempted upstream.
+- area: ip-tagging
+  change: |
+    Adds support for specifying an alternate header
+    :ref:`ip_tag_header <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.ip_tag_header>`
+    for appending IP tags via ip-tagging filter instead of using the default header ``x-envoy-ip-tags``.
 
 deprecated:

docs/root/configuration/http/http_filters/ip_tagging_filter.rst

@@ -3,9 +3,18 @@
 IP Tagging
 ==========
 
-The HTTP IP Tagging filter sets the header *x-envoy-ip-tags* with the string tags for the trusted address from
-:ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`. If there are no tags for an address,
-the header is not set.
+The HTTP IP Tagging filter sets the *x-envoy-ip-tags* header or the provided :ref: `ip_tag_header <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.ip_tag_header>`
+with the string tags for the trusted address from :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`.
+
+If the :ref: `ip_tag_header.action <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.ip_tag_header.action>`
+is set to *SANITIZE* (the default), the header mentioned in :ref: `ip_tag_header.header <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.ip_tag_header.header>`
+will be replaced with the new tags, and clearing it if there are no tags.
+If it is instead set to *APPEND_IF_EXISTS_OR_ADD*, the header will only be appended to, retaining any existing values.
+
+Due to backward compatibility, if the :ref: `ip_tag_header <envoy_v3_api_field_extensions.filters.http.ip_tagging.v3.IPTagging.ip_tag_header>`
+is empty, the tags will be appended to the *x-envoy-ip-tags* header.
+This header is cleared at the start of the filter chain, so this is in effect the same as sanitize.
+When applying this filter multiple times within the same filter chain, this retains the old behaviour which combines the tags from each invocation.
 
 The implementation for IP Tagging provides a scalable way to compare an IP address to a large list of CIDR
 ranges efficiently. The underlying algorithm for storing tags and IP address subnets is a Level-Compressed trie

source/extensions/filters/http/ip_tagging/ip_tagging_filter.cc

@@ -20,7 +20,11 @@ IpTaggingFilterConfig::IpTaggingFilterConfig(
       stat_name_set_(scope.symbolTable().makeSet("IpTagging")),
       stats_prefix_(stat_name_set_->add(stat_prefix + "ip_tagging")),
       no_hit_(stat_name_set_->add("no_hit")), total_(stat_name_set_->add("total")),
-      unknown_tag_(stat_name_set_->add("unknown_tag.hit")) {
+      unknown_tag_(stat_name_set_->add("unknown_tag.hit")),
+      ip_tag_header_(config.has_ip_tag_header() ? config.ip_tag_header().header() : ""),
+      ip_tag_header_action_(config.has_ip_tag_header()
+                                ? config.ip_tag_header().action()
+                                : HeaderAction::IPTagging_IpTagHeader_HeaderAction_SANITIZE) {
 
   // Once loading IP tags from a file system is supported, the restriction on the size
   // of the set should be removed and observability into what tags are loaded needs
@@ -80,13 +84,8 @@ Http::FilterHeadersStatus IpTaggingFilter::decodeHeaders(Http::RequestHeaderMap&
   std::vector<std::string> tags =
       config_->trie().getData(callbacks_->streamInfo().downstreamAddressProvider().remoteAddress());
 
+  applyTags(headers, tags);
   if (!tags.empty()) {
-    const std::string tags_join = absl::StrJoin(tags, ",");
-    headers.appendEnvoyIpTags(tags_join, ",");
-
-    // We must clear the route cache or else we can't match on x-envoy-ip-tags.
-    callbacks_->downstreamCallbacks()->clearRouteCache();
-
     // For a large number(ex > 1000) of tags, stats cardinality will be an issue.
     // If there are use cases with a large set of tags, a way to opt into these stats
     // should be exposed and other observability options like logging tags need to be implemented.
@@ -112,6 +111,46 @@ void IpTaggingFilter::setDecoderFilterCallbacks(Http::StreamDecoderFilterCallbac
   callbacks_ = &callbacks;
 }
 
+void IpTaggingFilter::applyTags(Http::RequestHeaderMap& headers,
+                                const std::vector<std::string>& tags) {
+  using HeaderAction = IpTaggingFilterConfig::HeaderAction;
+
+  OptRef<const Http::LowerCaseString> header_name = config_->ipTagHeader();
+
+  if (tags.empty()) {
+    bool maybe_sanitize =
+        config_->ipTagHeaderAction() == HeaderAction::IPTagging_IpTagHeader_HeaderAction_SANITIZE;
+    if (header_name.has_value() && maybe_sanitize) {
+      if (headers.remove(header_name.value()) != 0) {
+        // We must clear the route cache in case it held a decision based on the now-removed header.
+        callbacks_->downstreamCallbacks()->clearRouteCache();
+      }
+    }
+    return;
+  }
+
+  const std::string tags_join = absl::StrJoin(tags, ",");
+  if (!header_name.has_value()) {
+    // The x-envoy-ip-tags header was cleared at the start of the filter chain.
+    // We only do append here, so that if multiple ip-tagging filters are run sequentially,
+    // the behaviour will be backwards compatible.
+    headers.appendEnvoyIpTags(tags_join, ",");
+  } else {
+    switch (config_->ipTagHeaderAction()) {
+      PANIC_ON_PROTO_ENUM_SENTINEL_VALUES;
+    case HeaderAction::IPTagging_IpTagHeader_HeaderAction_SANITIZE:
+      headers.setCopy(header_name.value(), tags_join);
+      break;
+    case HeaderAction::IPTagging_IpTagHeader_HeaderAction_APPEND_IF_EXISTS_OR_ADD:
+      headers.appendCopy(header_name.value(), tags_join);
+      break;
+    }
+  }
+
+  // We must clear the route cache so it can match on the updated value of the header.
+  callbacks_->downstreamCallbacks()->clearRouteCache();
+}
+
 } // namespace IpTagging
 } // namespace HttpFilters
 } // namespace Extensions

source/extensions/filters/http/ip_tagging/ip_tagging_filter.h

@@ -7,6 +7,7 @@
 #include <vector>
 
 #include "envoy/common/exception.h"
+#include "envoy/common/optref.h"
 #include "envoy/extensions/filters/http/ip_tagging/v3/ip_tagging.pb.h"
 #include "envoy/http/filter.h"
 #include "envoy/runtime/runtime.h"
@@ -31,6 +32,9 @@ enum class FilterRequestType { INTERNAL, EXTERNAL, BOTH };
  */
 class IpTaggingFilterConfig {
 public:
+  using HeaderAction =
+      envoy::extensions::filters::http::ip_tagging::v3::IPTagging::IpTagHeader::HeaderAction;
+
   IpTaggingFilterConfig(const envoy::extensions::filters::http::ip_tagging::v3::IPTagging& config,
                         const std::string& stat_prefix, Stats::Scope& scope,
                         Runtime::Loader& runtime);
@@ -39,6 +43,14 @@ class IpTaggingFilterConfig {
   FilterRequestType requestType() const { return request_type_; }
   const Network::LcTrie::LcTrie<std::string>& trie() const { return *trie_; }
 
+  OptRef<const Http::LowerCaseString> ipTagHeader() const {
+    if (ip_tag_header_.get().empty()) {
+      return absl::nullopt;
+    }
+    return ip_tag_header_;
+  }
+  HeaderAction ipTagHeaderAction() const { return ip_tag_header_action_; }
+
   void incHit(absl::string_view tag) {
     incCounter(stat_name_set_->getBuiltin(absl::StrCat(tag, ".hit"), unknown_tag_));
   }
@@ -71,6 +83,9 @@ class IpTaggingFilterConfig {
   const Stats::StatName total_;
   const Stats::StatName unknown_tag_;
   std::unique_ptr<Network::LcTrie::LcTrie<std::string>> trie_;
+  const Http::LowerCaseString
+      ip_tag_header_; // An empty string indicates that no ip_tag_header is set.
+  const HeaderAction ip_tag_header_action_;
 };
 
 using IpTaggingFilterConfigSharedPtr = std::shared_ptr<IpTaggingFilterConfig>;
@@ -95,6 +110,8 @@ class IpTaggingFilter : public Http::StreamDecoderFilter {
   void setDecoderFilterCallbacks(Http::StreamDecoderFilterCallbacks& callbacks) override;
 
 private:
+  void applyTags(Http::RequestHeaderMap& headers, const std::vector<std::string>& tags);
+
   IpTaggingFilterConfigSharedPtr config_;
   Http::StreamDecoderFilterCallbacks* callbacks_{};
 };

test/extensions/filters/http/ip_tagging/ip_tagging_filter_test.cc

@@ -192,6 +192,157 @@ TEST_F(IpTaggingFilterTest, AppendEntry) {
   EXPECT_EQ(Http::FilterTrailersStatus::Continue, filter_->decodeTrailers(request_trailers));
 }
 
+TEST_F(IpTaggingFilterTest, ReplaceAlternateHeaderWhenActionIsDefaulted) {
+  const std::string internal_request_yaml = R"EOF(
+request_type: internal
+ip_tag_header:
+  header: x-envoy-optional-header
+ip_tags:
+  - ip_tag_name: internal_request_with_optional_header
+    ip_list:
+      - {address_prefix: 1.2.3.4, prefix_len: 32}
+)EOF";
+
+  initializeFilter(internal_request_yaml);
+
+  Http::TestRequestHeaderMapImpl request_headers{
+      {"x-envoy-internal", "true"},
+      {"x-envoy-optional-header", "foo"}, // foo will be removed
+      {"x-envoy-optional-header", "bar"}, // bar will be removed
+      {"x-envoy-optional-header", "baz"}, // baz will be removed
+  };
+  Network::Address::InstanceConstSharedPtr remote_address =
+      Network::Utility::parseInternetAddressNoThrow("1.2.3.4");
+  filter_callbacks_.stream_info_.downstream_connection_info_provider_->setRemoteAddress(
+      remote_address);
+
+  EXPECT_EQ(Http::FilterHeadersStatus::Continue, filter_->decodeHeaders(request_headers, false));
+  EXPECT_EQ("internal_request_with_optional_header",
+            request_headers.get_("x-envoy-optional-header"));
+
+  EXPECT_EQ(Http::FilterDataStatus::Continue, filter_->decodeData(data_, false));
+  Http::TestRequestTrailerMapImpl request_trailers;
+  EXPECT_EQ(Http::FilterTrailersStatus::Continue, filter_->decodeTrailers(request_trailers));
+}
+
+TEST_F(IpTaggingFilterTest, ReplaceAlternateHeader) {
+  const std::string internal_request_yaml = R"EOF(
+request_type: internal
+ip_tag_header:
+  header: x-envoy-optional-header
+  action: SANITIZE
+ip_tags:
+  - ip_tag_name: internal_request_with_optional_header
+    ip_list:
+      - {address_prefix: 1.2.3.4, prefix_len: 32}
+)EOF";
+
+  initializeFilter(internal_request_yaml);
+
+  Http::TestRequestHeaderMapImpl request_headers{
+      {"x-envoy-internal", "true"}, {"x-envoy-optional-header", "foo"}}; // foo will be removed
+  Network::Address::InstanceConstSharedPtr remote_address =
+      Network::Utility::parseInternetAddressNoThrow("1.2.3.4");
+  filter_callbacks_.stream_info_.downstream_connection_info_provider_->setRemoteAddress(
+      remote_address);
+
+  EXPECT_EQ(Http::FilterHeadersStatus::Continue, filter_->decodeHeaders(request_headers, false));
+  EXPECT_EQ("internal_request_with_optional_header",
+            request_headers.get_("x-envoy-optional-header"));
+
+  EXPECT_EQ(Http::FilterDataStatus::Continue, filter_->decodeData(data_, false));
+  Http::TestRequestTrailerMapImpl request_trailers;
+  EXPECT_EQ(Http::FilterTrailersStatus::Continue, filter_->decodeTrailers(request_trailers));
+}
+
+TEST_F(IpTaggingFilterTest, ClearAlternateHeaderWhenUnmatchedAndSanitized) {
+  const std::string internal_request_yaml = R"EOF(
+request_type: internal
+ip_tag_header:
+  header: x-envoy-optional-header
+  action: SANITIZE
+ip_tags:
+  - ip_tag_name: internal_request_with_optional_header
+    ip_list:
+      - {address_prefix: 1.2.3.4, prefix_len: 32}
+)EOF";
+
+  initializeFilter(internal_request_yaml);
+
+  Http::TestRequestHeaderMapImpl request_headers{
+      {"x-envoy-internal", "true"}, {"x-envoy-optional-header", "foo"}}; // header will be removed
+  Network::Address::InstanceConstSharedPtr remote_address =
+      Network::Utility::parseInternetAddressNoThrow("1.2.3.5");
+  filter_callbacks_.stream_info_.downstream_connection_info_provider_->setRemoteAddress(
+      remote_address);
+
+  EXPECT_EQ(Http::FilterHeadersStatus::Continue, filter_->decodeHeaders(request_headers, false));
+  EXPECT_FALSE(request_headers.has("x-envoy-optional-header"));
+
+  EXPECT_EQ(Http::FilterDataStatus::Continue, filter_->decodeData(data_, false));
+  Http::TestRequestTrailerMapImpl request_trailers;
+  EXPECT_EQ(Http::FilterTrailersStatus::Continue, filter_->decodeTrailers(request_trailers));
+}
+
+TEST_F(IpTaggingFilterTest, AppendForwardAlternateHeader) {
+  const std::string internal_request_yaml = R"EOF(
+request_type: internal
+ip_tag_header:
+  header: x-envoy-optional-header
+  action: APPEND_IF_EXISTS_OR_ADD
+ip_tags:
+  - ip_tag_name: internal_request_with_optional_header
+    ip_list:
+      - {address_prefix: 1.2.3.4, prefix_len: 32}
+)EOF";
+
+  initializeFilter(internal_request_yaml);
+
+  Http::TestRequestHeaderMapImpl request_headers{{"x-envoy-internal", "true"},
+                                                 {"x-envoy-optional-header", "foo"}};
+  Network::Address::InstanceConstSharedPtr remote_address =
+      Network::Utility::parseInternetAddressNoThrow("1.2.3.4");
+  filter_callbacks_.stream_info_.downstream_connection_info_provider_->setRemoteAddress(
+      remote_address);
+
+  EXPECT_EQ(Http::FilterHeadersStatus::Continue, filter_->decodeHeaders(request_headers, false));
+  EXPECT_EQ("foo,internal_request_with_optional_header",
+            request_headers.get_("x-envoy-optional-header"));
+
+  EXPECT_EQ(Http::FilterDataStatus::Continue, filter_->decodeData(data_, false));
+  Http::TestRequestTrailerMapImpl request_trailers;
+  EXPECT_EQ(Http::FilterTrailersStatus::Continue, filter_->decodeTrailers(request_trailers));
+}
+
+TEST_F(IpTaggingFilterTest, RetainAlternateHeaderWhenUnmatchedAndAppendForwarded) {
+  const std::string internal_request_yaml = R"EOF(
+request_type: internal
+ip_tag_header:
+  header: x-envoy-optional-header
+  action: APPEND_IF_EXISTS_OR_ADD
+ip_tags:
+  - ip_tag_name: internal_request_with_optional_header
+    ip_list:
+      - {address_prefix: 1.2.3.4, prefix_len: 32}
+)EOF";
+
+  initializeFilter(internal_request_yaml);
+
+  Http::TestRequestHeaderMapImpl request_headers{{"x-envoy-internal", "true"},
+                                                 {"x-envoy-optional-header", "foo"}};
+  Network::Address::InstanceConstSharedPtr remote_address =
+      Network::Utility::parseInternetAddressNoThrow("1.2.3.5");
+  filter_callbacks_.stream_info_.downstream_connection_info_provider_->setRemoteAddress(
+      remote_address);
+
+  EXPECT_EQ(Http::FilterHeadersStatus::Continue, filter_->decodeHeaders(request_headers, false));
+  EXPECT_EQ("foo", request_headers.get_("x-envoy-optional-header"));
+
+  EXPECT_EQ(Http::FilterDataStatus::Continue, filter_->decodeData(data_, false));
+  Http::TestRequestTrailerMapImpl request_trailers;
+  EXPECT_EQ(Http::FilterTrailersStatus::Continue, filter_->decodeTrailers(request_trailers));
+}
+
 TEST_F(IpTaggingFilterTest, NestedPrefixes) {
   const std::string duplicate_request_yaml = R"EOF(
 request_type: both