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