cds: add configuration for healthy_panic_threshold (#465)

Also setup a message that we can use for other missing settings such as
zone aware LB settings.

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

STYLE.md

@@ -42,7 +42,8 @@ In addition, the following conventions should be followed:
 
     * Consuming code will break and require source change to match the changes.
 
-* Non-frozen fields should be tagged with `[#not-implemented-hide:]`, `[#not-implemented-warn:]`,  `[#proto-status: draft]` or `[#proto-status: experimental]`.
+* Non-frozen fields should be tagged with `[#not-implemented-hide:]`, `[#not-implemented-warn:]`,
+  `[#proto-status: draft]` or `[#proto-status: experimental]`.
 
 * Every proto directory should have a `README.md` describing its content. See
   for example [envoy.service](envoy/service/README.md).
@@ -93,6 +94,13 @@ In addition, the following conventions should be followed:
   pattern forces developers to explicitly choose the correct enum value for
   their use case, and avoid misunderstanding of the default behavior.
 
+* Proto fields should be sorted logically, not by field number. For large protos, place a comment
+  at the top that specifies the next free field number. E.g.,
+
+  ```
+  // [#comment:next free field: 28]
+  ```
+
 ## Package organization
 
 API definitions are layered hierarchically in packages from top-to-bottom:

docs/root/intro/arch_overview/load_balancing.rst

@@ -88,8 +88,10 @@ During load balancing, Envoy will generally only consider healthy hosts in an up
 However, if the percentage of healthy hosts in the cluster becomes too low, Envoy will disregard
 health status and balance amongst all hosts. This is known as the *panic threshold*. The default
 panic threshold is 50%. This is :ref:`configurable <config_cluster_manager_cluster_runtime>` via
-runtime. The panic threshold is used to avoid a situation in which host failures cascade throughout
-the cluster as load increases.
+runtime as well as in the :ref:`cluster configuration
+<envoy_api_field_Cluster.CommonLbConfig.healthy_panic_threshold>`. The panic threshold
+is used to avoid a situation in which host failures cascade throughout the cluster as load
+increases.
 
 .. _arch_overview_load_balancing_priority_levels:
 

envoy/api/v2/cds.proto

@@ -37,6 +37,8 @@ service ClusterDiscoveryService {
 
 // [#protodoc-title: Clusters]
 
+// Configuration for a single upstream cluster.
+// [#comment:next free field: 28]
 message Cluster {
   // Supplies the name of the cluster which must be unique across all clusters.
   // The cluster name is used when emitting
@@ -343,7 +345,17 @@ message Cluster {
     RingHashLbConfig ring_hash_lb_config = 23;
   }
 
-  // See :ref:`base.TransportSocket<envoy_api_msg_core.TransportSocket>` description.
+  // Common configuration for all load balancer implementations.
+  message CommonLbConfig {
+    // Configures the :ref:`healthy panic threshold <arch_overview_load_balancing_panic_threshold>`.
+    // If not specified, the default is 50%.
+    core.Percent healthy_panic_threshold = 1;
+  }
+
+  // Common configuration for all load balancer implementations.
+  CommonLbConfig common_lb_config = 27;
+
+  // Optional custom transport socket implementation to use for upstream connections.
   core.TransportSocket transport_socket = 24;
 
   // The Metadata field can be used to provide additional information about the
@@ -361,6 +373,8 @@ message Cluster {
     // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection.
     USE_DOWNSTREAM_PROTOCOL = 1;
   }
+
+  // Determines how Envoy selects the protocol used to speak to upstream hosts.
   ClusterProtocolSelection protocol_selection = 26;
 }