Add does_not_exist_at_server field to per-resource error state (#14900)

Signed-off-by: Lidi Zheng <lidiz@google.com>

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

envoy/admin/v3/config_dump.proto

@@ -17,6 +17,31 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: ConfigDump]
 
+// Resource status from the view of a xDS client, which tells the synchronization
+// status between the xDS client and the xDS server.
+enum ClientResourceStatus {
+  // Resource status is not available/unknown.
+  UNKNOWN = 0;
+
+  // Client requested this resource but hasn't received any update from management
+  // server. The client will not fail requests, but will queue them until update
+  // arrives or the client times out waiting for the resource.
+  REQUESTED = 1;
+
+  // This resource has been requested by the client but has either not been
+  // delivered by the server or was previously delivered by the server and then
+  // subsequently removed from resources provided by the server. For more
+  // information, please refer to the :ref:`"Knowing When a Requested Resource
+  // Does Not Exist" <xds_protocol_resource_not_existed>` section.
+  DOES_NOT_EXIST = 2;
+
+  // Client received this resource and replied with ACK.
+  ACKED = 3;
+
+  // Client received this resource and replied with NACK.
+  NACKED = 4;
+}
+
 // The :ref:`/config_dump <operations_admin_interface_config_dump>` admin endpoint uses this wrapper
 // message to maintain and serve arbitrary configuration information from any component in Envoy.
 message ConfigDump {
@@ -114,7 +139,7 @@ message ListenersConfigDump {
   }
 
   // Describes a dynamically loaded listener via the LDS API.
-  // [#next-free-field: 6]
+  // [#next-free-field: 7]
   message DynamicListener {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v2alpha.ListenersConfigDump.DynamicListener";
@@ -143,6 +168,10 @@ message ListenersConfigDump {
     // resource along with the reason and timestamp. For successfully updated or
     // acknowledged resource, this field should be empty.
     UpdateFailureState error_state = 5;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 6;
   }
 
   // This is the :ref:`version_info <envoy_api_field_service.discovery.v3.DiscoveryResponse.version_info>` in the
@@ -177,6 +206,7 @@ message ClustersConfigDump {
   }
 
   // Describes a dynamically loaded cluster via the CDS API.
+  // [#next-free-field: 6]
   message DynamicCluster {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v2alpha.ClustersConfigDump.DynamicCluster";
@@ -199,6 +229,10 @@ message ClustersConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 4;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 5;
   }
 
   // This is the :ref:`version_info <envoy_api_field_service.discovery.v3.DiscoveryResponse.version_info>` in the
@@ -240,6 +274,7 @@ message RoutesConfigDump {
     google.protobuf.Timestamp last_updated = 2;
   }
 
+  // [#next-free-field: 6]
   message DynamicRouteConfig {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v2alpha.RoutesConfigDump.DynamicRouteConfig";
@@ -261,6 +296,10 @@ message RoutesConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 4;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 5;
   }
 
   // The statically loaded route configs.
@@ -292,7 +331,7 @@ message ScopedRoutesConfigDump {
     google.protobuf.Timestamp last_updated = 3;
   }
 
-  // [#next-free-field: 6]
+  // [#next-free-field: 7]
   message DynamicScopedRouteConfigs {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v2alpha.ScopedRoutesConfigDump.DynamicScopedRouteConfigs";
@@ -317,6 +356,10 @@ message ScopedRoutesConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 5;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 6;
   }
 
   // The statically loaded scoped route configs.
@@ -332,7 +375,7 @@ message SecretsConfigDump {
       "envoy.admin.v2alpha.SecretsConfigDump";
 
   // DynamicSecret contains secret information fetched via SDS.
-  // [#next-free-field: 6]
+  // [#next-free-field: 7]
   message DynamicSecret {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v2alpha.SecretsConfigDump.DynamicSecret";
@@ -357,6 +400,10 @@ message SecretsConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 5;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 6;
   }
 
   // StaticSecret specifies statically loaded secret in bootstrap.
@@ -400,6 +447,7 @@ message EndpointsConfigDump {
     google.protobuf.Timestamp last_updated = 2;
   }
 
+  // [#next-free-field: 6]
   message DynamicEndpointConfig {
     // [#not-implemented-hide:] This is the per-resource version information. This version is currently taken from the
     // :ref:`version_info <envoy_api_field_service.discovery.v3.DiscoveryResponse.version_info>` field at the time that
@@ -418,6 +466,10 @@ message EndpointsConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 4;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 5;
   }
 
   // The statically loaded endpoint configs.

envoy/admin/v4alpha/config_dump.proto

@@ -17,6 +17,31 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO
 
 // [#protodoc-title: ConfigDump]
 
+// Resource status from the view of a xDS client, which tells the synchronization
+// status between the xDS client and the xDS server.
+enum ClientResourceStatus {
+  // Resource status is not available/unknown.
+  UNKNOWN = 0;
+
+  // Client requested this resource but hasn't received any update from management
+  // server. The client will not fail requests, but will queue them until update
+  // arrives or the client times out waiting for the resource.
+  REQUESTED = 1;
+
+  // This resource has been requested by the client but has either not been
+  // delivered by the server or was previously delivered by the server and then
+  // subsequently removed from resources provided by the server. For more
+  // information, please refer to the :ref:`"Knowing When a Requested Resource
+  // Does Not Exist" <xds_protocol_resource_not_existed>` section.
+  DOES_NOT_EXIST = 2;
+
+  // Client received this resource and replied with ACK.
+  ACKED = 3;
+
+  // Client received this resource and replied with NACK.
+  NACKED = 4;
+}
+
 // The :ref:`/config_dump <operations_admin_interface_config_dump>` admin endpoint uses this wrapper
 // message to maintain and serve arbitrary configuration information from any component in Envoy.
 message ConfigDump {
@@ -111,7 +136,7 @@ message ListenersConfigDump {
   }
 
   // Describes a dynamically loaded listener via the LDS API.
-  // [#next-free-field: 6]
+  // [#next-free-field: 7]
   message DynamicListener {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v3.ListenersConfigDump.DynamicListener";
@@ -140,6 +165,10 @@ message ListenersConfigDump {
     // resource along with the reason and timestamp. For successfully updated or
     // acknowledged resource, this field should be empty.
     UpdateFailureState error_state = 5;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 6;
   }
 
   // This is the :ref:`version_info <envoy_api_field_service.discovery.v4alpha.DiscoveryResponse.version_info>` in the
@@ -173,6 +202,7 @@ message ClustersConfigDump {
   }
 
   // Describes a dynamically loaded cluster via the CDS API.
+  // [#next-free-field: 6]
   message DynamicCluster {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v3.ClustersConfigDump.DynamicCluster";
@@ -195,6 +225,10 @@ message ClustersConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 4;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 5;
   }
 
   // This is the :ref:`version_info <envoy_api_field_service.discovery.v4alpha.DiscoveryResponse.version_info>` in the
@@ -235,6 +269,7 @@ message RoutesConfigDump {
     google.protobuf.Timestamp last_updated = 2;
   }
 
+  // [#next-free-field: 6]
   message DynamicRouteConfig {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v3.RoutesConfigDump.DynamicRouteConfig";
@@ -256,6 +291,10 @@ message RoutesConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 4;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 5;
   }
 
   // The statically loaded route configs.
@@ -287,7 +326,7 @@ message ScopedRoutesConfigDump {
     google.protobuf.Timestamp last_updated = 3;
   }
 
-  // [#next-free-field: 6]
+  // [#next-free-field: 7]
   message DynamicScopedRouteConfigs {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v3.ScopedRoutesConfigDump.DynamicScopedRouteConfigs";
@@ -312,6 +351,10 @@ message ScopedRoutesConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 5;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 6;
   }
 
   // The statically loaded scoped route configs.
@@ -326,7 +369,7 @@ message SecretsConfigDump {
   option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.SecretsConfigDump";
 
   // DynamicSecret contains secret information fetched via SDS.
-  // [#next-free-field: 6]
+  // [#next-free-field: 7]
   message DynamicSecret {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v3.SecretsConfigDump.DynamicSecret";
@@ -351,6 +394,10 @@ message SecretsConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 5;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 6;
   }
 
   // StaticSecret specifies statically loaded secret in bootstrap.
@@ -399,6 +446,7 @@ message EndpointsConfigDump {
     google.protobuf.Timestamp last_updated = 2;
   }
 
+  // [#next-free-field: 6]
   message DynamicEndpointConfig {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.admin.v3.EndpointsConfigDump.DynamicEndpointConfig";
@@ -420,6 +468,10 @@ message EndpointsConfigDump {
     // acknowledged resource, this field should be empty.
     // [#not-implemented-hide:]
     UpdateFailureState error_state = 4;
+
+    // The client status of this resource.
+    // [#not-implemented-hide:]
+    ClientResourceStatus client_status = 5;
   }
 
   // The statically loaded endpoint configs.

envoy/service/status/v3/csds.proto

@@ -93,13 +93,17 @@ message PerXdsConfig {
 
   // Config status generated by management servers. Will not be present if the
   // CSDS server is an xDS client.
-  ConfigStatus status = 1 [(udpa.annotations.field_migrate).oneof_promotion = "status_config"];
+  ConfigStatus status = 1;
 
   // Client config status is populated by xDS clients. Will not be present if
   // the CSDS server is an xDS server. No matter what the client config status
   // is, xDS clients should always dump the most recent accepted xDS config.
-  ClientConfigStatus client_status = 7
+  //
-      [(udpa.annotations.field_migrate).oneof_promotion = "status_config"];
+  // .. attention::
+  //   This field is deprecated. Use :ref:`ClientResourceStatus
+  //   <envoy_v3_api_enum_admin.v3.ClientResourceStatus>` for per-resource
+  //   config status instead.
+  ClientConfigStatus client_status = 7 [deprecated = true];
 
   oneof per_xds_config {
     admin.v3.ListenersConfigDump listener_config = 2;

envoy/service/status/v4alpha/csds.proto

@@ -90,16 +90,13 @@ message PerXdsConfig {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.service.status.v3.PerXdsConfig";
 
-  oneof status_config {
+  reserved 7;
-    // Config status generated by management servers. Will not be present if the
+
-    // CSDS server is an xDS client.
+  reserved "client_status";
-    ConfigStatus status = 1;
+
-
+  // Config status generated by management servers. Will not be present if the
-    // Client config status is populated by xDS clients. Will not be present if
+  // CSDS server is an xDS client.
-    // the CSDS server is an xDS server. No matter what the client config status
+  ConfigStatus status = 1;
-    // is, xDS clients should always dump the most recent accepted xDS config.
-    ClientConfigStatus client_status = 7;
-  }
 
   oneof per_xds_config {
     admin.v4alpha.ListenersConfigDump listener_config = 2;

xds_protocol.rst

@@ -507,6 +507,8 @@ if no other :ref:`Listener <envoy_api_msg_Listener>` is pointing to :ref:`RouteC
 an empty :ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>` is effectively a no-op
 from the client's perspective.
 
+.. _xds_protocol_resource_not_existed:
+
 Knowing When a Requested Resource Does Not Exist
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^