config: distinct resource/transport API versions. (envoyproxy#9526)

This PR extends envoyproxy#9468 to support a distinct notion of transport and resource API version. The intuition here is that the opaque resources (and their type URLs) can be delivered via either v2 or v3 xDS, and the DiscoveryRequest etc. messages have their own versioning. Currently, the v2 and v3 transport protocols are indistinguishable modulo service endpoint. As v3 evolves, e.g. with envoyproxy#9301, differences will be introduced. At this point it will be necessary to have enhanced support in the gRPC mux and HTTP subscription modules to handle the protocol differences. This is technically a breaking v2 API change, but since the field it breaks was only added today, I think it's safe to assume it is not in use yet. Risk level: Low Testing: Integration tests added to validate service endpoint and type URL selection based on transport/resource version. Signed-off-by: Harvey Tuch <[email protected]>
hango-io · Jan 8, 2020 · df05827 · df05827
1 parent d5772a9
commit df05827
Show file tree

Hide file tree

Showing 38 changed files with 702 additions and 187 deletions.
diff --git a/api/envoy/api/v2/core/config_source.proto b/api/envoy/api/v2/core/config_source.proto
@@ -17,9 +17,24 @@ option (udpa.annotations.file_migrate).move_to_package = "envoy.config.core.v3al
 
 // [#protodoc-title: Configuration sources]
 
+// xDS API version. This is used to describe both resource and transport
+// protocol versions (in distinct configuration fields).
+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;
+
+  // Use xDS v2 API.
+  V2 = 1;
+
+  // Use xDS v3alpha API.
+  V3ALPHA = 2;
+}
+
 // API configuration source. This identifies the API type and cluster that Envoy
 // will use to fetch an xDS API.
