diff --git a/envoy/api/v2/core/base.proto b/envoy/api/v2/core/base.proto index 565f4c53..f7bb6d7f 100644 --- a/envoy/api/v2/core/base.proto +++ b/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 ` that xDS client may + // support. + repeated string client_features = 10; } // Metadata provides additional inputs to filters based on matched listeners, diff --git a/envoy/config/core/v3alpha/base.proto b/envoy/config/core/v3alpha/base.proto index 869e61ea..2a57ff54 100644 --- a/envoy/config/core/v3alpha/base.proto +++ b/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 ` that xDS client may + // support. + repeated string client_features = 10; } // Metadata provides additional inputs to filters based on matched listeners, diff --git a/envoy/type/semantic_version.proto b/envoy/type/semantic_version.proto new file mode 100644 index 00000000..5ad0335c --- /dev/null +++ b/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; +} diff --git a/envoy/type/v3alpha/semantic_version.proto b/envoy/type/v3alpha/semantic_version.proto new file mode 100644 index 00000000..2bf52615 --- /dev/null +++ b/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; +}