API changes for refactoring Envoy DNS resolution as first class extension

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,24 @@ 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. When c-ares DNS is configured,
+  // :ref:'dns_resolution_config <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.dns_resolution_config>'
+  // will be enclosed in this *typed_dns_resolver_config*.
+  // This configuration is to replace the *dns_resolution_config* configuration eventually.
+  // 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. Envoy will either use
+  // c-ares DNS library or apple DNS library based on the compiling flag.
+  // [#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,24 @@ 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. When c-ares DNS is configured,
+  // :ref:'dns_resolution_config <envoy_v3_api_field_config.cluster.v3.Cluster.dns_resolution_config>'
+  // will be enclosed in this *typed_dns_resolver_config*.
+  // This configuration is to replace the *dns_resolution_config* configuration eventually.
+  // 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. Envoy will either use
+  // c-ares DNS library or apple DNS library based on the compiling flag.
+  // [#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,24 @@ 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. When c-ares DNS is configured,
+  // :ref:'dns_resolution_config <envoy_v3_api_field_extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig.dns_resolution_config>'
+  // will be enclosed in this *typed_dns_resolver_config*.
+  // This configuration is to replace the *dns_resolution_config* configuration eventually.
+  // 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. Envoy will either use
+  // c-ares DNS library or apple DNS library based on the compiling flag.
+  // [#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.