-// [#next-free-field: 8]
+// [#next-free-field: 9]
 message ApiConfigSource {
   // APIs may be fetched via either REST or gRPC.
   enum ApiType {
@@ -45,8 +60,13 @@ message ApiConfigSource {
     DELTA_GRPC = 3;
   }
 
+  // API type (gRPC, REST, delta gRPC)
   ApiType api_type = 1 [(validate.rules).enum = {defined_only: true}];
 
+  // API version for xDS transport protocol. This describes the xDS gRPC/REST
+  // endpoint and version of [Delta]DiscoveryRequest/Response used on the wire.
+  ApiVersion transport_api_version = 8 [(validate.rules).enum = {defined_only: true}];
+
   // Cluster names should be used only with REST. If > 1
   // cluster is defined, clusters will be cycled through if any kind of failure
   // occurs.
@@ -107,18 +127,6 @@ message RateLimitSettings {
 // inotify for updates.
 // [#next-free-field: 7]
 message ConfigSource {
-  enum XdsApiVersion {
-    // use for describing explicitly that xDS API version is set automatically. In default, xDS API
-    // version is V2
-    AUTO = 0;
-
-    // use xDS v2 API
-    V2 = 1;
-
-    // use xDS v3alpha API
-    V3ALPHA = 2;
-  }
-
   oneof config_source_specifier {
     option (validate.required) = true;
 
@@ -165,6 +173,8 @@ message ConfigSource {
   // timeout applies). The default is 15s.
   google.protobuf.Duration initial_fetch_timeout = 4;
 
-  // API version for xDS endpoint
-  XdsApiVersion xds_api_version = 6;
+  // API version for xDS resources. This implies the type URLs that the client
+  // will request for resources and the resource type that the client will in
+  // turn expect to be delivered.
+  ApiVersion resource_api_version = 6 [(validate.rules).enum = {defined_only: true}];
 }
diff --git a/api/envoy/config/core/v3alpha/config_source.proto b/api/envoy/config/core/v3alpha/config_source.proto
@@ -17,9 +17,24 @@ option java_multiple_files = true;
 
 // [#protodoc-title: Configuration sources]
 
+// xDS API version. This is used to describe both resource and transport
+// protocol versions (in distinct configuration fields).
+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;
+
+  // Use xDS v2 API.
+  V2 = 1;
+
+  // Use xDS v3alpha API.
+  V3ALPHA = 2;
+}
+
 // API configuration source. This identifies the API type and cluster that Envoy
 // will use to fetch an xDS API.
-// [#next-free-field: 8]
+// [#next-free-field: 9]
 message ApiConfigSource {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.ApiConfigSource";
 
@@ -47,8 +62,13 @@ message ApiConfigSource {
     DELTA_GRPC = 3;
   }
 
+  // API type (gRPC, REST, delta gRPC)
   ApiType api_type = 1 [(validate.rules).enum = {defined_only: true}];
 
+  // API version for xDS transport protocol. This describes the xDS gRPC/REST
+  // endpoint and version of [Delta]DiscoveryRequest/Response used on the wire.
+  ApiVersion transport_api_version = 8 [(validate.rules).enum = {defined_only: true}];
+
   // Cluster names should be used only with REST. If > 1
   // cluster is defined, clusters will be cycled through if any kind of failure
   // occurs.
@@ -117,18 +137,6 @@ message RateLimitSettings {
 message ConfigSource {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.ConfigSource";
 
-  enum XdsApiVersion {
-    // use for describing explicitly that xDS API version is set automatically. In default, xDS API
-    // version is V2
-    AUTO = 0;
-
-    // use xDS v2 API
-    V2 = 1;
-
-    // use xDS v3alpha API
-    V3ALPHA = 2;
-  }
-
   oneof config_source_specifier {
     option (validate.required) = true;
 
@@ -175,6 +183,8 @@ message ConfigSource {
   // timeout applies). The default is 15s.
   google.protobuf.Duration initial_fetch_timeout = 4;
 
-  // API version for xDS endpoint
-  XdsApiVersion xds_api_version = 6;
+  // API version for xDS resources. This implies the type URLs that the client
+  // will request for resources and the resource type that the client will in
+  // turn expect to be delivered.
+  ApiVersion resource_api_version = 6 [(validate.rules).enum = {defined_only: true}];
 }
diff --git a/generated_api_shadow/envoy/api/v2/core/config_source.proto b/generated_api_shadow/envoy/api/v2/core/config_source.proto
diff --git a/generated_api_shadow/envoy/config/core/v3alpha/config_source.proto b/generated_api_shadow/envoy/config/core/v3alpha/config_source.proto
diff --git a/source/common/config/BUILD b/source/common/config/BUILD
@@ -64,6 +64,7 @@ envoy_cc_library(
     srcs = ["delta_subscription_impl.cc"],
     hdrs = ["delta_subscription_impl.h"],
     deps = [
+        ":api_version_lib",
         ":grpc_stream_lib",
         ":new_grpc_mux_lib",
         ":utility_lib",
@@ -84,6 +85,7 @@ envoy_cc_library(
     srcs = ["delta_subscription_state.cc"],
     hdrs = ["delta_subscription_state.h"],
     deps = [
+        ":api_version_lib",
         ":pausable_ack_queue_lib",
         "//include/envoy/config:subscription_interface",
         "//include/envoy/event:dispatcher_interface",
@@ -93,6 +95,7 @@ envoy_cc_library(
         "//source/common/common:token_bucket_impl_lib",
         "//source/common/grpc:common_lib",
         "//source/common/protobuf",
+        "@envoy_api//envoy/api/v2:pkg_cc_proto",
         "@envoy_api//envoy/service/discovery/v3alpha:pkg_cc_proto",
     ],
 )
@@ -136,13 +139,15 @@ envoy_cc_library(
     srcs = ["grpc_mux_impl.cc"],
     hdrs = ["grpc_mux_impl.h"],
     deps = [
+        ":api_version_lib",
         ":grpc_stream_lib",
         ":utility_lib",
         "//include/envoy/config:grpc_mux_interface",
         "//include/envoy/config:subscription_interface",
         "//include/envoy/upstream:cluster_manager_interface",
         "//source/common/common:minimal_logger_lib",
         "//source/common/protobuf",
+        "@envoy_api//envoy/api/v2:pkg_cc_proto",
         "@envoy_api//envoy/service/discovery/v3alpha:pkg_cc_proto",
     ],
 )
@@ -185,6 +190,7 @@ envoy_cc_library(
         ":watch_map_lib",
         "//include/envoy/event:dispatcher_interface",
         "//include/envoy/grpc:async_client_interface",
+        "@envoy_api//envoy/api/v2:pkg_cc_proto",
         "@envoy_api//envoy/service/discovery/v3alpha:pkg_cc_proto",
     ],
 )
@@ -197,6 +203,7 @@ envoy_cc_library(
         "http_api_protos",
     ],
     deps = [
+        ":api_version_lib",
         "//include/envoy/config:subscription_interface",
         "//include/envoy/event:dispatcher_interface",
         "//source/common/buffer:buffer_lib",
@@ -206,6 +213,7 @@ envoy_cc_library(
         "//source/common/http:rest_api_fetcher_lib",
         "//source/common/protobuf",
         "//source/common/protobuf:utility_lib",
+        "@envoy_api//envoy/api/v2:pkg_cc_proto",
         "@envoy_api//envoy/service/discovery/v3alpha:pkg_cc_proto",
     ],
 )
@@ -239,8 +247,15 @@ envoy_cc_library(
     name = "protobuf_link_hacks",
     hdrs = ["protobuf_link_hacks.h"],
     deps = [
+        "@envoy_api//envoy/api/v2:pkg_cc_proto",
+        "@envoy_api//envoy/service/cluster/v3alpha:pkg_cc_proto",
+        "@envoy_api//envoy/service/discovery/v2:pkg_cc_proto",
         "@envoy_api//envoy/service/discovery/v3alpha:pkg_cc_proto",
+        "@envoy_api//envoy/service/endpoint/v3alpha:pkg_cc_proto",
+        "@envoy_api//envoy/service/listener/v3alpha:pkg_cc_proto",
+        "@envoy_api//envoy/service/ratelimit/v2:pkg_cc_proto",
         "@envoy_api//envoy/service/ratelimit/v3alpha:pkg_cc_proto",
+        "@envoy_api//envoy/service/route/v3alpha:pkg_cc_proto",
         "@envoy_api//envoy/service/runtime/v3alpha:pkg_cc_proto",
         "@envoy_api//envoy/service/secret/v3alpha:pkg_cc_proto",
     ],
@@ -300,6 +315,7 @@ envoy_cc_library(
         "//source/common/grpc:common_lib",
         "//source/common/protobuf",
         "@envoy_api//envoy/annotations:pkg_cc_proto",
+        "@envoy_api//envoy/config/core/v3alpha:pkg_cc_proto",
     ],
 )
 

diff --git a/source/common/config/delta_subscription_state.h b/source/common/config/delta_subscription_state.h
@@ -1,5 +1,6 @@
 #pragma once
 
+#include "envoy/api/v2/discovery.pb.h"
 #include "envoy/config/subscription.h"
 #include "envoy/event/dispatcher.h"
 #include "envoy/grpc/status.h"
@@ -8,6 +9,7 @@
 
 #include "common/common/assert.h"
 #include "common/common/logger.h"
+#include "common/config/api_version.h"
 #include "common/config/pausable_ack_queue.h"
 
 namespace Envoy {

diff --git a/source/common/config/grpc_mux_impl.h b/source/common/config/grpc_mux_impl.h
@@ -3,6 +3,7 @@
 #include <queue>
 #include <unordered_map>
 
+#include "envoy/api/v2/discovery.pb.h"
 #include "envoy/common/time.h"
 #include "envoy/config/grpc_mux.h"
 #include "envoy/config/subscription.h"
@@ -13,6 +14,7 @@
 
 #include "common/common/cleanup.h"
 #include "common/common/logger.h"
+#include "common/config/api_version.h"
 #include "common/config/grpc_stream.h"
 #include "common/config/utility.h"