CSDS: add new config status ACKED (#13121)

As the CSDS service definition described, it has the potential to be used to expose xDS config from a client or proxy. gRPC wants to utilize this service to improve its debuggability. But the ConfigStatus is designed from the control plane point of view. Especially, the client cannot predict if there is new config on its way, so it can't accurately claim any xDS config status as SYNCED. We need another config status to indicate the status that the client received the status and sent out ACK.

Risk Level: Low

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

Mirrored from https://github.com/envoyproxy/envoy @ 22061a275d5fb53132fd1f104dd53cb533922707

envoy/service/status/v3/csds.proto

@@ -9,6 +9,7 @@ import "envoy/type/matcher/v3/node.proto";
 import "google/api/annotations.proto";
 import "google/protobuf/struct.proto";
 
+import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 
@@ -21,9 +22,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // [#protodoc-title: Client Status Discovery Service (CSDS)]
 
 // CSDS is Client Status Discovery Service. It can be used to get the status of
-// an xDS-compliant client from the management server's point of view. In the
-// future, it can potentially be used as an interface to get the current
-// state directly from the client.
+// an xDS-compliant client from the management server's point of view. It can
+// also be used to get the current xDS states directly from the client.
 service ClientStatusDiscoveryService {
   rpc StreamClientStatus(stream ClientStatusRequest) returns (stream ClientStatusResponse) {
   }
@@ -34,7 +34,7 @@ service ClientStatusDiscoveryService {
   }
 }
 
-// Status of a config.
+// Status of a config from a management server view.
 enum ConfigStatus {
   // Status info is not available/unknown.
   UNKNOWN = 0;
@@ -49,10 +49,30 @@ enum ConfigStatus {
   // ACK/NACK.
   STALE = 3;
 
-  // Management server has sent the config to client but received NACK.
+  // Management server has sent the config to client but received NACK. The
+  // attached config dump will be the latest config (the rejected one), since
+  // it is the persisted version in the management server.
   ERROR = 4;
 }
 
+// Config status from a client-side view.
+enum ClientConfigStatus {
+  // Config status is not available/unknown.
+  CLIENT_UNKNOWN = 0;
+
+  // Client requested the config but hasn't received any config from management
+  // server yet.
+  CLIENT_REQUESTED = 1;
+
+  // Client received the config and replied with ACK.
+  CLIENT_ACKED = 2;
+
+  // Client received the config and replied with NACK. Notably, the attached
+  // config dump is not the NACKed version, but the most recent accepted one. If
+  // no config is accepted yet, the attached config dump will be empty.
+  CLIENT_NACKED = 3;
+}
+
 // Request for client status of clients identified by a list of NodeMatchers.
 message ClientStatusRequest {
   option (udpa.annotations.versioning).previous_message_type =
@@ -67,12 +87,20 @@ message ClientStatusRequest {
 }
 
 // Detailed config (per xDS) with status.
-// [#next-free-field: 7]
+// [#next-free-field: 8]
 message PerXdsConfig {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.service.status.v2.PerXdsConfig";
 
-  ConfigStatus status = 1;
+  // 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"];
+
+  // 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"];
 
   oneof per_xds_config {
     admin.v3.ListenersConfigDump listener_config = 2;

envoy/service/status/v4alpha/csds.proto

@@ -21,9 +21,8 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO
 // [#protodoc-title: Client Status Discovery Service (CSDS)]
 
 // CSDS is Client Status Discovery Service. It can be used to get the status of
-// an xDS-compliant client from the management server's point of view. In the
-// future, it can potentially be used as an interface to get the current
-// state directly from the client.
+// an xDS-compliant client from the management server's point of view. It can
+// also be used to get the current xDS states directly from the client.
 service ClientStatusDiscoveryService {
   rpc StreamClientStatus(stream ClientStatusRequest) returns (stream ClientStatusResponse) {
   }
@@ -34,7 +33,7 @@ service ClientStatusDiscoveryService {
   }
 }
 
-// Status of a config.
+// Status of a config from a management server view.
 enum ConfigStatus {
   // Status info is not available/unknown.
   UNKNOWN = 0;
@@ -49,10 +48,30 @@ enum ConfigStatus {
   // ACK/NACK.
   STALE = 3;
 
-  // Management server has sent the config to client but received NACK.
+  // Management server has sent the config to client but received NACK. The
+  // attached config dump will be the latest config (the rejected one), since
+  // it is the persisted version in the management server.
   ERROR = 4;
 }
 
+// Config status from a client-side view.
+enum ClientConfigStatus {
+  // Config status is not available/unknown.
+  CLIENT_UNKNOWN = 0;
+
+  // Client requested the config but hasn't received any config from management
+  // server yet.
+  CLIENT_REQUESTED = 1;
+
+  // Client received the config and replied with ACK.
+  CLIENT_ACKED = 2;
+
+  // Client received the config and replied with NACK. Notably, the attached
+  // config dump is not the NACKed version, but the most recent accepted one. If
+  // no config is accepted yet, the attached config dump will be empty.
+  CLIENT_NACKED = 3;
+}
+
 // Request for client status of clients identified by a list of NodeMatchers.
 message ClientStatusRequest {
   option (udpa.annotations.versioning).previous_message_type =
@@ -67,12 +86,21 @@ message ClientStatusRequest {
 }
 
 // Detailed config (per xDS) with status.
-// [#next-free-field: 7]
+// [#next-free-field: 8]
 message PerXdsConfig {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.service.status.v3.PerXdsConfig";
 
-  ConfigStatus status = 1;
+  oneof status_config {
+    // Config status generated by management servers. Will not be present if the
+    // CSDS server is an xDS client.
+    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;
+  }
 
   oneof per_xds_config {
     admin.v4alpha.ListenersConfigDump listener_config = 2;