Add Client Status Discovery Service (CSDS) API definition

api/BUILD

@@ -104,6 +104,7 @@ proto_library(
         "//envoy/service/load_stats/v2:pkg",
         "//envoy/service/metrics/v2:pkg",
         "//envoy/service/ratelimit/v2:pkg",
+        "//envoy/service/status/v2:pkg",
         "//envoy/service/tap/v2alpha:pkg",
         "//envoy/service/trace/v2:pkg",
         "//envoy/type:pkg",
@@ -219,6 +220,7 @@ proto_library(
         "//envoy/service/route/v3:pkg",
         "//envoy/service/runtime/v3:pkg",
         "//envoy/service/secret/v3:pkg",
+        "//envoy/service/status/v3:pkg",
         "//envoy/service/tap/v3:pkg",
         "//envoy/service/trace/v3:pkg",
         "//envoy/type/matcher/v3:pkg",

api/docs/BUILD

@@ -110,6 +110,7 @@ proto_library(
         "//envoy/service/load_stats/v2:pkg",
         "//envoy/service/metrics/v2:pkg",
         "//envoy/service/ratelimit/v2:pkg",
+        "//envoy/service/status/v2:pkg",
         "//envoy/service/tap/v2alpha:pkg",
         "//envoy/service/trace/v2:pkg",
         "//envoy/type:pkg",

api/envoy/service/status/v2/BUILD

@@ -0,0 +1,14 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    has_services = True,
+    deps = [
+        "//envoy/admin/v2alpha:pkg",
+        "//envoy/api/v2/core:pkg",
+        "//envoy/type/matcher:pkg",
+    ],
+)

api/envoy/service/status/v2/csds.proto

@@ -0,0 +1,86 @@
+syntax = "proto3";
+
+package envoy.service.status.v2;
+
+import "envoy/admin/v2alpha/config_dump.proto";
+import "envoy/api/v2/core/base.proto";
+import "envoy/type/matcher/node.proto";
+
+import "google/api/annotations.proto";
+import "google/protobuf/struct.proto";
+
+option java_package = "io.envoyproxy.envoy.service.status.v2";
+option java_outer_classname = "CsdsProto";
+option java_multiple_files = true;
+option java_generic_services = true;
+
+// [#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.
+service ClientStatusDiscoveryService {
+  rpc StreamClientStatus(stream ClientStatusRequest) returns (stream ClientStatusResponse) {
+  }
+
+  rpc FetchClientStatus(ClientStatusRequest) returns (ClientStatusResponse) {
+    option (google.api.http).post = "/v2/discovery:client_status";
+    option (google.api.http).body = "*";
+  }
+}
+
+// Status of a config.
+enum ConfigStatus {
+  // Status info is not available/unknown.
+  UNKNOWN = 0;
+
+  // Management server has sent the config to client and received ACK.
+  SYNCED = 1;
+
+  // Config is not sent.
+  NOT_SENT = 2;
+
+  // Management server has sent the config to client but hasn’t received
+  // ACK/NACK.
+  STALE = 3;
+
+  // Management server has sent the config to client but received NACK.
+  ERROR = 4;
+}
+
+// Request for client status of clients identified by a list of NodeMatchers.
+message ClientStatusRequest {
+  // Management server can use these match criteria to identify clients.
+  // The match follows OR semantics.
+  repeated type.matcher.NodeMatcher node_matchers = 1;
+}
+
+// Detailed config (per xDS) with status.
+// [#next-free-field: 6]
+message PerXdsConfig {
+  ConfigStatus status = 1;
+
+  oneof per_xds_config {
+    admin.v2alpha.ListenersConfigDump listener_config = 2;
+
+    admin.v2alpha.ClustersConfigDump cluster_config = 3;
+
+    admin.v2alpha.RoutesConfigDump route_config = 4;
+
+    admin.v2alpha.ScopedRoutesConfigDump scoped_route_config = 5;
+  }
+}
+
+// All xds configs for a particular client.
+message ClientConfig {
+  // Node for a particular client.
+  api.v2.core.Node node = 1;
+
+  repeated PerXdsConfig xds_config = 2;
+}
+
+message ClientStatusResponse {
+  // Client configs for the clients specified in the ClientStatusRequest.
+  repeated ClientConfig config = 1;
+}

api/envoy/service/status/v3/BUILD

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

api/envoy/service/status/v3/csds.proto

@@ -0,0 +1,100 @@
+syntax = "proto3";
+
+package envoy.service.status.v3;
+
+import "envoy/admin/v3/config_dump.proto";
+import "envoy/config/core/v3/base.proto";
+import "envoy/type/matcher/v3/node.proto";
+
+import "google/api/annotations.proto";
+import "google/protobuf/struct.proto";
+
+import "udpa/annotations/versioning.proto";
+
+option java_package = "io.envoyproxy.envoy.service.status.v3";
+option java_outer_classname = "CsdsProto";
+option java_multiple_files = true;
+option java_generic_services = true;
+
+// [#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.
+service ClientStatusDiscoveryService {
+  rpc StreamClientStatus(stream ClientStatusRequest) returns (stream ClientStatusResponse) {
+  }
+
+  rpc FetchClientStatus(ClientStatusRequest) returns (ClientStatusResponse) {
+    option (google.api.http).post = "/v3/discovery:client_status";
+    option (google.api.http).body = "*";
+  }
+}
+
+// Status of a config.
+enum ConfigStatus {
+  // Status info is not available/unknown.
+  UNKNOWN = 0;
+
+  // Management server has sent the config to client and received ACK.
+  SYNCED = 1;
+
+  // Config is not sent.
+  NOT_SENT = 2;
+
+  // Management server has sent the config to client but hasn’t received
+  // ACK/NACK.
+  STALE = 3;
+
+  // Management server has sent the config to client but received NACK.
+  ERROR = 4;
+}
+
+// Request for client status of clients identified by a list of NodeMatchers.
+message ClientStatusRequest {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.status.v2.ClientStatusRequest";
+
+  // Management server can use these match criteria to identify clients.
+  // The match follows OR semantics.
+  repeated type.matcher.v3.NodeMatcher node_matchers = 1;
+}
+
+// Detailed config (per xDS) with status.
+// [#next-free-field: 6]
+message PerXdsConfig {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.status.v2.PerXdsConfig";
+
+  ConfigStatus status = 1;
+
+  oneof per_xds_config {
+    admin.v3.ListenersConfigDump listener_config = 2;
+
+    admin.v3.ClustersConfigDump cluster_config = 3;
+
+    admin.v3.RoutesConfigDump route_config = 4;
+
+    admin.v3.ScopedRoutesConfigDump scoped_route_config = 5;
+  }
+}
+
+// All xds configs for a particular client.
+message ClientConfig {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.status.v2.ClientConfig";
+
+  // Node for a particular client.
+  config.core.v3.Node node = 1;
+
+  repeated PerXdsConfig xds_config = 2;
+}
+
+message ClientStatusResponse {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.status.v2.ClientStatusResponse";
+
+  // Client configs for the clients specified in the ClientStatusRequest.
+  repeated ClientConfig config = 1;
+}

api/envoy/type/matcher/metadata.proto

@@ -10,7 +10,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher";
 option java_outer_classname = "MetadataProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: MetadataMatcher]
+// [#protodoc-title: Metadata matcher]
 
 // MetadataMatcher provides a general interface to check if a given value is matched in
 // :ref:`Metadata <envoy_api_msg_core.Metadata>`. It uses `filter` and `path` to retrieve the value

api/envoy/type/matcher/node.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package envoy.type.matcher;
+
+import "envoy/type/matcher/metadata.proto";
+import "envoy/type/matcher/string.proto";
+
+option java_package = "io.envoyproxy.envoy.type.matcher";
+option java_outer_classname = "NodeProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: Node matcher]
+
+// Specifies the way to match a Node.
+// The match follows AND semantics.
+message NodeMatcher {
+  // Specifies match criteria on the node id.
+  StringMatcher node_id = 1;
+
+  // Specifies match criteria on the node metadata.
+  repeated MetadataMatcher node_metadatas = 2;
+}

api/envoy/type/matcher/number.proto

@@ -10,7 +10,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher";
 option java_outer_classname = "NumberProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: NumberMatcher]
+// [#protodoc-title: Number matcher]
 
 // Specifies the way to match a double value.
 message DoubleMatcher {

api/envoy/type/matcher/regex.proto

@@ -10,7 +10,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher";
 option java_outer_classname = "RegexProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: RegexMatcher]
+// [#protodoc-title: Regex matcher]
 
 // A regex matcher designed for safety when used with untrusted input.
 message RegexMatcher {

api/envoy/type/matcher/string.proto

@@ -11,7 +11,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher";
 option java_outer_classname = "StringProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: StringMatcher]
+// [#protodoc-title: String matcher]
 
 // Specifies the way to match a string.
 // [#next-free-field: 6]

api/envoy/type/matcher/v3/metadata.proto

@@ -12,7 +12,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher.v3";
 option java_outer_classname = "MetadataProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: MetadataMatcher]
+// [#protodoc-title: Metadata matcher]
 
 // MetadataMatcher provides a general interface to check if a given value is matched in
 // :ref:`Metadata <envoy_api_msg_config.core.v3.Metadata>`. It uses `filter` and `path` to retrieve the value

api/envoy/type/matcher/v3/node.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+
+package envoy.type.matcher.v3;
+
+import "envoy/type/matcher/v3/metadata.proto";
+import "envoy/type/matcher/v3/string.proto";
+
+import "udpa/annotations/versioning.proto";
+
+option java_package = "io.envoyproxy.envoy.type.matcher.v3";
+option java_outer_classname = "NodeProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: Node matcher]
+
+// Specifies the way to match a Node.
+// The match follows AND semantics.
+message NodeMatcher {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.type.matcher.NodeMatcher";
+
+  // Specifies match criteria on the node id.
+  StringMatcher node_id = 1;
+
+  // Specifies match criteria on the node metadata.
+  repeated MetadataMatcher node_metadatas = 2;
+}

api/envoy/type/matcher/v3/number.proto

@@ -12,7 +12,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher.v3";
 option java_outer_classname = "NumberProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: NumberMatcher]
+// [#protodoc-title: Number matcher]
 
 // Specifies the way to match a double value.
 message DoubleMatcher {

api/envoy/type/matcher/v3/regex.proto

@@ -12,7 +12,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher.v3";
 option java_outer_classname = "RegexProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: RegexMatcher]
+// [#protodoc-title: Regex matcher]
 
 // A regex matcher designed for safety when used with untrusted input.
 message RegexMatcher {

api/envoy/type/matcher/v3/string.proto

@@ -13,7 +13,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher.v3";
 option java_outer_classname = "StringProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: StringMatcher]
+// [#protodoc-title: String matcher]
 
 // Specifies the way to match a string.
 // [#next-free-field: 6]

api/envoy/type/matcher/v3/value.proto

@@ -13,7 +13,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher.v3";
 option java_outer_classname = "ValueProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: ValueMatcher]
+// [#protodoc-title: Value matcher]
 
 // Specifies the way to match a ProtobufWkt::Value. Primitive values and ListValue are supported.
 // StructValue is not supported and is always not matched.

api/envoy/type/matcher/value.proto

@@ -11,7 +11,7 @@ option java_package = "io.envoyproxy.envoy.type.matcher";
 option java_outer_classname = "ValueProto";
 option java_multiple_files = true;
 
-// [#protodoc-title: ValueMatcher]
+// [#protodoc-title: Value matcher]
 
 // Specifies the way to match a ProtobufWkt::Value. Primitive values and ListValue are supported.
 // StructValue is not supported and is always not matched.

docs/root/api-v2/service/service.rst

@@ -10,5 +10,6 @@ Services
   discovery/v2/*
   metrics/v2/*
   ratelimit/v2/*
+  status/v2/*
   tap/v2alpha/*
   trace/v2/*

docs/root/api-v2/types/types.rst

@@ -13,6 +13,7 @@ Types
   ../type/semantic_version.proto
   ../type/token_bucket.proto
   ../type/matcher/metadata.proto
+  ../type/matcher/node.proto
   ../type/matcher/number.proto
   ../type/matcher/regex.proto
   ../type/matcher/string.proto