hds: extend response protos group endpoint health by cluster and locality (#12153)

Currently, the HDS specifier proto gives endpoint information organized by their locality and grouped by cluster. This information is retained when doing health checks, however when responding with health statuses from each endpoint locality and cluster information is dropped. This puts all endpoint information into a flat list when returning, making it the responsibility of the receiver to re-structure data by cluster and locality.

This change follows a similar format to the specifier coming into HDS, organizing it in the same way. The proposed changed adds consistency to how messages are flowing in and out of HDS.

Note that his PR only contains the protos changes, and does not include implementation. This is done to get approval from api-shepherds for the changes before continuing.

Risk Level: Low
Testing: No new tests. New tests will be added upon implementation, but for now the fields remain empty.

Docs Changes:
Inline comments in hds.proto.

Release Notes:
N/A - will append to release notes upon implementation completion.

Deprecated:
The endpoints_health field in EndpointHealthResponse should be deprecated in favor of the new cluster_endpoints_health field.

Signed-off-by: Drew S. Ortega <drewortega@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 4f1ee95e36ad233aac0d37a8b1d7c4536d4972c7

envoy/service/health/v3/hds.proto

@@ -9,6 +9,7 @@ import "envoy/config/endpoint/v3/endpoint_components.proto";
 import "google/api/annotations.proto";
 import "google/protobuf/duration.proto";
 
+import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 
@@ -108,11 +109,32 @@ message EndpointHealth {
   config.core.v3.HealthStatus health_status = 2;
 }
 
+// Group endpoint health by locality under each cluster.
+message LocalityEndpointsHealth {
+  config.core.v3.Locality locality = 1;
+
+  repeated EndpointHealth endpoints_health = 2;
+}
+
+// The health status of endpoints in a cluster. The cluster name and locality
+// should match the corresponding fields in ClusterHealthCheck message.
+message ClusterEndpointsHealth {
+  string cluster_name = 1;
+
+  repeated LocalityEndpointsHealth locality_endpoints_health = 2;
+}
+
 message EndpointHealthResponse {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.service.discovery.v2.EndpointHealthResponse";
 
+  // [#comment:TODO(drewsortega): add deprecate annotation once cluster_endpoints_health is implemented]
+  // Deprecated - Flat list of endpoint health information.
   repeated EndpointHealth endpoints_health = 1;
+
+  // [#not-implemented-hide:]
+  // Organize Endpoint health information by cluster.
+  repeated ClusterEndpointsHealth cluster_endpoints_health = 2;
 }
 
 message HealthCheckRequestOrEndpointHealthResponse {

envoy/service/health/v4alpha/hds.proto

@@ -107,11 +107,38 @@ message EndpointHealth {
   config.core.v4alpha.HealthStatus health_status = 2;
 }
 
+// Group endpoint health by locality under each cluster.
+message LocalityEndpointsHealth {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.health.v3.LocalityEndpointsHealth";
+
+  config.core.v4alpha.Locality locality = 1;
+
+  repeated EndpointHealth endpoints_health = 2;
+}
+
+// The health status of endpoints in a cluster. The cluster name and locality
+// should match the corresponding fields in ClusterHealthCheck message.
+message ClusterEndpointsHealth {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.health.v3.ClusterEndpointsHealth";
+
+  string cluster_name = 1;
+
+  repeated LocalityEndpointsHealth locality_endpoints_health = 2;
+}
+
 message EndpointHealthResponse {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.service.health.v3.EndpointHealthResponse";
 
+  // [#comment:TODO(drewsortega): add deprecate annotation once cluster_endpoints_health is implemented]
+  // Deprecated - Flat list of endpoint health information.
   repeated EndpointHealth endpoints_health = 1;
+
+  // [#not-implemented-hide:]
+  // Organize Endpoint health information by cluster.
+  repeated ClusterEndpointsHealth cluster_endpoints_health = 2;
 }
 
 message HealthCheckRequestOrEndpointHealthResponse {