API definitions for health check & outlier detection event services (#…

…10407)

This PR introduces gRPC services interfaces for outlier detection and healthcheck events services.

Risk Level: low
Testing: n.a.
Docs Changes: not yet
Release Notes: not yet

Relates to #8970

Signed-off-by: Alexey Baranov <me@kotiki.cc>

api/BUILD

@@ -110,6 +110,7 @@ proto_library(
         "//envoy/service/accesslog/v2:pkg",
         "//envoy/service/auth/v2:pkg",
         "//envoy/service/discovery/v2:pkg",
+        "//envoy/service/event_reporting/v2alpha:pkg",
         "//envoy/service/load_stats/v2:pkg",
         "//envoy/service/metrics/v2:pkg",
         "//envoy/service/ratelimit/v2:pkg",
@@ -230,6 +231,7 @@ proto_library(
         "//envoy/service/cluster/v3:pkg",
         "//envoy/service/discovery/v3:pkg",
         "//envoy/service/endpoint/v3:pkg",
+        "//envoy/service/event_reporting/v3:pkg",
         "//envoy/service/health/v3:pkg",
         "//envoy/service/listener/v3:pkg",
         "//envoy/service/load_stats/v3:pkg",

api/envoy/api/v2/core/event_service_config.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+
+package envoy.api.v2.core;
+
+import "envoy/api/v2/core/grpc_service.proto";
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.api.v2.core";
+option java_outer_classname = "EventServiceConfigProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_migrate).move_to_package = "envoy.config.core.v3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#not-implemented-hide:]
+// Configuration of the event reporting service endpoint.
+message EventServiceConfig {
+  oneof config_source_specifier {
+    option (validate.required) = true;
+
+    // Specifies the gRPC service that hosts the event reporting service.
+    GrpcService grpc_service = 1;
+  }
+}

api/envoy/api/v2/core/health_check.proto

@@ -3,6 +3,7 @@ syntax = "proto3";
 package envoy.api.v2.core;
 
 import "envoy/api/v2/core/base.proto";
+import "envoy/api/v2/core/event_service_config.proto";
 import "envoy/type/http.proto";
 import "envoy/type/matcher/string.proto";
 import "envoy/type/range.proto";
@@ -54,7 +55,7 @@ enum HealthStatus {
   DEGRADED = 5;
 }
 
-// [#next-free-field: 22]
+// [#next-free-field: 23]
 message HealthCheck {
   // Describes the encoding of the payload bytes in the payload.
   message Payload {
@@ -290,6 +291,11 @@ message HealthCheck {
   // If empty, no event log will be written.
   string event_log_path = 17;
 
+  // [#not-implemented-hide:]
+  // The gRPC service for the health check event service.
+  // If empty, health check events won't be sent to a remote endpoint.
+  EventServiceConfig event_service = 22;
+
   // If set to true, health check failure events will always be logged. If set to false, only the
   // initial health check failure event will be logged.
   // The default value is false.

api/envoy/config/bootstrap/v2/bootstrap.proto

@@ -7,6 +7,7 @@ import "envoy/api/v2/cluster.proto";
 import "envoy/api/v2/core/address.proto";
 import "envoy/api/v2/core/base.proto";
 import "envoy/api/v2/core/config_source.proto";
+import "envoy/api/v2/core/event_service_config.proto";
 import "envoy/api/v2/core/socket_option.proto";
 import "envoy/api/v2/listener.proto";
 import "envoy/config/metrics/v2/stats.proto";
@@ -194,6 +195,11 @@ message ClusterManager {
   message OutlierDetection {
     // Specifies the path to the outlier event log.
     string event_log_path = 1;
+
+    // [#not-implemented-hide:]
+    // The gRPC service for the outlier detection event service.
+    // If empty, outlier detection events won't be sent to a remote endpoint.
+    api.v2.core.EventServiceConfig event_service = 2;
   }
 
   // Name of the local cluster (i.e., the cluster that owns the Envoy running

api/envoy/config/bootstrap/v3/bootstrap.proto

@@ -6,6 +6,7 @@ import "envoy/config/cluster/v3/cluster.proto";
 import "envoy/config/core/v3/address.proto";
 import "envoy/config/core/v3/base.proto";
 import "envoy/config/core/v3/config_source.proto";
+import "envoy/config/core/v3/event_service_config.proto";
 import "envoy/config/core/v3/socket_option.proto";
 import "envoy/config/listener/v3/listener.proto";
 import "envoy/config/metrics/v3/stats.proto";
@@ -209,6 +210,11 @@ message ClusterManager {
 
     // Specifies the path to the outlier event log.
     string event_log_path = 1;
+
+    // [#not-implemented-hide:]
+    // The gRPC service for the outlier detection event service.
+    // If empty, outlier detection events won't be sent to a remote endpoint.
+    core.v3.EventServiceConfig event_service = 2;
   }
 
   // Name of the local cluster (i.e., the cluster that owns the Envoy running

api/envoy/config/core/v3/event_service_config.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package envoy.config.core.v3;
+
+import "envoy/config/core/v3/grpc_service.proto";
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.config.core.v3";
+option java_outer_classname = "EventServiceConfigProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;
+
+// [#not-implemented-hide:]
+// Configuration of the event reporting service endpoint.
+message EventServiceConfig {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.api.v2.core.EventServiceConfig";
+
+  oneof config_source_specifier {
+    option (validate.required) = true;
+
+    // Specifies the gRPC service that hosts the event reporting service.
+    GrpcService grpc_service = 1;
+  }
+}

api/envoy/config/core/v3/health_check.proto

@@ -3,6 +3,7 @@ syntax = "proto3";
 package envoy.config.core.v3;
 
 import "envoy/config/core/v3/base.proto";
+import "envoy/config/core/v3/event_service_config.proto";
 import "envoy/type/matcher/v3/string.proto";
 import "envoy/type/v3/http.proto";
 import "envoy/type/v3/range.proto";
@@ -53,7 +54,7 @@ enum HealthStatus {
   DEGRADED = 5;
 }
 
-// [#next-free-field: 22]
+// [#next-free-field: 23]
 message HealthCheck {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HealthCheck";
 
@@ -303,6 +304,11 @@ message HealthCheck {
   // If empty, no event log will be written.
   string event_log_path = 17;
 
+  // [#not-implemented-hide:]
+  // The gRPC service for the health check event service.
+  // If empty, health check events won't be sent to a remote endpoint.
+  EventServiceConfig event_service = 22;
+
   // If set to true, health check failure events will always be logged. If set to false, only the
   // initial health check failure event will be logged.
   // The default value is false.

api/envoy/service/event_reporting/v2alpha/BUILD

@@ -0,0 +1,13 @@
+# 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/api/v2/core:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

api/envoy/service/event_reporting/v2alpha/event_reporting_service.proto

@@ -0,0 +1,62 @@
+syntax = "proto3";
+
+package envoy.service.event_reporting.v2alpha;
+
+import "envoy/api/v2/core/base.proto";
+
+import "google/protobuf/any.proto";
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.service.event_reporting.v2alpha";
+option java_outer_classname = "EventReportingServiceProto";
+option java_multiple_files = true;
+option java_generic_services = true;
+option (udpa.annotations.file_migrate).move_to_package = "envoy.service.event_reporting.v3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: gRPC Event Reporting Service]
+
+// [#not-implemented-hide:]
+// Service for streaming different types of events from Envoy to a server. The examples of
+// such events may be health check or outlier detection events.
+service EventReportingService {
+  // Envoy will connect and send StreamEventsRequest messages forever.
+  // The management server may send StreamEventsResponse to configure event stream. See below.
+  // This API is designed for high throughput with the expectation that it might be lossy.
+  rpc StreamEvents(stream StreamEventsRequest) returns (stream StreamEventsResponse) {
+  }
+}
+
+// [#not-implemented-hide:]
+// An events envoy sends to the management server.
+message StreamEventsRequest {
+  message Identifier {
+    // The node sending the event messages over the stream.
+    api.v2.core.Node node = 1 [(validate.rules).message = {required: true}];
+  }
+
+  // Identifier data that will only be sent in the first message on the stream. This is effectively
+  // structured metadata and is a performance optimization.
+  Identifier identifier = 1;
+
+  // Batch of events. When the stream is already active, it will be the events occurred
+  // since the last message had been sent. If the server receives unknown event type, it should
+  // silently ignore it.
+  //
+  // The following events are supported:
+  //
+  // * :ref:`HealthCheckEvent <envoy_api_msg_data.core.v2alpha.HealthCheckEvent>`
+  // * :ref:`OutlierDetectionEvent <envoy_api_msg_data.cluster.v2alpha.OutlierDetectionEvent>`
+  repeated google.protobuf.Any events = 2 [(validate.rules).repeated = {min_items: 1}];
+}
+
+// [#not-implemented-hide:]
+// The management server may send envoy a StreamEventsResponse to tell which events the server
+// is interested in. In future, with aggregated event reporting service, this message will
+// contain, for example, clusters the envoy should send events for, or event types the server
+// wants to process.
+message StreamEventsResponse {
+}

api/envoy/service/event_reporting/v3/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/config/core/v3:pkg",
+        "//envoy/service/event_reporting/v2alpha:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

api/envoy/service/event_reporting/v3/event_reporting_service.proto

@@ -0,0 +1,69 @@
+syntax = "proto3";
+
+package envoy.service.event_reporting.v3;
+
+import "envoy/config/core/v3/base.proto";
+
+import "google/protobuf/any.proto";
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.service.event_reporting.v3";
+option java_outer_classname = "EventReportingServiceProto";
+option java_multiple_files = true;
+option java_generic_services = true;
+option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;
+
+// [#protodoc-title: gRPC Event Reporting Service]
+
+// [#not-implemented-hide:]
+// Service for streaming different types of events from Envoy to a server. The examples of
+// such events may be health check or outlier detection events.
+service EventReportingService {
+  // Envoy will connect and send StreamEventsRequest messages forever.
+  // The management server may send StreamEventsResponse to configure event stream. See below.
+  // This API is designed for high throughput with the expectation that it might be lossy.
+  rpc StreamEvents(stream StreamEventsRequest) returns (stream StreamEventsResponse) {
+  }
+}
+
+// [#not-implemented-hide:]
+// An events envoy sends to the management server.
+message StreamEventsRequest {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.event_reporting.v2alpha.StreamEventsRequest";
+
+  message Identifier {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.service.event_reporting.v2alpha.StreamEventsRequest.Identifier";
+
+    // The node sending the event messages over the stream.
+    config.core.v3.Node node = 1 [(validate.rules).message = {required: true}];
+  }
+
+  // Identifier data that will only be sent in the first message on the stream. This is effectively
+  // structured metadata and is a performance optimization.
+  Identifier identifier = 1;
+
+  // Batch of events. When the stream is already active, it will be the events occurred
+  // since the last message had been sent. If the server receives unknown event type, it should
+  // silently ignore it.
+  //
+  // The following events are supported:
+  //
+  // * :ref:`HealthCheckEvent <envoy_api_msg_data.core.v3.HealthCheckEvent>`
+  // * :ref:`OutlierDetectionEvent <envoy_api_msg_data.cluster.v3.OutlierDetectionEvent>`
+  repeated google.protobuf.Any events = 2 [(validate.rules).repeated = {min_items: 1}];
+}
+
+// [#not-implemented-hide:]
+// The management server may send envoy a StreamEventsResponse to tell which events the server
+// is interested in. In future, with aggregated event reporting service, this message will
+// contain, for example, clusters the envoy should send events for, or event types the server
+// wants to process.
+message StreamEventsResponse {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.service.event_reporting.v2alpha.StreamEventsResponse";
+}

api/versioning/BUILD

@@ -111,6 +111,7 @@ proto_library(
         "//envoy/service/accesslog/v2:pkg",
         "//envoy/service/auth/v2:pkg",
         "//envoy/service/discovery/v2:pkg",
+        "//envoy/service/event_reporting/v2alpha:pkg",
         "//envoy/service/load_stats/v2:pkg",
         "//envoy/service/metrics/v2:pkg",
         "//envoy/service/ratelimit/v2:pkg",