From 1adb5d54abb0e28ca409254d26fad1cf5535239b Mon Sep 17 00:00:00 2001 From: "data-plane-api(CircleCI)" Date: Wed, 8 Jan 2020 00:47:17 +0000 Subject: [PATCH] config: distinct resource/transport API versions. (#9526) This PR extends #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 #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 Mirrored from https://github.com/envoyproxy/envoy @ df0582765f8cc01a2f5901b068783f6bba9366f0 --- envoy/api/v2/core/config_source.proto | 40 ++++++++++++------- envoy/config/core/v3alpha/config_source.proto | 40 ++++++++++++------- 2 files changed, 50 insertions(+), 30 deletions(-) diff --git a/envoy/api/v2/core/config_source.proto b/envoy/api/v2/core/config_source.proto index 627df30a..5a082d8b 100644 --- a/envoy/api/v2/core/config_source.proto +++ b/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/envoy/config/core/v3alpha/config_source.proto b/envoy/config/core/v3alpha/config_source.proto index b2e4d555..718ca6cc 100644 --- a/envoy/config/core/v3alpha/config_source.proto +++ b/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}]; }