API: Add extension information the Node message. (#9301)

Report extension information in the Node message.

Risk Level: Low
Testing: Unit Tests
Docs Changes: N/A
Release Notes: N/A

Fixes: #8332

Signed-off-by: Yan Avlasov <yavlasov@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ f5efe4a9bedf0ef7b03324f9bfda50118a0555c4

envoy/api/v2/core/base.proto

@@ -4,6 +4,7 @@ package envoy.api.v2.core;
 
 import "envoy/api/v2/core/http_uri.proto";
 import "envoy/type/percent.proto";
+import "envoy/type/semantic_version.proto";
 
 import "google/protobuf/any.proto";
 import "google/protobuf/struct.proto";
@@ -78,10 +79,49 @@ message Locality {
   string sub_zone = 3;
 }
 
+// BuildVersion combines SemVer version of extension with free-form build information
+// (i.e. 'alpha', 'private-build') as a set of strings.
+message BuildVersion {
+  // SemVer version of extension.
+  type.SemanticVersion version = 1;
+
+  // Free-form build information.
+  // Envoy defines several well known keys in the source/common/common/version.h file
+  google.protobuf.Struct metadata = 2;
+}
+
+// Version and identification for an Envoy extension.
+// [#next-free-field: 6]
+message Extension {
+  // This is the name of the Envoy filter as specified in the Envoy
+  // configuration, e.g. envoy.router, com.acme.widget.
+  string name = 1;
+
+  // Category of the extension.
+  // Extension category names use reverse DNS notation. For instance "envoy.filters.listener"
+  // for Envoy's built-in listener filters or "com.acme.filters.http" for HTTP filters from
+  // acme.com vendor.
+  // [#comment:TODO(yanavlasov): Link to the doc with existing envoy category names.]
+  string category = 2;
+
+  // [#not-implemented-hide:] Type descriptor of extension configuration proto.
+  // [#comment:TODO(yanavlasov): Link to the doc with existing configuration protos.]
+  // [#comment:TODO(yanavlasov): Add tests when PR #9391 lands.]
+  string type_descriptor = 3;
+
+  // The version is a property of the extension and maintained independently
+  // of other extensions and the Envoy API.
+  // This field is not set when extension did not provide version information.
+  BuildVersion version = 4;
+
+  // Indicates that the extension is present but was disabled via dynamic configuration.
+  bool disabled = 5;
+}
+
 // Identifies a specific Envoy instance. The node identifier is presented to the
 // management server, which may use this identifier to distinguish per Envoy
 // configuration for serving.
-// [#next-free-field: 6]
+// [#next-free-field: 11]
 message Node {
   // An opaque node identifier for the Envoy node. This also provides the local
   // service node name. It should be set if any of the following features are
@@ -114,7 +154,32 @@ message Node {
   // This is motivated by informing a management server during canary which
   // version of Envoy is being tested in a heterogeneous fleet. This will be set
   // by Envoy in management server RPCs.
+  // This field will be deprecated in favor of the user_agent_name and user_agent_version values.
+  // [#comment:TODO(yanavlasov): Deprecate once issue #9604 is fixed.]
   string build_version = 5;
+
+  // Free-form string that identifies the entity requesting config.
+  // E.g. "envoy" or "grpc"
+  string user_agent_name = 6;
+
+  oneof user_agent_version_type {
+    // Free-form string that identifies the version of the entity requesting config.
+    // E.g. "1.12.2" or "abcd1234", or "SpecialEnvoyBuild"
+    string user_agent_version = 7;
+
+    // Structured version of the entity requesting config.
+    BuildVersion user_agent_build_version = 8;
+  }
+
+  // List of extensions and their versions supported by the node.
+  repeated Extension extensions = 9;
+
+  // Client feature support list. These are well known features described
+  // in the Envoy API repository for a given major version of an API. Client features
+  // use reverse DNS naming scheme, for example `com.acme.feature`.
+  // See :ref:`the list of features <client_features>` that xDS client may
+  // support.
+  repeated string client_features = 10;
 }
 
 // Metadata provides additional inputs to filters based on matched listeners,

envoy/config/core/v3alpha/base.proto

@@ -4,6 +4,7 @@ package envoy.config.core.v3alpha;
 
 import "envoy/config/core/v3alpha/http_uri.proto";
 import "envoy/type/v3alpha/percent.proto";
+import "envoy/type/v3alpha/semantic_version.proto";
 
 import "google/protobuf/any.proto";
 import "google/protobuf/struct.proto";
@@ -81,10 +82,53 @@ message Locality {
   string sub_zone = 3;
 }
 
+// BuildVersion combines SemVer version of extension with free-form build information
+// (i.e. 'alpha', 'private-build') as a set of strings.
+message BuildVersion {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.BuildVersion";
+
+  // SemVer version of extension.
+  type.v3alpha.SemanticVersion version = 1;
+
+  // Free-form build information.
+  // Envoy defines several well known keys in the source/common/common/version.h file
+  google.protobuf.Struct metadata = 2;
+}
+
+// Version and identification for an Envoy extension.
+// [#next-free-field: 6]
+message Extension {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Extension";
+
+  // This is the name of the Envoy filter as specified in the Envoy
+  // configuration, e.g. envoy.router, com.acme.widget.
+  string name = 1;
+
+  // Category of the extension.
+  // Extension category names use reverse DNS notation. For instance "envoy.filters.listener"
+  // for Envoy's built-in listener filters or "com.acme.filters.http" for HTTP filters from
+  // acme.com vendor.
+  // [#comment:TODO(yanavlasov): Link to the doc with existing envoy category names.]
+  string category = 2;
+
+  // [#not-implemented-hide:] Type descriptor of extension configuration proto.
+  // [#comment:TODO(yanavlasov): Link to the doc with existing configuration protos.]
+  // [#comment:TODO(yanavlasov): Add tests when PR #9391 lands.]
+  string type_descriptor = 3;
+
+  // The version is a property of the extension and maintained independently
+  // of other extensions and the Envoy API.
+  // This field is not set when extension did not provide version information.
+  BuildVersion version = 4;
+
+  // Indicates that the extension is present but was disabled via dynamic configuration.
+  bool disabled = 5;
+}
+
 // Identifies a specific Envoy instance. The node identifier is presented to the
 // management server, which may use this identifier to distinguish per Envoy
 // configuration for serving.
-// [#next-free-field: 6]
+// [#next-free-field: 11]
 message Node {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Node";
 
@@ -119,7 +163,32 @@ message Node {
   // This is motivated by informing a management server during canary which
   // version of Envoy is being tested in a heterogeneous fleet. This will be set
   // by Envoy in management server RPCs.
+  // This field will be deprecated in favor of the user_agent_name and user_agent_version values.
+  // [#comment:TODO(yanavlasov): Deprecate once issue #9604 is fixed.]
   string build_version = 5;
+
+  // Free-form string that identifies the entity requesting config.
+  // E.g. "envoy" or "grpc"
+  string user_agent_name = 6;
+
+  oneof user_agent_version_type {
+    // Free-form string that identifies the version of the entity requesting config.
+    // E.g. "1.12.2" or "abcd1234", or "SpecialEnvoyBuild"
+    string user_agent_version = 7;
+
+    // Structured version of the entity requesting config.
+    BuildVersion user_agent_build_version = 8;
+  }
+
+  // List of extensions and their versions supported by the node.
+  repeated Extension extensions = 9;
+
+  // Client feature support list. These are well known features described
+  // in the Envoy API repository for a given major version of an API. Client features
+  // use reverse DNS naming scheme, for example `com.acme.feature`.
+  // See :ref:`the list of features <client_features>` that xDS client may
+  // support.
+  repeated string client_features = 10;
 }
 
 // Metadata provides additional inputs to filters based on matched listeners,

envoy/type/semantic_version.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package envoy.type;
+
+option java_package = "io.envoyproxy.envoy.type";
+option java_outer_classname = "SemanticVersionProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: Semantic Version]
+
+// Envoy uses SemVer (https://semver.org/). Major/minor versions indicate
+// expected behaviors and APIs, the patch version field is used only
+// for security fixes and can be generally ignored.
+message SemanticVersion {
+  uint32 major = 1;
+
+  uint32 minor = 2;
+
+  uint32 patch = 3;
+}

envoy/type/v3alpha/semantic_version.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package envoy.type.v3alpha;
+
+import "udpa/annotations/versioning.proto";
+
+option java_package = "io.envoyproxy.envoy.type.v3alpha";
+option java_outer_classname = "SemanticVersionProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: Semantic Version]
+
+// Envoy uses SemVer (https://semver.org/). Major/minor versions indicate
+// expected behaviors and APIs, the patch version field is used only
+// for security fixes and can be generally ignored.
+message SemanticVersion {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.type.SemanticVersion";
+
+  uint32 major = 1;
+
+  uint32 minor = 2;
+
+  uint32 patch = 3;
+}