admin: add json serialized proto for /clusters (#3478)

Added the /clusters?format=json admin endpoint along with a proto representation of /clusters.

Risk Level: Low

Testing: Added a unit test for the new format.

Docs Changes: Added a brief description on the admin docs and linked to the more detailed proto definition.

Release Notes: Added release notes.

Fixes #2020

Signed-off-by: Matt Rice <mattrice@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 64605338ef040a949c5ea205bdd472a8fe42306c

docs/BUILD

@@ -12,6 +12,7 @@ package_group(
 proto_library(
     name = "protos",
     deps = [
+        "//envoy/admin/v2alpha:clusters",
         "//envoy/admin/v2alpha:config_dump",
         "//envoy/api/v2:cds",
         "//envoy/api/v2:discovery",

envoy/admin/v2alpha/BUILD

@@ -13,3 +13,21 @@ api_proto_library(
         "//envoy/config/bootstrap/v2:bootstrap",
     ],
 )
+
+api_proto_library(
+    name = "clusters",
+    srcs = ["clusters.proto"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":metrics",
+        "//envoy/api/v2/core:address",
+        "//envoy/api/v2/core:health_check",
+        "//envoy/type:percent",
+    ],
+)
+
+api_proto_library(
+    name = "metrics",
+    srcs = ["metrics.proto"],
+    visibility = ["//visibility:public"],
+)

envoy/admin/v2alpha/clusters.proto

@@ -0,0 +1,72 @@
+syntax = "proto3";
+
+package envoy.admin.v2alpha;
+
+import "envoy/admin/v2alpha/metrics.proto";
+import "envoy/api/v2/core/address.proto";
+import "envoy/api/v2/core/health_check.proto";
+import "envoy/type/percent.proto";
+
+// [#protodoc-title: Clusters]
+
+// Admin endpoint uses this wrapper for `/clusters` to display cluster status information.
+// See :ref:`/clusters <operations_admin_interface_clusters>` for more information.
+message Clusters {
+  // Mapping from cluster name to each cluster's status.
+  repeated ClusterStatus cluster_statuses = 1;
+}
+
+// Details an individual cluster's current status.
+message ClusterStatus {
+  // Name of the cluster.
+  string name = 1;
+
+  // Denotes whether this cluster was added via API or configured statically.
+  bool added_via_api = 2;
+
+  // The success rate threshold used in the last interval. The threshold is used to eject hosts
+  // based on their success rate. See 
+  // :ref:`Cluster outlier detection <arch_overview_outlier_detection>` statistics
+  //
+  // Note: this field may be omitted in any of the three following cases:
+  // 1. There were not enough hosts with enough request volume to proceed with success rate based outlier ejection.
+  // 2. The threshold is computed to be < 0 because a negative value implies that there was no threshold for that
+  // interval.
+  // 3. Outlier detection is not enabled for this cluster.
+  envoy.type.Percent success_rate_ejection_threshold = 3;
+
+  // Mapping from host address to the host's current status.
+  repeated HostStatus host_statuses = 4;
+}
+
+// Current state of a particular host.
+message HostStatus {
+  // Address of this host.
+  envoy.api.v2.core.Address address = 1;
+
+  // Mapping from the name of the statistic to the current value.
+  map<string, SimpleMetric> stats = 2;
+
+  // The host's current health status.
+  HostHealthStatus health_status = 3;
+
+  // Request success rate for this host over the last calculated interval.
+  //
+  // Note: the message will not be present if host did not have enough request volume to calculate
+  // success rate or the cluster did not have enough hosts to run through success rate outlier
+  // ejection.
+  envoy.type.Percent success_rate = 4;
+}
+
+// Health status for a host.
+message HostHealthStatus {
+  // The host is currently failing active health checks.
+  bool failed_active_health_check = 1;
+
+  // The host is currently considered an outlier and has been ejected.
+  bool failed_outlier_check = 2;
+
+  // Health status as reported by EDS. Note: only HEALTHY and UNHEALTHY are currently supported here.
+  // TODO(mrice32): pipe through remaining EDS health status possibilities.
+  envoy.api.v2.core.HealthStatus eds_health_status = 3;
+}

envoy/admin/v2alpha/metrics.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package envoy.admin.v2alpha;
+
+// [#protodoc-title: Metrics]
+
+// Proto representation of an Envoy Counter or Gauge value.
+message SimpleMetric {
+  enum Type {
+    COUNTER = 0;
+    GAUGE = 1;
+  }
+
+  // Type of metric represented.
+  Type type = 1;
+
+  // Current metric value.
+  uint64 value = 2;
+}