api: deprecated version annotation introduction (#15564)

Adding a deprecated API version annotation to deprecated fields and enum values in proto files.
This is part of the work on adding minor/patch versioning work.

Risk Level: Low (adding annotation to existing protos).
Testing: Added and modified tests for the tooling (in tools/testdata).

Signed-off-by: Adi Suissa-Peleg <[email protected]>

Mirrored from https://github.com/envoyproxy/envoy @ 5a8bfa20dc3c85ecb61826d122696ecaa75dffa0

envoy/annotations/deprecation.proto

@@ -5,18 +5,29 @@ package envoy.annotations;
 import "google/protobuf/descriptor.proto";
 
 // [#protodoc-title: Deprecation]
-// Allows tagging proto fields as fatal by default. One Envoy release after
-// deprecation, deprecated fields will be disallowed by default, a state which
-// is reversible with :ref:`runtime overrides <config_runtime_deprecation>`.
+// Adds annotations for deprecated fields and enums to allow tagging proto
+// fields as fatal by default and the minor version on which the field was
+// deprecated. One Envoy release after deprecation, deprecated fields will be
+// disallowed by default, a state which is reversible with
+// :ref:`runtime overrides <config_runtime_deprecation>`.
 
 // Magic number in this file derived from top 28bit of SHA256 digest of
-// "envoy.annotation.disallowed_by_default"
+// "envoy.annotation.disallowed_by_default" and "envoy.annotation.deprecated_at_minor_version"
 extend google.protobuf.FieldOptions {
   bool disallowed_by_default = 189503207;
+
+  // The API major and minor version on which the field was deprecated
+  // (e.g., "3.5" for major version 3 and minor version 5).
+  string deprecated_at_minor_version = 157299826;
 }
 
 // Magic number in this file derived from top 28bit of SHA256 digest of
-// "envoy.annotation.disallowed_by_default_enum"
+// "envoy.annotation.disallowed_by_default_enum" and
+// "envoy.annotation.deprecated_at_minor_version_eum"
 extend google.protobuf.EnumValueOptions {
   bool disallowed_by_default_enum = 70100853;
+
+  // The API major and minor version on which the enum value was deprecated
+  // (e.g., "3.5" for major version 3 and minor version 5).
+  string deprecated_at_minor_version_enum = 181198657;
 }

envoy/config/bootstrap/v3/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/config/accesslog/v3:pkg",
         "//envoy/config/bootstrap/v2:pkg",
         "//envoy/config/cluster/v3:pkg",

envoy/config/bootstrap/v3/bootstrap.proto

@@ -21,6 +21,7 @@ import "google/protobuf/duration.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/migrate.proto";
 import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
@@ -187,7 +188,8 @@ message Bootstrap {
   // Optional watchdog configuration.
   // This is for a single watchdog configuration for the entire system.
   // Deprecated in favor of *watchdogs* which has finer granularity.
-  Watchdog watchdog = 8 [deprecated = true];
+  Watchdog watchdog = 8
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Optional watchdogs configuration.
   // This is used for specifying different watchdogs for the different subsystems.
@@ -199,7 +201,8 @@ message Bootstrap {
   // .. attention::
   //  This field has been deprecated in favor of :ref:`HttpConnectionManager.Tracing.provider
   //  <envoy_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.provider>`.
-  trace.v3.Tracing tracing = 9 [deprecated = true];
+  trace.v3.Tracing tracing = 9
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Configuration for the runtime configuration provider. If not
   // specified, a “null” provider will be used which will result in all defaults
@@ -308,7 +311,8 @@ message Admin {
   // access log is desired specify ‘/dev/null’. This is only required if
   // :ref:`address <envoy_api_field_config.bootstrap.v3.Admin.address>` is set.
   // Deprecated in favor of *access_log* which offers more options.
-  string access_log_path = 1 [deprecated = true];
+  string access_log_path = 1
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // The cpu profiler output path for the administration server. If no profile
   // path is specified, the default is ‘/var/log/envoy/envoy.prof’.

envoy/config/cluster/v3/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/api/v2:pkg",
         "//envoy/api/v2/cluster:pkg",
         "//envoy/config/core/v3:pkg",

envoy/config/cluster/v3/cluster.proto

@@ -21,6 +21,7 @@ import "google/protobuf/wrappers.proto";
 
 import "xds/core/v3/collection_entry.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/migrate.proto";
 import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
@@ -758,7 +759,8 @@ message Cluster {
   // See ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
-  core.v3.UpstreamHttpProtocolOptions upstream_http_protocol_options = 46 [deprecated = true];
+  core.v3.UpstreamHttpProtocolOptions upstream_http_protocol_options = 46
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Additional options when handling HTTP requests upstream. These options will be applicable to
   // both HTTP1 and HTTP2 requests.
@@ -770,7 +772,8 @@ message Cluster {
   // See ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
-  core.v3.HttpProtocolOptions common_http_protocol_options = 29 [deprecated = true];
+  core.v3.HttpProtocolOptions common_http_protocol_options = 29
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Additional options when handling HTTP1 requests.
   // This has been deprecated in favor of http_protocol_options fields in the in the
@@ -780,7 +783,8 @@ message Cluster {
   // See ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
-  core.v3.Http1ProtocolOptions http_protocol_options = 13 [deprecated = true];
+  core.v3.Http1ProtocolOptions http_protocol_options = 13
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Even if default HTTP2 protocol options are desired, this field must be
   // set so that Envoy will assume that the upstream supports HTTP/2 when
@@ -795,8 +799,11 @@ message Cluster {
   // See ref:`upstream_http_protocol_options
   // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   // for example usage.
-  core.v3.Http2ProtocolOptions http2_protocol_options = 14
-      [deprecated = true, (udpa.annotations.security).configure_for_untrusted_upstream = true];
+  core.v3.Http2ProtocolOptions http2_protocol_options = 14 [
+    deprecated = true,
+    (udpa.annotations.security).configure_for_untrusted_upstream = true,
+    (envoy.annotations.deprecated_at_minor_version) = "3.0"
+  ];
 
   // The extension_protocol_options field is used to provide extension-specific protocol options
   // for upstream connections. The key should match the extension filter name, such as
@@ -932,7 +939,8 @@ message Cluster {
   // <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   // http_protocol_options can be set via the cluster's
   // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
-  ClusterProtocolSelection protocol_selection = 26 [deprecated = true];
+  ClusterProtocolSelection protocol_selection = 26
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Optional options for upstream connections.
   UpstreamConnectionOptions upstream_connection_options = 30;
@@ -993,7 +1001,8 @@ message Cluster {
   //
   //   This field has been deprecated in favor of `timeout_budgets`, part of
   //   :ref:`track_cluster_stats <envoy_api_field_config.cluster.v3.Cluster.track_cluster_stats>`.
-  bool track_timeout_budgets = 47 [deprecated = true];
+  bool track_timeout_budgets = 47
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Optional customization and configuration of upstream connection pool, and upstream type.
   //

envoy/config/core/v3/base.proto

@@ -14,6 +14,7 @@ import "google/protobuf/wrappers.proto";
 
 import "xds/core/v3/context_params.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
@@ -204,7 +205,8 @@ message Node {
   // for filtering :ref:`listeners <config_listeners>` to be returned. For example,
   // if there is a listener bound to port 80, the list can optionally contain the
   // SocketAddress `(0.0.0.0,80)`. The field is optional and just a hint.
-  repeated Address listening_addresses = 11 [deprecated = true];
+  repeated Address listening_addresses = 11
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 }
 
 // Metadata provides additional inputs to filters based on matched listeners,

envoy/config/core/v3/config_source.proto

@@ -27,10 +27,10 @@ enum ApiVersion {
   // When not specified, we assume v2, to ease migration to Envoy's stable API
   // versioning. If a client does not support v2 (e.g. due to deprecation), this
   // is an invalid value.
-  AUTO = 0 [deprecated = true];
+  AUTO = 0 [deprecated = true, (envoy.annotations.deprecated_at_minor_version_enum) = "3.0"];
 
   // Use xDS v2 API.
-  V2 = 1 [deprecated = true];
+  V2 = 1 [deprecated = true, (envoy.annotations.deprecated_at_minor_version_enum) = "3.0"];
 
   // Use xDS v3 API.
   V3 = 2;

envoy/config/core/v3/protocol.proto

@@ -8,6 +8,7 @@ import "envoy/type/v3/percent.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -361,7 +362,8 @@ message Http2ProtocolOptions {
   // <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.override_stream_error_on_invalid_http_message>`
   //
   // See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details.
-  bool stream_error_on_invalid_http_messaging = 12 [deprecated = true];
+  bool stream_error_on_invalid_http_messaging = 12
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Allows invalid HTTP messaging and headers. When this option is disabled (default), then
   // the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However,

envoy/config/core/v3/substitution_format_string.proto

@@ -7,6 +7,7 @@ import "envoy/config/core/v3/extension.proto";
 
 import "google/protobuf/struct.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "validate/validate.proto";
 
@@ -41,7 +42,8 @@ message SubstitutionFormatString {
     //   upstream connect error:503:path=/foo
     //
     // Deprecated in favor of :ref:`text_format_source <envoy_v3_api_field_config.core.v3.SubstitutionFormatString.text_format_source>`. To migrate text format strings, use the :ref:`inline_string <envoy_v3_api_field_config.core.v3.DataSource.inline_string>` field.
-    string text_format = 1 [deprecated = true];
+    string text_format = 1
+        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
     // Specify a format with command operators to form a JSON string.
     // Its details is described in :ref:`format dictionary<config_access_log_format_dictionaries>`.

envoy/config/core/v4alpha/config_source.proto

@@ -31,7 +31,8 @@ enum ApiVersion {
   // When not specified, we assume v2, to ease migration to Envoy's stable API
   // versioning. If a client does not support v2 (e.g. due to deprecation), this
   // is an invalid value.
-  DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE = 0 [deprecated = true];
+  DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE = 0
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version_enum) = "3.0"];
 
   // Use xDS v3 API.
   V3 = 2;

envoy/config/listener/v3/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/api/v2:pkg",
         "//envoy/api/v2/listener:pkg",
         "//envoy/config/accesslog/v3:pkg",

envoy/config/listener/v3/listener.proto

@@ -15,6 +15,7 @@ import "google/protobuf/wrappers.proto";
 
 import "xds/core/v3/collection_entry.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/security.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
@@ -133,7 +134,8 @@ message Listener {
   core.v3.Metadata metadata = 6;
 
   // [#not-implemented-hide:]
-  DeprecatedV1 deprecated_v1 = 7 [deprecated = true];
+  DeprecatedV1 deprecated_v1 = 7
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // The type of draining to perform at a listener-wide level.
   DrainType drain_type = 8;

envoy/config/listener/v3/listener_components.proto

@@ -11,6 +11,7 @@ import "google/protobuf/any.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -230,7 +231,8 @@ message FilterChain {
   // This field is deprecated. Add a
   // :ref:`PROXY protocol listener filter <config_listener_filters_proxy_protocol>`
   // explicitly instead.
-  google.protobuf.BoolValue use_proxy_proto = 4 [deprecated = true];
+  google.protobuf.BoolValue use_proxy_proto = 4
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // [#not-implemented-hide:] filter chain metadata.
   core.v3.Metadata metadata = 5;

envoy/config/rbac/v3/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/config/core/v3:pkg",
         "//envoy/config/rbac/v2:pkg",
         "//envoy/config/route/v3:pkg",

envoy/config/rbac/v3/rbac.proto

@@ -11,6 +11,7 @@ import "envoy/type/matcher/v3/string.proto";
 import "google/api/expr/v1alpha1/checked.proto";
 import "google/api/expr/v1alpha1/syntax.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
@@ -259,7 +260,8 @@ message Principal {
 
     // A CIDR block that describes the downstream IP.
     // This address will honor proxy protocol, but will not honor XFF.
-    core.v3.CidrRange source_ip = 5 [deprecated = true];
+    core.v3.CidrRange source_ip = 5
+        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
     // A CIDR block that describes the downstream remote/origin address.
     // Note: This is always the physical peer even if the

envoy/config/route/v3/route_components.proto

@@ -1022,7 +1022,8 @@ message RouteAction {
   // request.
   //
   // This field is deprecated. Please use :ref:`vh_rate_limits <envoy_v3_api_field_extensions.filters.http.ratelimit.v3.RateLimitPerRoute.vh_rate_limits>`
-  google.protobuf.BoolValue include_vh_rate_limits = 14 [deprecated = true];
+  google.protobuf.BoolValue include_vh_rate_limits = 14
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Specifies a list of hash policies to use for ring hash load balancing. Each
   // hash policy is evaluated individually and the combined result is used to
@@ -1061,7 +1062,8 @@ message RouteAction {
   //    :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`,
   //    :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the
   //    :ref:`retry overview <arch_overview_http_routing_retry>`.
-  google.protobuf.Duration max_grpc_timeout = 23 [deprecated = true];
+  google.protobuf.Duration max_grpc_timeout = 23
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Deprecated by :ref:`grpc_timeout_header_offset <envoy_api_field_config.route.v3.RouteAction.MaxStreamDuration.grpc_timeout_header_offset>`.
   // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by subtracting
@@ -1071,7 +1073,8 @@ message RouteAction {
   // The offset will only be applied if the provided grpc_timeout is greater than the offset. This
   // ensures that the offset will only ever decrease the timeout and never set it to 0 (meaning
   // infinity).
-  google.protobuf.Duration grpc_timeout_offset = 28 [deprecated = true];
+  google.protobuf.Duration grpc_timeout_offset = 28
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   repeated UpgradeConfig upgrade_configs = 25;
 
@@ -1081,7 +1084,8 @@ message RouteAction {
   // <envoy_api_field_config.route.v3.InternalRedirectPolicy.redirect_response_codes>`.
   InternalRedirectPolicy internal_redirect_policy = 34;
 
-  InternalRedirectAction internal_redirect_action = 26 [deprecated = true];
+  InternalRedirectAction internal_redirect_action = 26
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // An internal redirect is handled, iff the number of previous internal redirects that a
   // downstream request has encountered is lower than this value, and
@@ -1097,7 +1101,8 @@ message RouteAction {
   // will pass the redirect back to downstream.
   //
   // If not specified, at most one redirect will be followed.
-  google.protobuf.UInt32Value max_internal_redirects = 31 [deprecated = true];
+  google.protobuf.UInt32Value max_internal_redirects = 31
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Indicates that the route has a hedge policy. Note that if this is set,
   // it'll take precedence over the virtual host level hedge policy entirely
@@ -1751,8 +1756,11 @@ message RateLimit {
       //
       // .. attention::
       //   This field has been deprecated in favor of the :ref:`metadata <envoy_api_field_config.route.v3.RateLimit.Action.metadata>` field
-      DynamicMetaData dynamic_metadata = 7
-          [deprecated = true, (envoy.annotations.disallowed_by_default) = true];
+      DynamicMetaData dynamic_metadata = 7 [
+        deprecated = true,
+        (envoy.annotations.deprecated_at_minor_version) = "3.0",
+        (envoy.annotations.disallowed_by_default) = true
+      ];
 
       // Rate limit on metadata.
       MetaData metadata = 8;

envoy/config/route/v4alpha/BUILD

@@ -6,7 +6,6 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
-        "//envoy/annotations:pkg",
         "//envoy/config/core/v4alpha:pkg",
         "//envoy/config/route/v3:pkg",
         "//envoy/type/matcher/v4alpha:pkg",

envoy/config/route/v4alpha/route_components.proto

@@ -16,7 +16,6 @@ import "google/protobuf/any.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
-import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";

envoy/config/tap/v3/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/config/common/matcher/v3:pkg",
         "//envoy/config/core/v3:pkg",
         "//envoy/config/route/v3:pkg",