docs: health_check.proto (#278)

Signed-off-by: Matt Klein <mklein@lyft.com>

api/eds.proto

@@ -63,7 +63,7 @@ service EndpointDiscoveryService {
 message LbEndpoint {
   Endpoint endpoint = 1;
 
-  // Optional health status when known and supplied by EDS server.
+  // [#not-implemented-hide:] Optional health status when known and supplied by EDS server.
   HealthStatus health_status = 2;
 
   // The endpoint metadata specifies values that may be used by the load

api/health_check.proto

@@ -1,5 +1,3 @@
-// [#protodoc-title: Health check]
-
 syntax = "proto3";
 
 package envoy.api.v2;
@@ -7,83 +5,119 @@ package envoy.api.v2;
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "validate/validate.proto";
+
+// [#protodoc-title: Health check]
+// * Health checking :ref:`architecture overview <arch_overview_health_checking>`.
+// * If health checking is configured for a cluster, additional statistics are emitted. They are
+//   documented :ref:`here <config_cluster_manager_cluster_stats>`.
+
 message HealthCheck {
   // The time to wait for a health check response. If the timeout is reached the
   // health check attempt will be considered a failure.
-  google.protobuf.Duration timeout = 1;
+  google.protobuf.Duration timeout = 1 [(validate.rules).duration.required = true];
+
   // The interval between health checks.
-  google.protobuf.Duration interval = 2;
+  google.protobuf.Duration interval = 2 [(validate.rules).duration.required = true];
+
   // An optional jitter amount in millseconds. If specified, during every
   // internal Envoy will add 0 to interval_jitter to the wait time.
   google.protobuf.Duration interval_jitter = 3;
 
   // The number of unhealthy health checks required before a host is marked
-  // unhealthy. Note that for http health checking if a host responds with 503
+  // unhealthy. Note that for *http* health checking if a host responds with 503
   // this threshold is ignored and the host is considered unhealthy immediately.
   google.protobuf.UInt32Value unhealthy_threshold = 4;
+
   // The number of healthy health checks required before a host is marked
   // healthy. Note that during startup, only a single successful health check is
   // required to mark a host healthy.
   google.protobuf.UInt32Value healthy_threshold = 5;
 
-  // Non-serving port for health checking.
+  // [#not-implemented-hide:] Non-serving port for health checking.
   google.protobuf.UInt32Value alt_port = 6;
+
   // Reuse health check connection between health checks. Default is true.
   google.protobuf.BoolValue reuse_connection = 7;
 
-  // Describes the encoding of the payload bytes in the payload
+  // Describes the encoding of the payload bytes in the payload.
   message Payload {
     oneof payload {
-      string text = 1;
+      option (validate.required) = true;
+
+      // Hex encoded payload. E.g., "000000FF".
+      string text = 1 [(validate.rules).string.min_len = 1];
+
+      // [#not-implemented-hide:] Binary payload.
       bytes binary = 2;
     }
   }
+
   message HttpHealthCheck {
-    // The value of the host header in the HTTPS health check request. If left
-    // empty (default value), the IP on behalf of which this health check is
-    // performed will be used.
+    // [#not-implemented-hide:] The value of the host header in the HTTPS health check request. If
+    // left empty (default value), the IP on behalf of which this health check is performed will be
+    // used.
     string host = 1;
-    // This parameter is required if the type is http. It species the HTTP path
-    // that will be requested during health checking. For example /healthcheck.
-    string path = 2;
+
+    // Specifies the HTTP path that will be requested during health checking. For example
+    // */healthcheck*.
+    string path = 2 [(validate.rules).string.min_len = 1];
+
+    // [#not-implemented-hide:] HTTP specific payload.
     Payload send = 3;
+
+    // [#not-implemented-hide:] HTTP specific response.
     Payload receive = 4;
-    // The Envoy HTTP health checker supports the service_name option. If this
-    // option is set, the health checker additionally compares the value of the
-    // x-envoy-upstream-healthchecked-cluster response header to service_name. If
-    // the values do not match, the health check does not pass. The upstream
-    // health check filter appends x-envoy-upstream-healthchecked-cluster to the
-    // response headers. The appended value is determined by the --service-cluster
-    // command line option.
+
+    // An optional service name parameter which is used to validate the identity of
+    // the health checked cluster. See the :ref:`architecture overview
+    // <arch_overview_health_checking_identity>` for more information.
     string service_name = 5;
   }
+
   message TcpHealthCheck {
     // Empty payloads imply a connect-only health check.
     Payload send = 1;
+
     // When checking the response, “fuzzy” matching is performed such that each
     // binary block must be found, and in the order specified, but not
-    // necessarly contiguous.
+    // necessarily contiguous.
     repeated Payload receive = 2;
   }
-  message RedisHealthCheck {
-  }
+
+  message RedisHealthCheck {}
+
   oneof health_checker {
+    option (validate.required) = true;
+
+    // HTTP health check.
     HttpHealthCheck http_health_check = 8;
+
+    // TCP health check.
     TcpHealthCheck tcp_health_check = 9;
+
+    // Redis health check.
     RedisHealthCheck redis_health_check = 10;
   }
 }
 
+// [#not-implemented-hide:] Part of HDS.
 enum HealthStatus {
   // UNKNOWN should be treated by Envoy as HEALTHY.
   UNKNOWN = 0;
+
+  // Healthy.
   HEALTHY = 1;
+
+  // Unhealthy.
   UNHEALTHY = 2;
-  // Connection draining in progress -
+
+  // Connection draining in progress. E.g.,
   // https://aws.amazon.com/blogs/aws/elb-connection-draining-remove-instances-from-service-with-care/
-  // and
+  // or
   // https://cloud.google.com/compute/docs/load-balancing/enabling-connection-draining.
   DRAINING = 3;
+
   // This value is used by HDS Remote server. From Envoy’s perspective
   // TIMEOUT = UNHEALTHY in case EDS returns HealthStatus.
   TIMEOUT = 4;

docs/root/api-v1/api.rst

@@ -5,6 +5,7 @@ v1 API reference
   :glob:
   :maxdepth: 2
 
+  cluster_manager/cluster_manager
   network_filters/network_filters
   route_config/route_config
   http_filters/http_filters

docs/root/api-v1/cluster_manager/cluster_hc.rst

@@ -0,0 +1,82 @@
+.. _config_cluster_manager_cluster_hc_v1:
+
+Health checking
+===============
+
+* Health checking :ref:`architecture overview <arch_overview_health_checking>`.
+* If health checking is configured for a cluster, additional statistics are emitted. They are
+  documented :ref:`here <config_cluster_manager_cluster_stats>`.
+
+.. code-block:: json
+
+  {
+    "type": "...",
+    "timeout_ms": "...",
+    "interval_ms": "...",
+    "unhealthy_threshold": "...",
+    "healthy_threshold": "...",
+    "path": "...",
+    "send": [],
+    "receive": [],
+    "interval_jitter_ms": "...",
+    "service_name": "..."
+  }
+
+type
+  *(required, string)* The type of health checking to perform. Currently supported types are
+  *http*, *redis*, and *tcp*. See the :ref:`architecture overview <arch_overview_health_checking>`
+  for more information.
+
+timeout_ms
+  *(required, integer)* The time in milliseconds to wait for a health check response. If the
+  timeout is reached the health check attempt will be considered a failure.
+
+.. _config_cluster_manager_cluster_hc_interval:
+
+interval_ms
+  *(required, integer)* The interval between health checks in milliseconds.
+
+unhealthy_threshold
+  *(required, integer)* The number of unhealthy health checks required before a host is marked
+  unhealthy. Note that for *http* health checking if a host responds with 503 this threshold is
+  ignored and the host is considered unhealthy immediately.
+
+healthy_threshold
+  *(required, integer)* The number of healthy health checks required before a host is marked
+  healthy. Note that during startup, only a single successful health check is required to mark
+  a host healthy.
+
+path
+  *(sometimes required, string)* This parameter is required if the type is *http*. It species the
+  HTTP path that will be requested during health checking. For example */healthcheck*.
+
+send
+  *(sometimes required, array)* This parameter is required if the type is *tcp*. It specifies
+  the bytes to send for a health check request. It is an array of hex byte strings specified
+  as in the following example:
+
+  .. code-block:: json
+
+    [
+      {"binary": "01"},
+      {"binary": "000000FF"}
+    ]
+
+  The array is allowed to be empty in the case of "connect only" health checking.
+
+receive
+  *(sometimes required, array)* This parameter is required if the type is *tcp*. It specified the
+  bytes that are expected in a successful health check response. It is an array of hex byte strings
+  specified similarly to the *send* parameter. The array is allowed to be empty in the case of
+  "connect only" health checking.
+
+interval_jitter_ms
+  *(optional, integer)* An optional jitter amount in millseconds. If specified, during every
+  internal Envoy will add 0 to *interval_jitter_ms* milliseconds to the wait time.
+
+.. _config_cluster_manager_cluster_hc_service_name:
+
+service_name
+  *(optional, string)* An optional service name parameter which is used to validate the identity of
+  the health checked cluster. See the :ref:`architecture overview
+  <arch_overview_health_checking_identity>` for more information.

docs/root/api-v1/cluster_manager/cluster_manager.rst

@@ -0,0 +1,8 @@
+Cluster manager
+===============
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  *

docs/root/configuration/cluster_manager/cluster_hc.rst

@@ -6,86 +6,19 @@ Health checking
 * Health checking :ref:`architecture overview <arch_overview_health_checking>`.
 * If health checking is configured for a cluster, additional statistics are emitted. They are
   documented :ref:`here <config_cluster_manager_cluster_stats>`.
-
-.. code-block:: json
-
-  {
-    "type": "...",
-    "timeout_ms": "...",
-    "interval_ms": "...",
-    "unhealthy_threshold": "...",
-    "healthy_threshold": "...",
-    "path": "...",
-    "send": [],
-    "receive": [],
-    "interval_jitter_ms": "...",
-    "service_name": "..."
-  }
-
-type
-  *(required, string)* The type of health checking to perform. Currently supported types are
-  *http*, *redis*, and *tcp*. See the :ref:`architecture overview <arch_overview_health_checking>`
-  for more information.
-
-timeout_ms
-  *(required, integer)* The time in milliseconds to wait for a health check response. If the
-  timeout is reached the health check attempt will be considered a failure.
-
-.. _config_cluster_manager_cluster_hc_interval:
-
-interval_ms
-  *(required, integer)* The interval between health checks in milliseconds.
-
-unhealthy_threshold
-  *(required, integer)* The number of unhealthy health checks required before a host is marked
-  unhealthy. Note that for *http* health checking if a host responds with 503 this threshold is
-  ignored and the host is considered unhealthy immediately.
-
-healthy_threshold
-  *(required, integer)* The number of healthy health checks required before a host is marked
-  healthy. Note that during startup, only a single successful health check is required to mark
-  a host healthy.
-
-path
-  *(sometimes required, string)* This parameter is required if the type is *http*. It species the
-  HTTP path that will be requested during health checking. For example */healthcheck*.
-
-send
-  *(sometimes required, array)* This parameter is required if the type is *tcp*. It specifies
-  the bytes to send for a health check request. It is an array of hex byte strings specified
-  as in the following example:
-
-  .. code-block:: json
-
-    [
-      {"binary": "01"},
-      {"binary": "000000FF"}
-    ]
-
-  The array is allowed to be empty in the case of "connect only" health checking.
-
-receive
-  *(sometimes required, array)* This parameter is required if the type is *tcp*. It specified the
-  bytes that are expected in a successful health check response. It is an array of hex byte strings
-  specified similarly to the *send* parameter. The array is allowed to be empty in the case of
-  "connect only" health checking.
-
-interval_jitter_ms
-  *(optional, integer)* An optional jitter amount in millseconds. If specified, during every
-  internal Envoy will add 0 to *interval_jitter_ms* milliseconds to the wait time.
-
-.. _config_cluster_manager_cluster_hc_service_name:
-
-service_name
-  *(optional, string)* An optional service name parameter which is used to validate the identity of
-  the health checked cluster. See the :ref:`architecture overview
-  <arch_overview_health_checking_identity>` for more information.
+* :ref:`v1 API documentation <config_cluster_manager_cluster_hc_v1>`.
+* :ref:`v2 API documentation <envoy_api_msg_HealthCheck>`.
 
 .. _config_cluster_manager_cluster_hc_tcp_health_checking:
 
 TCP health checking
 -------------------
 
+.. attention::
+
+  This section is written for the v1 API but the concepts also apply to the v2 API. It will be
+  rewritten to target the v2 API in a future release.
+
 The type of matching performed is the following (this is the MongoDB health check request and
 response):