1syntax = "proto3";
2
3package envoy.service.health.v3;
4
5import "envoy/config/cluster/v3/cluster.proto";
6import "envoy/config/core/v3/base.proto";
7import "envoy/config/core/v3/health_check.proto";
8import "envoy/config/endpoint/v3/endpoint_components.proto";
9
10import "google/api/annotations.proto";
11import "google/protobuf/duration.proto";
12
13import "udpa/annotations/migrate.proto";
14import "udpa/annotations/status.proto";
15import "udpa/annotations/versioning.proto";
16
17option java_package = "io.envoyproxy.envoy.service.health.v3";
18option java_outer_classname = "HdsProto";
19option java_multiple_files = true;
20option java_generic_services = true;
21option (udpa.annotations.file_status).package_version_status = ACTIVE;
22
23// [#protodoc-title: Health Discovery Service (HDS)]
24
25// HDS is Health Discovery Service. It compliments Envoy’s health checking
26// service by designating this Envoy to be a healthchecker for a subset of hosts
27// in the cluster. The status of these health checks will be reported to the
28// management server, where it can be aggregated etc and redistributed back to
29// Envoy through EDS.
30service HealthDiscoveryService {
31 // 1. Envoy starts up and if its can_healthcheck option in the static
32 // bootstrap config is enabled, sends HealthCheckRequest to the management
33 // server. It supplies its capabilities (which protocol it can health check
34 // with, what zone it resides in, etc.).
35 // 2. In response to (1), the management server designates this Envoy as a
36 // healthchecker to health check a subset of all upstream hosts for a given
37 // cluster (for example upstream Host 1 and Host 2). It streams
38 // HealthCheckSpecifier messages with cluster related configuration for all
39 // clusters this Envoy is designated to health check. Subsequent
40 // HealthCheckSpecifier message will be sent on changes to:
41 // a. Endpoints to health checks
42 // b. Per cluster configuration change
43 // 3. Envoy creates a health probe based on the HealthCheck config and sends
44 // it to endpoint(ip:port) of Host 1 and 2. Based on the HealthCheck
45 // configuration Envoy waits upon the arrival of the probe response and
46 // looks at the content of the response to decide whether the endpoint is
47 // healthy or not. If a response hasn't been received within the timeout
48 // interval, the endpoint health status is considered TIMEOUT.
49 // 4. Envoy reports results back in an EndpointHealthResponse message.
50 // Envoy streams responses as often as the interval configured by the
51 // management server in HealthCheckSpecifier.
52 // 5. The management Server collects health statuses for all endpoints in the
53 // cluster (for all clusters) and uses this information to construct
54 // EndpointDiscoveryResponse messages.
55 // 6. Once Envoy has a list of upstream endpoints to send traffic to, it load
56 // balances traffic to them without additional health checking. It may
57 // use inline healthcheck (i.e. consider endpoint UNHEALTHY if connection
58 // failed to a particular endpoint to account for health status propagation
59 // delay between HDS and EDS).
60 // By default, can_healthcheck is true. If can_healthcheck is false, Cluster
61 // configuration may not contain HealthCheck message.
62 // TODO(htuch): How is can_healthcheck communicated to CDS to ensure the above
63 // invariant?
64 // TODO(htuch): Add @amb67's diagram.
65 rpc StreamHealthCheck(stream HealthCheckRequestOrEndpointHealthResponse)
66 returns (stream HealthCheckSpecifier) {
67 }
68
69 // TODO(htuch): Unlike the gRPC version, there is no stream-based binding of
70 // request/response. Should we add an identifier to the HealthCheckSpecifier
71 // to bind with the response?
72 rpc FetchHealthCheck(HealthCheckRequestOrEndpointHealthResponse) returns (HealthCheckSpecifier) {
73 option (google.api.http).post = "/v3/discovery:health_check";
74 option (google.api.http).body = "*";
75 }
76}
77
78// Defines supported protocols etc, so the management server can assign proper
79// endpoints to healthcheck.
80message Capability {
81 option (udpa.annotations.versioning).previous_message_type =
82 "envoy.service.discovery.v2.Capability";
83
84 // Different Envoy instances may have different capabilities (e.g. Redis)
85 // and/or have ports enabled for different protocols.
86 enum Protocol {
87 HTTP = 0;
88 TCP = 1;
89 REDIS = 2;
90 }
91
92 repeated Protocol health_check_protocols = 1;
93}
94
95message HealthCheckRequest {
96 option (udpa.annotations.versioning).previous_message_type =
97 "envoy.service.discovery.v2.HealthCheckRequest";
98
99 config.core.v3.Node node = 1;
100
101 Capability capability = 2;
102}
103
104message EndpointHealth {
105 option (udpa.annotations.versioning).previous_message_type =
106 "envoy.service.discovery.v2.EndpointHealth";
107
108 config.endpoint.v3.Endpoint endpoint = 1;
109
110 config.core.v3.HealthStatus health_status = 2;
111}
112
113// Group endpoint health by locality under each cluster.
114message LocalityEndpointsHealth {
115 config.core.v3.Locality locality = 1;
116
117 repeated EndpointHealth endpoints_health = 2;
118}
119
120// The health status of endpoints in a cluster. The cluster name and locality
121// should match the corresponding fields in ClusterHealthCheck message.
122message ClusterEndpointsHealth {
123 string cluster_name = 1;
124
125 repeated LocalityEndpointsHealth locality_endpoints_health = 2;
126}
127
128message EndpointHealthResponse {
129 option (udpa.annotations.versioning).previous_message_type =
130 "envoy.service.discovery.v2.EndpointHealthResponse";
131
132 // Deprecated - Flat list of endpoint health information.
133 repeated EndpointHealth endpoints_health = 1 [deprecated = true];
134
135 // Organize Endpoint health information by cluster.
136 repeated ClusterEndpointsHealth cluster_endpoints_health = 2;
137}
138
139message HealthCheckRequestOrEndpointHealthResponse {
140 option (udpa.annotations.versioning).previous_message_type =
141 "envoy.service.discovery.v2.HealthCheckRequestOrEndpointHealthResponse";
142
143 oneof request_type {
144 HealthCheckRequest health_check_request = 1;
145
146 EndpointHealthResponse endpoint_health_response = 2;
147 }
148}
149
150message LocalityEndpoints {
151 option (udpa.annotations.versioning).previous_message_type =
152 "envoy.service.discovery.v2.LocalityEndpoints";
153
154 config.core.v3.Locality locality = 1;
155
156 repeated config.endpoint.v3.Endpoint endpoints = 2;
157}
158
159// The cluster name and locality is provided to Envoy for the endpoints that it
160// health checks to support statistics reporting, logging and debugging by the
161// Envoy instance (outside of HDS). For maximum usefulness, it should match the
162// same cluster structure as that provided by EDS.
163message ClusterHealthCheck {
164 option (udpa.annotations.versioning).previous_message_type =
165 "envoy.service.discovery.v2.ClusterHealthCheck";
166
167 string cluster_name = 1;
168
169 repeated config.core.v3.HealthCheck health_checks = 2;
170
171 repeated LocalityEndpoints locality_endpoints = 3;
172
173 // Optional map that gets filtered by :ref:`health_checks.transport_socket_match_criteria <envoy_api_field_config.core.v3.HealthCheck.transport_socket_match_criteria>`
174 // on connection when health checking. For more details, see
175 // :ref:`config.cluster.v3.Cluster.transport_socket_matches <envoy_api_field_config.cluster.v3.Cluster.transport_socket_matches>`.
176 repeated config.cluster.v3.Cluster.TransportSocketMatch transport_socket_matches = 4;
177}
178
179message HealthCheckSpecifier {
180 option (udpa.annotations.versioning).previous_message_type =
181 "envoy.service.discovery.v2.HealthCheckSpecifier";
182
183 repeated ClusterHealthCheck cluster_health_checks = 1;
184
185 // The default is 1 second.
186 google.protobuf.Duration interval = 2;
187}
View as plain text