API changes for refactoring Envoy DNS resolution as first class exten…

…sion (envoyproxy#17272)

Adding a core.v3.TypedExtensionConfig typed_dns_resolver_config for DNS resolver
in API definition. This configuration is to support DNS resolution as a first
class Envoy extension. This API change is the first step for that task.

This configuration is to replace above dns_resolution_config.
By default envoy supports c-ares DNS or apple DNS resolvers. This extension can be used
to configure other DNS resolver types.
This configuration is optional. In case it is missing, the default behavior is in place,
which means Envoy will either use c-ares DNS library or apple DNS library based on
the compiling flag. When this configuration is in place, Envoy will use the configured
DNS resolver carried in the extension typed_config field.
In case both typed_dns_resolver_config and dns_resolution_config are configured,
typed_dns_resolver_config take precedence.

Signed-off-by: Yanjun Xiang <yanjunxiang@google.com>

api/envoy/config/bootstrap/v3/bootstrap.proto

@@ -40,7 +40,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // <config_overview_bootstrap>` for more detail.
 
 // Bootstrap :ref:`configuration overview <config_overview_bootstrap>`.
-// [#next-free-field: 31]
+// [#next-free-field: 32]
 message Bootstrap {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.bootstrap.v2.Bootstrap";
@@ -260,8 +260,25 @@ message Bootstrap {
   // This may be overridden on a per-cluster basis in cds_config, when
   // :ref:`dns_resolution_config <envoy_v3_api_field_config.cluster.v3.Cluster.dns_resolution_config>`
   // is specified.
+  // *dns_resolution_config* will be deprecated once
+  // :ref:'typed_dns_resolver_config <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.typed_dns_resolver_config>'
+  // is fully supported.
   core.v3.DnsResolutionConfig dns_resolution_config = 30;
 
+  // DNS resolver type configuration extension. This extension can be used to configure c-ares, apple,
+  // or any other DNS resolver types and the related parameters.
+  // For example, an object of :ref:`DnsResolutionConfig <envoy_v3_api_msg_config.core.v3.DnsResolutionConfig>`
+  // can be packed into this *typed_dns_resolver_config*. This configuration will replace the
+  // :ref:'dns_resolution_config <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.dns_resolution_config>'
+  // configuration eventually.
+  // TODO(yanjunxiang): Investigate the deprecation plan for *dns_resolution_config*.
+  // During the transition period when both *dns_resolution_config* and *typed_dns_resolver_config* exists,
+  // this configuration is optional.
+  // When *typed_dns_resolver_config* is in place, Envoy will use it and ignore *dns_resolution_config*.
+  // When *typed_dns_resolver_config* is missing, the default behavior is in place.
+  // [#not-implemented-hide:]
+  core.v3.TypedExtensionConfig typed_dns_resolver_config = 31;
+
   // Specifies optional bootstrap extensions to be instantiated at startup time.
   // Each item contains extension specific configuration.
   // [#extension-category: envoy.bootstrap]

api/envoy/config/cluster/v3/cluster.proto

@@ -43,7 +43,7 @@ message ClusterCollection {
 }
 
 // Configuration for a single upstream cluster.
-// [#next-free-field: 55]
+// [#next-free-field: 56]
 message Cluster {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster";
 
@@ -874,8 +874,25 @@ message Cluster {
       [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // DNS resolution configuration which includes the underlying dns resolver addresses and options.
+  // *dns_resolution_config* will be deprecated once
+  // :ref:'typed_dns_resolver_config <envoy_v3_api_field_config.cluster.v3.Cluster.typed_dns_resolver_config>'
+  // is fully supported.
   core.v3.DnsResolutionConfig dns_resolution_config = 53;
 
+  // DNS resolver type configuration extension. This extension can be used to configure c-ares, apple,
+  // or any other DNS resolver types and the related parameters.
+  // For example, an object of :ref:`DnsResolutionConfig <envoy_v3_api_msg_config.core.v3.DnsResolutionConfig>`
+  // can be packed into this *typed_dns_resolver_config*. This configuration will replace the
+  // :ref:'dns_resolution_config <envoy_v3_api_field_config.cluster.v3.Cluster.dns_resolution_config>'
+  // configuration eventually.
+  // TODO(yanjunxiang): Investigate the deprecation plan for *dns_resolution_config*.
+  // During the transition period when both *dns_resolution_config* and *typed_dns_resolver_config* exists,
+  // this configuration is optional.
+  // When *typed_dns_resolver_config* is in place, Envoy will use it and ignore *dns_resolution_config*.
+  // When *typed_dns_resolver_config* is missing, the default behavior is in place.
+  // [#not-implemented-hide:]
+  core.v3.TypedExtensionConfig typed_dns_resolver_config = 55;
+
   // Optional configuration for having cluster readiness block on warm-up. Currently, only applicable for
   // :ref:`STRICT_DNS<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`,
   // or :ref:`LOGICAL_DNS<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`.

api/envoy/extensions/common/dynamic_forward_proxy/v3/dns_cache.proto

@@ -4,6 +4,7 @@ package envoy.extensions.common.dynamic_forward_proxy.v3;
 
 import "envoy/config/cluster/v3/cluster.proto";
 import "envoy/config/core/v3/address.proto";
+import "envoy/config/core/v3/extension.proto";
 import "envoy/config/core/v3/resolver.proto";
 
 import "google/protobuf/duration.proto";
@@ -30,7 +31,7 @@ message DnsCacheCircuitBreakers {
 
 // Configuration for the dynamic forward proxy DNS cache. See the :ref:`architecture overview
 // <arch_overview_http_dynamic_forward_proxy>` for more information.
-// [#next-free-field: 12]
+// [#next-free-field: 13]
 message DnsCacheConfig {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.common.dynamic_forward_proxy.v2alpha.DnsCacheConfig";
@@ -108,8 +109,25 @@ message DnsCacheConfig {
       [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // DNS resolution configuration which includes the underlying dns resolver addresses and options.
+  // *dns_resolution_config* will be deprecated once
+  // :ref:'typed_dns_resolver_config <envoy_v3_api_field_extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig.typed_dns_resolver_config>'
+  // is fully supported.
   config.core.v3.DnsResolutionConfig dns_resolution_config = 9;
 
+  // DNS resolver type configuration extension. This extension can be used to configure c-ares, apple,
+  // or any other DNS resolver types and the related parameters.
+  // For example, an object of :ref:`DnsResolutionConfig <envoy_v3_api_msg_config.core.v3.DnsResolutionConfig>`
+  // can be packed into this *typed_dns_resolver_config*. This configuration will replace the
+  // :ref:'dns_resolution_config <envoy_v3_api_field_extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig.dns_resolution_config>'
+  // configuration eventually.
+  // TODO(yanjunxiang): Investigate the deprecation plan for *dns_resolution_config*.
+  // During the transition period when both *dns_resolution_config* and *typed_dns_resolver_config* exists,
+  // this configuration is optional.
+  // When *typed_dns_resolver_config* is in place, Envoy will use it and ignore *dns_resolution_config*.
+  // When *typed_dns_resolver_config* is missing, the default behavior is in place.
+  // [#not-implemented-hide:]
+  config.core.v3.TypedExtensionConfig typed_dns_resolver_config = 12;
+
   // Hostnames that should be preresolved into the cache upon creation. This might provide a
   // performance improvement, in the form of cache hits, for hostnames that are going to be
   // resolved during steady state and are known at config load time.