...

Text file src/github.com/emissary-ingress/emissary/v3/api/envoy/service/discovery/v2/hds.proto

Documentation: github.com/emissary-ingress/emissary/v3/api/envoy/service/discovery/v2

     1syntax = "proto3";
     2
     3package envoy.service.discovery.v2;
     4
     5import "envoy/api/v2/core/base.proto";
     6import "envoy/api/v2/core/health_check.proto";
     7import "envoy/api/v2/endpoint/endpoint_components.proto";
     8
     9import "google/api/annotations.proto";
    10import "google/protobuf/duration.proto";
    11
    12import "udpa/annotations/migrate.proto";
    13import "udpa/annotations/status.proto";
    14
    15option java_package = "io.envoyproxy.envoy.service.discovery.v2";
    16option java_outer_classname = "HdsProto";
    17option java_multiple_files = true;
    18option go_package = "github.com/envoyproxy/go-control-plane/envoy/service/discovery/v2;discoveryv2";
    19option java_generic_services = true;
    20option (udpa.annotations.file_migrate).move_to_package = "envoy.service.health.v3";
    21option (udpa.annotations.file_status).package_version_status = FROZEN;
    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 = "/v2/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  // Different Envoy instances may have different capabilities (e.g. Redis)
    82  // and/or have ports enabled for different protocols.
    83  enum Protocol {
    84    HTTP = 0;
    85    TCP = 1;
    86    REDIS = 2;
    87  }
    88
    89  repeated Protocol health_check_protocols = 1;
    90}
    91
    92message HealthCheckRequest {
    93  api.v2.core.Node node = 1;
    94
    95  Capability capability = 2;
    96}
    97
    98message EndpointHealth {
    99  api.v2.endpoint.Endpoint endpoint = 1;
   100
   101  api.v2.core.HealthStatus health_status = 2;
   102}
   103
   104message EndpointHealthResponse {
   105  repeated EndpointHealth endpoints_health = 1;
   106}
   107
   108message HealthCheckRequestOrEndpointHealthResponse {
   109  oneof request_type {
   110    HealthCheckRequest health_check_request = 1;
   111
   112    EndpointHealthResponse endpoint_health_response = 2;
   113  }
   114}
   115
   116message LocalityEndpoints {
   117  api.v2.core.Locality locality = 1;
   118
   119  repeated api.v2.endpoint.Endpoint endpoints = 2;
   120}
   121
   122// The cluster name and locality is provided to Envoy for the endpoints that it
   123// health checks to support statistics reporting, logging and debugging by the
   124// Envoy instance (outside of HDS). For maximum usefulness, it should match the
   125// same cluster structure as that provided by EDS.
   126message ClusterHealthCheck {
   127  string cluster_name = 1;
   128
   129  repeated api.v2.core.HealthCheck health_checks = 2;
   130
   131  repeated LocalityEndpoints locality_endpoints = 3;
   132}
   133
   134message HealthCheckSpecifier {
   135  repeated ClusterHealthCheck cluster_health_checks = 1;
   136
   137  // The default is 1 second.
   138  google.protobuf.Duration interval = 2;
   139}

View as plain text