further documentation on the edge interval behavior

Signed-off-by: Marcelo Juchem <juchem@gmail.com>

include/envoy/upstream/health_checker.h

@@ -10,7 +10,21 @@ namespace Upstream {
 
 enum class HealthState { Unhealthy, Healthy };
 
-enum class HealthTransition { Unchanged, Changed, ChangePending };
+enum class HealthTransition {
+  /**
+   * Used when the health state of a host hasn't changed.
+   */
+  Unchanged,
+  /**
+   * Used when the health state of a host has changed.
+   */
+  Changed,
+  /**
+   * Used when the health check result differs from the health state of a host, but a change to the
+   * latter is delayed due to healthy/unhealthy threshold settings.
+   */
+  ChangePending
+};
 
 /**
  * Wraps active health checking of an upstream cluster.

source/common/upstream/health_checker_base_impl.cc

@@ -57,6 +57,15 @@ std::chrono::milliseconds HealthCheckerImplBase::interval(HealthState state,
   // refer to the HealthCheck API documentation for more details.
   uint64_t base_time_ms;
   if (cluster_.info()->stats().upstream_cx_total_.used()) {
+    // When healthy/unhealthy threshold is configured the health transition of a host will be
+    // delayed. In this situation Envoy should use the edge interval settings between health checks.
+    //
+    // Example scenario for an unhealthy host with healthy_threshold set to 3:
+    // - check fails, host is still unhealthy and next check happens after unhealthy_interval;
+    // - check succeeds, host is still unhealthy and next check happens after healthy_edge_interval;
+    // - check succeeds, host is still unhealthy and next check happens after healthy_edge_interval;
+    // - check succeeds, host is now healthy and next check happens after interval;
+    // - check succeeds, host is still healthy and next check happens after interval.
     switch (state) {
     case HealthState::Unhealthy:
       base_time_ms = changed_state == HealthTransition::ChangePending