udpa: context parameter encoding.

api/envoy/config/bootstrap/v3/bootstrap.proto

@@ -40,7 +40,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // <config_overview_bootstrap>` for more detail.
 
 // Bootstrap :ref:`configuration overview <config_overview_bootstrap>`.
-// [#next-free-field: 26]
+// [#next-free-field: 27]
 message Bootstrap {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.bootstrap.v2.Bootstrap";
@@ -108,6 +108,40 @@ message Bootstrap {
   // identification purposes (e.g. in generated headers).
   core.v3.Node node = 1;
 
+  // A list of :ref:`Node <envoy_v3_api_msg_config.core.v3.Node>` field names
+  // that will be included in the context parameters of the effective
+  // *UdpaResourceLocator* that is sent in a discovery request when resource
+  // locators are used for LDS/CDS. Any non-string field will have its JSON
+  // encoding set as the context parameter value, with the exception of
+  // metadata, which will be flattened (see example below). The supported field
+  // names are:
+  // - "cluster"
+  // - "id"
+  // - "locality.region"
+  // - "locality.sub_zone"
+  // - "locality.zone"
+  // - "metadata"
+  // - "user_agent_build_version.metadata"
+  // - "user_agent_build_version.version"
+  // - "user_agent_name"
+  // - "user_agent_version"
+  //
+  // The node context parameters act as a base layer dictionary for the context
+  // parameters (i.e. more specific resource specific context parameters will
+  // override). Field names will be prefixed with “udpa.node.” when included in
+  // context parameters.
+  //
+  // For example, if node_context_params is ``["user_agent_name", "metadata"]``,
+  // the implied context parameters might be::
+  //
+  //   node.user_agent_name: "envoy"
+  //   node.metadata.foo: "{\"bar\": \"baz\"}"
+  //   node.metadata.some: "42"
+  //   node.metadata.thing: "\"thing\""
+  //
+  // [#not-implemented-hide:]
+  repeated string node_context_params = 26;
+
   // Statically specified resources.
   StaticResources static_resources = 2;
 

source/common/config/BUILD

@@ -325,6 +325,18 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "udpa_context_params_lib",
+    srcs = ["udpa_context_params.cc"],
+    hdrs = ["udpa_context_params.h"],
+    deps = [
+        "//source/common/common:macros",
+        "//source/common/protobuf:utility_lib",
+        "@com_github_cncf_udpa//udpa/core/v1:pkg_cc_proto",
+        "@envoy_api//envoy/config/core/v3:pkg_cc_proto",
+    ],
+)
+
 envoy_cc_library(
     name = "udpa_resource_lib",
     srcs = ["udpa_resource.cc"],

source/common/config/udpa_context_params.cc

@@ -0,0 +1,91 @@
+#include "common/config/udpa_context_params.h"
+
+#include "common/common/macros.h"
+#include "common/protobuf/utility.h"
+
+namespace Envoy {
+namespace Config {
+
+namespace {
+
+using RenderContextParamCb = std::function<std::string(const envoy::config::core::v3::Node& node)>;
+using NodeContextRenderers = absl::flat_hash_map<std::string, RenderContextParamCb>;
+
+RenderContextParamCb directStringFieldRenderer(const std::string& field) {
+  return [field](const envoy::config::core::v3::Node& node) -> std::string {
+    return MessageUtil::getStringField(node, field);
+  };
+}
+
+RenderContextParamCb localityStringFieldRenderer(const std::string& field) {
+  return [field](const envoy::config::core::v3::Node& node) -> std::string {
+    return MessageUtil::getStringField(node.locality(), field);
+  };
+}
+
+std::string buildSemanticVersionRenderer(const envoy::config::core::v3::Node& node) {
+  const auto& semver = node.user_agent_build_version().version();
+  return fmt::format("{}.{}.{}", semver.major_number(), semver.minor_number(), semver.patch());
+}
+
+const NodeContextRenderers& nodeParamCbs() {
+  CONSTRUCT_ON_FIRST_USE(NodeContextRenderers, {"id", directStringFieldRenderer("id")},
+                         {"cluster", directStringFieldRenderer("cluster")},
+                         {"user_agent_name", directStringFieldRenderer("user_agent_name")},
+                         {"user_agent_version", directStringFieldRenderer("user_agent_version")},
+                         {"locality.region", localityStringFieldRenderer("region")},
+                         {"locality.zone", localityStringFieldRenderer("zone")},
+                         {"locality.sub_zone", localityStringFieldRenderer("sub_zone")},
+                         {"user_agent_build_version.version", buildSemanticVersionRenderer});
+}
+
+void mergeMetadataJson(Protobuf::Map<std::string, std::string>& params,
+                       const ProtobufWkt::Struct& metadata, const std::string& prefix) {
+  for (const auto& it : metadata.fields()) {
+    params[prefix + it.first] = MessageUtil::getJsonStringFromMessage(it.second);
+  }
+}
+
+} // namespace
+
+udpa::core::v1::ContextParams UdpaContextParams::encode(
+    const envoy::config::core::v3::Node& node, const std::vector<std::string>& node_context_params,
+    const udpa::core::v1::ContextParams& resource_context_params,
+    const std::vector<std::string>& client_features,
+    const absl::flat_hash_map<std::string, std::string>& extra_resource_params) {
+  udpa::core::v1::ContextParams context_params;
+  auto& mutable_params = *context_params.mutable_params();
+  // 1. Establish base layer of per-node context parameters.
+  for (const std::string& ncp : node_context_params) {
+    // First attempt field accessors known ahead of time, if that fails we consider the cases of
+    // metadata, either directly in the Node message, or nested in the user_agent_build_version.
+    if (nodeParamCbs().count(ncp) > 0) {
+      mutable_params["udpa.node." + ncp] = nodeParamCbs().at(ncp)(node);
+    } else if (ncp == "metadata") {
+      mergeMetadataJson(mutable_params, node.metadata(), "udpa.node.metadata.");
+    } else if (ncp == "user_agent_build_version.metadata") {
+      mergeMetadataJson(mutable_params, node.user_agent_build_version().metadata(),
+                        "udpa.node.user_agent_build_version.metadata.");
+    }
+  }
+
+  // 2. Overlay with context parameters from resource name.
+  for (const auto& it : resource_context_params.params()) {
+    mutable_params[it.first] = it.second;
+  }
+
+  // 3. Overlay with per-resource type context parameters.
+  for (const std::string& cf : client_features) {
+    mutable_params["udpa.client_feature." + cf] = "true";
+  }
+
+  // 4. Overlay with per-resource well-known attributes.
+  for (const auto& it : extra_resource_params) {
+    mutable_params["udpa.resource." + it.first] = it.second;
+  }
+
+  return context_params;
+}
+
+} // namespace Config
+} // namespace Envoy

source/common/config/udpa_context_params.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include "envoy/config/core/v3/base.pb.h"
+
+#include "absl/container/flat_hash_map.h"
+#include "udpa/core/v1/context_params.pb.h"
+
+namespace Envoy {
+namespace Config {
+
+// Utilities for working with context parameters.
+class UdpaContextParams {
+public:
+  /**
+   * Encode context parameters by following the xDS transport precedence algorithm and applying
+   * parameter prefixes.
+   * @param node reference to the local Node information.
+   * @param node_context_params a list of node fields to include in context parameters.
+   * @param resource_context_params context parameters from resource locator.
+   * @param client_features client feature capabilities.
+   * @param extra_resource_param per-resource type well known attributes.
+   * @return udpa::core::v1::ContextParams encoded context parameters.
+   */
+  static udpa::core::v1::ContextParams
+  encode(const envoy::config::core::v3::Node& node,
+         const std::vector<std::string>& node_context_params,
+         const udpa::core::v1::ContextParams& resource_context_params,
+         const std::vector<std::string>& client_features,
+         const absl::flat_hash_map<std::string, std::string>& extra_resource_params);
+};
+
+} // namespace Config
+} // namespace Envoy

source/common/config/udpa_resource.h

@@ -1,3 +1,5 @@
+#pragma once
+
 #include "envoy/common/exception.h"
 
 #include "absl/strings/string_view.h"

test/common/config/BUILD

@@ -440,15 +440,32 @@ envoy_cc_test(
     ],
 )
 
+envoy_cc_test(
+    name = "udpa_context_params_test",
+    srcs = ["udpa_context_params_test.cc"],
+    deps = [
+        ":udpa_test_utility_lib",
+        "//source/common/config:udpa_context_params_lib",
+        "//test/test_common:logging_lib",
+        "//test/test_common:utility_lib",
+    ],
+)
+
 envoy_cc_test(
     name = "udpa_resource_test",
     srcs = ["udpa_resource_test.cc"],
     deps = [
+        ":udpa_test_utility_lib",
         "//source/common/config:udpa_resource_lib",
         "//test/test_common:utility_lib",
     ],
 )
 
+envoy_cc_test_library(
+    name = "udpa_test_utility_lib",
+    hdrs = ["udpa_test_utility.h"],
+)
+
 envoy_proto_library(
     name = "version_converter_proto",
     srcs = ["version_converter.proto"],