dns: renumber dns filter fields for wire compatibility (#17943)

api/envoy/extensions/filters/udp/dns_filter/v3alpha/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/annotations:pkg",
         "//envoy/config/core/v3:pkg",
         "//envoy/data/dns/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",

api/envoy/extensions/filters/udp/dns_filter/v3alpha/dns_filter.proto

@@ -2,12 +2,14 @@ syntax = "proto3";
 
 package envoy.extensions.filters.udp.dns_filter.v3alpha;
 
+import "envoy/config/core/v3/address.proto";
 import "envoy/config/core/v3/base.proto";
 import "envoy/config/core/v3/resolver.proto";
 import "envoy/data/dns/v3/dns_table.proto";
 
 import "google/protobuf/duration.proto";
 
+import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "validate/validate.proto";
 
@@ -44,15 +46,29 @@ message DnsFilterConfig {
   // in a client context. This message will contain the timeouts, retry,
   // and forwarding configuration for Envoy to make DNS requests to other
   // resolvers
+  //
+  // [#next-free-field: 6]
   message ClientContextConfig {
     // Sets the maximum time we will wait for the upstream query to complete
     // We allow 5s for the upstream resolution to complete, so the minimum
     // value here is 1. Note that the total latency for a failed query is the
     // number of retries multiplied by the resolver_timeout.
     google.protobuf.Duration resolver_timeout = 1 [(validate.rules).duration = {gte {seconds: 1}}];
 
+    // This field was used for `dns_resolution_config` in Envoy 1.19.0 and
+    // 1.19.1.
+    // Control planes that need to set this field for Envoy 1.19.0 and
+    // 1.19.1 clients should fork the protobufs and change the field type
+    // to `DnsResolutionConfig`.
+    // Control planes that need to simultaneously support Envoy 1.18.x and
+    // Envoy 1.19.x should avoid Envoy 1.19.0 and 1.19.1.
+    //
+    // [#not-implemented-hide:]
+    repeated config.core.v3.Address upstream_resolvers = 2
+        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
+
     // DNS resolution configuration which includes the underlying dns resolver addresses and options.
-    config.core.v3.DnsResolutionConfig dns_resolution_config = 2;
+    config.core.v3.DnsResolutionConfig dns_resolution_config = 5;
 
     // 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

docs/root/version_history/current.rst

@@ -3,6 +3,17 @@
 
 Incompatible Behavior Changes
 -----------------------------
+*Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required*
+
+* dns_filter: :ref:`dns_filter <envoy_v3_api_msg_extensions.filters.udp.dns_filter.v3alpha.DnsFilterConfig>`
+  protobuf fields have been renumbered to restore compatibility with Envoy
+  1.18, breaking compatibility with Envoy 1.19.0 and 1.19.1. The new field
+  numbering allows control planes supporting Envoy 1.18 to gracefully upgrade to
+  :ref:`dns_resolution_config <envoy_v3_api_field_extensions.filters.udp.dns_filter.v3alpha.DnsFilterConfig.ClientContextConfig.dns_resolution_config>`,
+  provided they skip over Envoy 1.19.0 and 1.19.1.
+  Control planes upgrading from Envoy 1.19.0 and 1.19.1 will need to
+  vendor the corresponding protobuf definitions to ensure that the
+  renumbered fields have the types expected by those releases.
 
 Minor Behavior Changes
 ----------------------