Refactoring Envoy DNS resolution as extension (#17479)

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

Mirrored from https://github.com/envoyproxy/envoy @ f4a88f969cfb58b36efcf649fc25e5c85e7e9f5c

BUILD

@@ -198,6 +198,8 @@ proto_library(
         "//envoy/extensions/matching/common_inputs/environment_variable/v3:pkg",
         "//envoy/extensions/matching/input_matchers/consistent_hashing/v3:pkg",
         "//envoy/extensions/matching/input_matchers/ip/v3:pkg",
+        "//envoy/extensions/network/dns_resolver/apple/v3:pkg",
+        "//envoy/extensions/network/dns_resolver/cares/v3:pkg",
         "//envoy/extensions/network/socket_interface/v3:pkg",
         "//envoy/extensions/quic/crypto_stream/v3:pkg",
         "//envoy/extensions/quic/proof_source/v3:pkg",

envoy/config/bootstrap/v3/bootstrap.proto

@@ -248,9 +248,6 @@ message Bootstrap {
   // when :ref:`dns_resolvers <envoy_v3_api_field_config.cluster.v3.Cluster.dns_resolvers>` and
   // :ref:`use_tcp_for_dns_lookups <envoy_v3_api_field_config.cluster.v3.Cluster.use_tcp_for_dns_lookups>` are
   // specified.
-  // Setting this value causes failure if the
-  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
-  // server startup. Apple' API only uses UDP for DNS resolution.
   // This field is deprecated in favor of *dns_resolution_config*
   // which aggregates all of the DNS resolver configuration in a single message.
   bool use_tcp_for_dns_lookups = 20
@@ -260,23 +257,22 @@ 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
+  // This field is deprecated in favor of
-  // :ref:'typed_dns_resolver_config <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.typed_dns_resolver_config>'
+  // :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
-  core.v3.DnsResolutionConfig dns_resolution_config = 30;
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // 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>`
+  // For example, an object of
-  // can be packed into this *typed_dns_resolver_config*. This configuration will replace the
+  // :ref:`CaresDnsResolverConfig <envoy_v3_api_msg_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig>`
-  // :ref:'dns_resolution_config <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.dns_resolution_config>'
+  // can be packed into this *typed_dns_resolver_config*. This configuration replaces the
-  // configuration eventually.
+  // :ref:`dns_resolution_config <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.dns_resolution_config>`
-  // TODO(yanjunxiang): Investigate the deprecation plan for *dns_resolution_config*.
+  // configuration.
   // 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 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:]
+  // [#extension-category: envoy.network.dns_resolver]
   core.v3.TypedExtensionConfig typed_dns_resolver_config = 31;
 
   // Specifies optional bootstrap extensions to be instantiated at startup time.

envoy/config/cluster/v3/cluster.proto

@@ -900,41 +900,34 @@ message Cluster {
   // :ref:`STRICT_DNS<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`
   // and :ref:`LOGICAL_DNS<envoy_v3_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`
   // this setting is ignored.
-  // Setting this value causes failure if the
-  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
-  // server startup. Apple's API only allows overriding DNS resolvers via system settings.
   // This field is deprecated in favor of *dns_resolution_config*
   // which aggregates all of the DNS resolver configuration in a single message.
   repeated core.v3.Address dns_resolvers = 18
       [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // Always use TCP queries instead of UDP queries for DNS lookups.
-  // Setting this value causes failure if the
-  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
-  // server startup. Apple' API only uses UDP for DNS resolution.
   // This field is deprecated in favor of *dns_resolution_config*
   // which aggregates all of the DNS resolver configuration in a single message.
   bool use_tcp_for_dns_lookups = 45
       [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
+  // This field is deprecated in favor of
-  // :ref:'typed_dns_resolver_config <envoy_v3_api_field_config.cluster.v3.Cluster.typed_dns_resolver_config>'
+  // :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
-  core.v3.DnsResolutionConfig dns_resolution_config = 53;
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // 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>`
+  // For example, an object of
-  // can be packed into this *typed_dns_resolver_config*. This configuration will replace the
+  // :ref:`CaresDnsResolverConfig <envoy_v3_api_msg_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig>`
-  // :ref:'dns_resolution_config <envoy_v3_api_field_config.cluster.v3.Cluster.dns_resolution_config>'
+  // can be packed into this *typed_dns_resolver_config*. This configuration replaces the
-  // configuration eventually.
+  // :ref:`dns_resolution_config <envoy_v3_api_field_config.cluster.v3.Cluster.dns_resolution_config>`
-  // TODO(yanjunxiang): Investigate the deprecation plan for *dns_resolution_config*.
+  // configuration.
   // 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 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:]
+  // [#extension-category: envoy.network.dns_resolver]
   core.v3.TypedExtensionConfig typed_dns_resolver_config = 55;
 
   // Optional configuration for having cluster readiness block on warm-up. Currently, only applicable for

envoy/config/core/v3/resolver.proto

@@ -17,9 +17,6 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
 message DnsResolverOptions {
   // Use TCP for all DNS queries instead of the default protocol UDP.
-  // Setting this value causes failure if the
-  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
-  // server startup. Apple's API only uses UDP for DNS resolution.
   bool use_tcp_for_dns_lookups = 1;
 
   // Do not use the default search domains; only query hostnames as-is or as aliases.
@@ -31,9 +28,6 @@ message DnsResolutionConfig {
   // A list of dns resolver addresses. If specified, the DNS client library will perform resolution
   // via the underlying DNS resolvers. Otherwise, the default system resolvers
   // (e.g., /etc/resolv.conf) will be used.
-  // Setting this value causes failure if the
-  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
-  // server startup. Apple's API only allows overriding DNS resolvers via system settings.
   repeated Address resolvers = 1 [(validate.rules).repeated = {min_items: 1}];
 
   // Configuration of DNS resolver option flags which control the behavior of the DNS resolver.

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

@@ -97,32 +97,28 @@ message DnsCacheConfig {
   DnsCacheCircuitBreakers dns_cache_circuit_breaker = 7;
 
   // Always use TCP queries instead of UDP queries for DNS lookups.
-  // Setting this value causes failure if the
-  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
-  // server startup. Apple' API only uses UDP for DNS resolution.
   // This field is deprecated in favor of *dns_resolution_config*
   // which aggregates all of the DNS resolver configuration in a single message.
   bool use_tcp_for_dns_lookups = 8
       [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
+  // This field is deprecated in favor of
-  // :ref:'typed_dns_resolver_config <envoy_v3_api_field_extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig.typed_dns_resolver_config>'
+  // :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
-  config.core.v3.DnsResolutionConfig dns_resolution_config = 9;
+      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
   // 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>`
+  // For example, an object of
-  // can be packed into this *typed_dns_resolver_config*. This configuration will replace the
+  // :ref:`CaresDnsResolverConfig <envoy_v3_api_msg_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig>`
-  // :ref:'dns_resolution_config <envoy_v3_api_field_extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig.dns_resolution_config>'
+  // can be packed into this *typed_dns_resolver_config*. This configuration replaces the
-  // configuration eventually.
+  // :ref:`dns_resolution_config <envoy_v3_api_field_extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig.dns_resolution_config>`
-  // TODO(yanjunxiang): Investigate the deprecation plan for *dns_resolution_config*.
+  // configuration.
   // 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 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:]
+  // [#extension-category: envoy.network.dns_resolver]
   config.core.v3.TypedExtensionConfig typed_dns_resolver_config = 12;
 
   // Hostnames that should be preresolved into the cache upon creation. This might provide a

envoy/extensions/filters/udp/dns_filter/v3/dns_filter.proto

@@ -4,6 +4,7 @@ package envoy.extensions.filters.udp.dns_filter.v3;
 
 import "envoy/config/core/v3/address.proto";
 import "envoy/config/core/v3/base.proto";
+import "envoy/config/core/v3/extension.proto";
 import "envoy/config/core/v3/resolver.proto";
 import "envoy/data/dns/v3/dns_table.proto";
 
@@ -67,8 +68,23 @@ message DnsFilterConfig {
         [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
     // DNS resolution configuration which includes the underlying dns resolver addresses and options.
+    // This field will be deprecated in favor of
+    // :ref:`typed_dns_resolver_config <envoy_v3_api_field_extensions.filters.udp.dns_filter.v3.DnsFilterConfig.ClientContextConfig.typed_dns_resolver_config>`.
     config.core.v3.DnsResolutionConfig dns_resolution_config = 5;
 
+    // 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:`CaresDnsResolverConfig <envoy_v3_api_msg_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig>`
+    // can be packed into this *typed_dns_resolver_config*. This configuration replaces the
+    // :ref:`dns_resolution_config <envoy_v3_api_field_extensions.filters.udp.dns_filter.v3.DnsFilterConfig.ClientContextConfig.dns_resolution_config>`
+    // configuration.
+    // During the transition period when both *dns_resolution_config* and *typed_dns_resolver_config* exists,
+    // 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.
+    // [#extension-category: envoy.network.dns_resolver]
+    config.core.v3.TypedExtensionConfig typed_dns_resolver_config = 4;
+
     // Controls how many outstanding external lookup contexts the filter tracks.
     // The context structure allows the filter to respond to every query even if the external
     // resolution times out or is otherwise unsuccessful

envoy/extensions/network/dns_resolver/apple/v3/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)

envoy/extensions/network/dns_resolver/apple/v3/apple_dns_resolver.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package envoy.extensions.network.dns_resolver.apple.v3;
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.network.dns_resolver.apple.v3";
+option java_outer_classname = "AppleDnsResolverProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: apple DNS resolver]
+// [#extension: envoy.network.dns_resolver.apple]
+
+// Configuration for apple DNS resolver.
+message AppleDnsResolverConfig {
+}

envoy/extensions/network/dns_resolver/cares/v3/BUILD

@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/config/core/v3:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package envoy.extensions.network.dns_resolver.cares.v3;
+
+import "envoy/config/core/v3/address.proto";
+import "envoy/config/core/v3/resolver.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.network.dns_resolver.cares.v3";
+option java_outer_classname = "CaresDnsResolverProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: c-ares DNS resolver]
+// [#extension: envoy.network.dns_resolver.cares]
+
+// Configuration for c-ares DNS resolver.
+message CaresDnsResolverConfig {
+  // A list of dns resolver addresses. If specified, the DNS client library will perform resolution
+  // via the underlying DNS resolvers. Otherwise, the default system resolvers
+  // (e.g., /etc/resolv.conf) will be used.
+  repeated config.core.v3.Address resolvers = 1 [(validate.rules).repeated = {min_items: 1}];
+
+  // Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
+  config.core.v3.DnsResolverOptions dns_resolver_options = 2;
+}

versioning/BUILD

@@ -150,6 +150,8 @@ proto_library(
         "//envoy/extensions/matching/common_inputs/environment_variable/v3:pkg",
         "//envoy/extensions/matching/input_matchers/consistent_hashing/v3:pkg",
         "//envoy/extensions/matching/input_matchers/ip/v3:pkg",
+        "//envoy/extensions/network/dns_resolver/apple/v3:pkg",
+        "//envoy/extensions/network/dns_resolver/cares/v3:pkg",
         "//envoy/extensions/network/socket_interface/v3:pkg",
         "//envoy/extensions/quic/crypto_stream/v3:pkg",
         "//envoy/extensions/quic/proof_source/v3:pkg",