healthcheck: support transport socket matching (#10862)

Users can specify metadata in a health check's config that will be
used to select a matching transport socket from those configured in a
cluster's transport_socket_matches. This allows users to configure a
different transport socket for health check connections than the one
that is used to create a connection to an endpoint for proxying.

Risk Level: low; small optional feature
Testing: added unit tests
Docs Changes: updated health check and cluster proto docs with an explanation and example.
Release Notes: added

Fixes #10575

Signed-off-by: Spencer Lewis <slewis@squareup.com>

Mirrored from https://github.com/envoyproxy/envoy @ b6c8bb3a4ac6bcce221643a4924befd5eefd6815

envoy/config/cluster/v3/cluster.proto

@@ -547,6 +547,10 @@ message Cluster {
   // *TransportSocketMatch* in this field. Other client Envoys receive CDS without
   // *transport_socket_match* set, and still send plain text traffic to the same cluster.
   //
+  // This field can be used to specify custom transport socket configurations for health
+  // checks by adding matching key/value pairs in a health check's
+  // :ref:`transport socket match criteria <envoy_api_field_config.core.v3.HealthCheck.transport_socket_match_criteria>` field.
+  //
   // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.]
   repeated TransportSocketMatch transport_socket_matches = 43;
 

envoy/config/cluster/v4alpha/cluster.proto

@@ -548,6 +548,10 @@ message Cluster {
   // *TransportSocketMatch* in this field. Other client Envoys receive CDS without
   // *transport_socket_match* set, and still send plain text traffic to the same cluster.
   //
+  // This field can be used to specify custom transport socket configurations for health
+  // checks by adding matching key/value pairs in a health check's
+  // :ref:`transport socket match criteria <envoy_api_field_config.core.v4alpha.HealthCheck.transport_socket_match_criteria>` field.
+  //
   // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.]
   repeated TransportSocketMatch transport_socket_matches = 43;
 

envoy/config/core/v3/health_check.proto

@@ -54,7 +54,7 @@ enum HealthStatus {
   DEGRADED = 5;
 }
 
-// [#next-free-field: 23]
+// [#next-free-field: 24]
 message HealthCheck {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HealthCheck";
 
@@ -323,4 +323,36 @@ message HealthCheck {
 
   // This allows overriding the cluster TLS settings, just for health check connections.
   TlsOptions tls_options = 21;
+
+  // Optional key/value pairs that will be used to match a transport socket from those specified in the cluster's
+  // :ref:`tranport socket matches <envoy_api_field_config.cluster.v3.Cluster.transport_socket_matches>`.
+  // For example, the following match criteria
+  //
+  // .. code-block:: yaml
+  //
+  //  transport_socket_match_criteria:
+  //    useMTLS: true
+  //
+  // Will match the following :ref:`cluster socket match <envoy_api_msg_config.cluster.v3.Cluster.TransportSocketMatch>`
+  //
+  // .. code-block:: yaml
+  //
+  //  transport_socket_matches:
+  //  - name: "useMTLS"
+  //    match:
+  //      useMTLS: true
+  //    transport_socket:
+  //      name: envoy.transport_sockets.tls
+  //      config: { ... } # tls socket configuration
+  //
+  // If this field is set, then for health checks it will supersede an entry of *envoy.transport_socket* in the
+  // :ref:`LbEndpoint.Metadata <envoy_api_field_config.endpoint.v3.LbEndpoint.metadata>`.
+  // This allows using different transport socket capabilities for health checking versus proxying to the
+  // endpoint.
+  //
+  // If the key/values pairs specified do not match any
+  // :ref:`transport socket matches <envoy_api_field_config.cluster.v3.Cluster.transport_socket_matches>`,
+  // the cluster's :ref:`transport socket <envoy_api_field_config.cluster.v3.Cluster.transport_socket>`
+  // will be used for health check socket configuration.
+  google.protobuf.Struct transport_socket_match_criteria = 23;
 }

envoy/config/core/v4alpha/health_check.proto

@@ -54,7 +54,7 @@ enum HealthStatus {
   DEGRADED = 5;
 }
 
-// [#next-free-field: 23]
+// [#next-free-field: 24]
 message HealthCheck {
   option (udpa.annotations.versioning).previous_message_type = "envoy.config.core.v3.HealthCheck";
 
@@ -323,4 +323,36 @@ message HealthCheck {
 
   // This allows overriding the cluster TLS settings, just for health check connections.
   TlsOptions tls_options = 21;
+
+  // Optional key/value pairs that will be used to match a transport socket from those specified in the cluster's
+  // :ref:`tranport socket matches <envoy_api_field_config.cluster.v4alpha.Cluster.transport_socket_matches>`.
+  // For example, the following match criteria
+  //
+  // .. code-block:: yaml
+  //
+  //  transport_socket_match_criteria:
+  //    useMTLS: true
+  //
+  // Will match the following :ref:`cluster socket match <envoy_api_msg_config.cluster.v4alpha.Cluster.TransportSocketMatch>`
+  //
+  // .. code-block:: yaml
+  //
+  //  transport_socket_matches:
+  //  - name: "useMTLS"
+  //    match:
+  //      useMTLS: true
+  //    transport_socket:
+  //      name: envoy.transport_sockets.tls
+  //      config: { ... } # tls socket configuration
+  //
+  // If this field is set, then for health checks it will supersede an entry of *envoy.transport_socket* in the
+  // :ref:`LbEndpoint.Metadata <envoy_api_field_config.endpoint.v3.LbEndpoint.metadata>`.
+  // This allows using different transport socket capabilities for health checking versus proxying to the
+  // endpoint.
+  //
+  // If the key/values pairs specified do not match any
+  // :ref:`transport socket matches <envoy_api_field_config.cluster.v4alpha.Cluster.transport_socket_matches>`,
+  // the cluster's :ref:`transport socket <envoy_api_field_config.cluster.v4alpha.Cluster.transport_socket>`
+  // will be used for health check socket configuration.
+  google.protobuf.Struct transport_socket_match_criteria = 23;
 }