From 508b7d4fb97a860082f91c0a409ba9c32c15a909 Mon Sep 17 00:00:00 2001 From: "data-plane-api(CircleCI)" Date: Mon, 30 Mar 2020 15:36:27 +0000 Subject: [PATCH] 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 Mirrored from https://github.com/envoyproxy/envoy @ 34fcdef99633947543070d5eadf32867e940694e --- BUILD | 2 + envoy/api/v2/core/event_service_config.proto | 26 +++++++ envoy/api/v2/core/health_check.proto | 8 ++- envoy/config/bootstrap/v2/bootstrap.proto | 6 ++ envoy/config/bootstrap/v3/bootstrap.proto | 6 ++ .../config/core/v3/event_service_config.proto | 28 ++++++++ envoy/config/core/v3/health_check.proto | 8 ++- envoy/service/event_reporting/v2alpha/BUILD | 13 ++++ .../v2alpha/event_reporting_service.proto | 62 +++++++++++++++++ envoy/service/event_reporting/v3/BUILD | 14 ++++ .../v3/event_reporting_service.proto | 69 +++++++++++++++++++ versioning/BUILD | 1 + 12 files changed, 241 insertions(+), 2 deletions(-) create mode 100644 envoy/api/v2/core/event_service_config.proto create mode 100644 envoy/config/core/v3/event_service_config.proto create mode 100644 envoy/service/event_reporting/v2alpha/BUILD create mode 100644 envoy/service/event_reporting/v2alpha/event_reporting_service.proto create mode 100644 envoy/service/event_reporting/v3/BUILD create mode 100644 envoy/service/event_reporting/v3/event_reporting_service.proto diff --git a/BUILD b/BUILD index b0f2c33b..29f8807e 100644 --- a/BUILD +++ b/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", diff --git a/envoy/api/v2/core/event_service_config.proto b/envoy/api/v2/core/event_service_config.proto new file mode 100644 index 00000000..778cbbe1 --- /dev/null +++ b/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; + } +} diff --git a/envoy/api/v2/core/health_check.proto b/envoy/api/v2/core/health_check.proto index 06e303bd..77b078cc 100644 --- a/envoy/api/v2/core/health_check.proto +++ b/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. diff --git a/envoy/config/bootstrap/v2/bootstrap.proto b/envoy/config/bootstrap/v2/bootstrap.proto index 66c7509f..09b6303e 100644 --- a/envoy/config/bootstrap/v2/bootstrap.proto +++ b/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 diff --git a/envoy/config/bootstrap/v3/bootstrap.proto b/envoy/config/bootstrap/v3/bootstrap.proto index 59e88a6c..0aa9e46e 100644 --- a/envoy/config/bootstrap/v3/bootstrap.proto +++ b/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 diff --git a/envoy/config/core/v3/event_service_config.proto b/envoy/config/core/v3/event_service_config.proto new file mode 100644 index 00000000..6be0b061 --- /dev/null +++ b/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; + } +} diff --git a/envoy/config/core/v3/health_check.proto b/envoy/config/core/v3/health_check.proto index de4f1e0c..ce693001 100644 --- a/envoy/config/core/v3/health_check.proto +++ b/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. diff --git a/envoy/service/event_reporting/v2alpha/BUILD b/envoy/service/event_reporting/v2alpha/BUILD new file mode 100644 index 00000000..6db6b085 --- /dev/null +++ b/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", + ], +) diff --git a/envoy/service/event_reporting/v2alpha/event_reporting_service.proto b/envoy/service/event_reporting/v2alpha/event_reporting_service.proto new file mode 100644 index 00000000..3b073253 --- /dev/null +++ b/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 ` + // * :ref:`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 { +} diff --git a/envoy/service/event_reporting/v3/BUILD b/envoy/service/event_reporting/v3/BUILD new file mode 100644 index 00000000..99d01d89 --- /dev/null +++ b/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", + ], +) diff --git a/envoy/service/event_reporting/v3/event_reporting_service.proto b/envoy/service/event_reporting/v3/event_reporting_service.proto new file mode 100644 index 00000000..d5335847 --- /dev/null +++ b/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 ` + // * :ref:`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"; +} diff --git a/versioning/BUILD b/versioning/BUILD index 697aee00..4be7f581 100644 --- a/versioning/BUILD +++ b/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",