envoy.config.core.v3.health_check.proto Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
There is a newer version: 1.0.47
syntax = "proto3";

package envoy.config.core.v3;

import "envoy/config/core/v3/base.proto";
import "envoy/type/matcher/v3/string.proto";
import "envoy/type/v3/http.proto";
import "envoy/type/v3/range.proto";

import "google/protobuf/any.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

import "udpa/annotations/versioning.proto";

import "envoy/annotations/deprecation.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.config.core.v3";
option java_outer_classname = "HealthCheckProto";
option java_multiple_files = true;

// [#protodoc-title: Health check]
// * Health checking :ref:`architecture overview `.
// * If health checking is configured for a cluster, additional statistics are emitted. They are
//   documented :ref:`here `.

// Endpoint health status.
enum HealthStatus {
  // The health status is not known. This is interpreted by Envoy as *HEALTHY*.
  UNKNOWN = 0;

  // Healthy.
  HEALTHY = 1;

  // Unhealthy.
  UNHEALTHY = 2;

  // Connection draining in progress. E.g.,
  // ``_
  // or
  // ``_.
  // This is interpreted by Envoy as *UNHEALTHY*.
  DRAINING = 3;

  // Health check timed out. This is part of HDS and is interpreted by Envoy as
  // *UNHEALTHY*.
  TIMEOUT = 4;

  // Degraded.
  DEGRADED = 5;
}

// [#next-free-field: 22]
message HealthCheck {
  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HealthCheck";

  // Describes the encoding of the payload bytes in the payload.
  message Payload {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.HealthCheck.Payload";

    oneof payload {
      option (validate.required) = true;

      // Hex encoded payload. E.g., "000000FF".
      string text = 1 [(validate.rules).string = {min_bytes: 1}];

      // [#not-implemented-hide:] Binary payload.
      bytes binary = 2;
    }
  }

  // [#next-free-field: 12]
  message HttpHealthCheck {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.HealthCheck.HttpHealthCheck";

    reserved 5, 7;

    reserved "service_name", "use_http2";

    // The value of the host header in the HTTP health check request. If
    // left empty (default value), the name of the cluster this health check is associated
    // with will be used.
    string host = 1;

    // Specifies the HTTP path that will be requested during health checking. For example
    // */healthcheck*.
    string path = 2 [(validate.rules).string = {min_bytes: 1}];

    // [#not-implemented-hide:] HTTP specific payload.
    Payload send = 3;

    // [#not-implemented-hide:] HTTP specific response.
    Payload receive = 4;

    // Specifies a list of HTTP headers that should be added to each request that is sent to the
    // health checked cluster. For more information, including details on header value syntax, see
    // the documentation on :ref:`custom request headers
    // `.
    repeated HeaderValueOption request_headers_to_add = 6
        [(validate.rules).repeated = {max_items: 1000}];

    // Specifies a list of HTTP headers that should be removed from each request that is sent to the
    // health checked cluster.
    repeated string request_headers_to_remove = 8;

    // Specifies a list of HTTP response statuses considered healthy. If provided, replaces default
    // 200-only policy - 200 must be included explicitly as needed. Ranges follow half-open
    // semantics of :ref:`Int64Range `. The start and end of each
    // range are required. Only statuses in the range [100, 600) are allowed.
    repeated type.v3.Int64Range expected_statuses = 9;

    // Use specified application protocol for health checks.
    type.v3.CodecClientType codec_client_type = 10 [(validate.rules).enum = {defined_only: true}];

    // An optional service name parameter which is used to validate the identity of
    // the health checked cluster using a :ref:`StringMatcher
    // `. See the :ref:`architecture overview
    // ` for more information.
    type.matcher.v3.StringMatcher service_name_matcher = 11;
  }

  message TcpHealthCheck {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.HealthCheck.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
    // necessarily contiguous.
    repeated Payload receive = 2;
  }

  message RedisHealthCheck {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.HealthCheck.RedisHealthCheck";

    // If set, optionally perform ``EXISTS `` instead of ``PING``. A return value
    // from Redis of 0 (does not exist) is considered a passing healthcheck. A return value other
    // than 0 is considered a failure. This allows the user to mark a Redis instance for maintenance
    // by setting the specified key to any value and waiting for traffic to drain.
    string key = 1;
  }

  // `grpc.health.v1.Health
  // `_-based
  // healthcheck. See `gRPC doc `_
  // for details.
  message GrpcHealthCheck {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.HealthCheck.GrpcHealthCheck";

    // An optional service name parameter which will be sent to gRPC service in
    // `grpc.health.v1.HealthCheckRequest
    // `_.
    // message. See `gRPC health-checking overview
    // `_ for more information.
    string service_name = 1;

    // The value of the :authority header in the gRPC health check request. If
    // left empty (default value), the name of the cluster this health check is associated
    // with will be used.
    string authority = 2;
  }

  // Custom health check.
  message CustomHealthCheck {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.HealthCheck.CustomHealthCheck";

    reserved 2;

    reserved "config";

    // The registered name of the custom health checker.
    string name = 1 [(validate.rules).string = {min_bytes: 1}];

    // A custom health checker specific configuration which depends on the custom health checker
    // being instantiated. See :api:`envoy/config/health_checker` for reference.
    oneof config_type {
      google.protobuf.Any typed_config = 3;
    }
  }

  // Health checks occur over the transport socket specified for the cluster. This implies that if a
  // cluster is using a TLS-enabled transport socket, the health check will also occur over TLS.
  //
  // This allows overriding the cluster TLS settings, just for health check connections.
  message TlsOptions {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.HealthCheck.TlsOptions";

    // Specifies the ALPN protocols for health check connections. This is useful if the
    // corresponding upstream is using ALPN-based :ref:`FilterChainMatch
    // ` along with different protocols for health checks
    // versus data connections. If empty, no ALPN protocols will be set on health check connections.
    repeated string alpn_protocols = 1;
  }

  reserved 10;

  // 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 [(validate.rules).duration = {
    required: true
    gt {}
  }];

  // The interval between health checks.
  google.protobuf.Duration interval = 2 [(validate.rules).duration = {
    required: true
    gt {}
  }];

  // An optional jitter amount in milliseconds. If specified, Envoy will start health
  // checking after for a random time in ms between 0 and initial_jitter. This only
  // applies to the first health check.
  google.protobuf.Duration initial_jitter = 20;

  // An optional jitter amount in milliseconds. If specified, during every
  // interval Envoy will add interval_jitter to the wait time.
  google.protobuf.Duration interval_jitter = 3;

  // An optional jitter amount as a percentage of interval_ms. If specified,
  // during every interval Envoy will add interval_ms *
  // interval_jitter_percent / 100 to the wait time.
  //
  // If interval_jitter_ms and interval_jitter_percent are both set, both of
  // them will be used to increase the wait time.
  uint32 interval_jitter_percent = 18;

  // 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.
  google.protobuf.UInt32Value unhealthy_threshold = 4 [(validate.rules).message = {required: true}];

  // 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 [(validate.rules).message = {required: true}];

  // [#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;

  oneof health_checker {
    option (validate.required) = true;

    // HTTP health check.
    HttpHealthCheck http_health_check = 8;

    // TCP health check.
    TcpHealthCheck tcp_health_check = 9;

    // gRPC health check.
    GrpcHealthCheck grpc_health_check = 11;

    // Custom health check.
    CustomHealthCheck custom_health_check = 13;
  }

  // The "no traffic interval" is a special health check interval that is used when a cluster has
  // never had traffic routed to it. This lower interval allows cluster information to be kept up to
  // date, without sending a potentially large amount of active health checking traffic for no
  // reason. Once a cluster has been used for traffic routing, Envoy will shift back to using the
  // standard health check interval that is defined. Note that this interval takes precedence over
  // any other.
  //
  // The default value for "no traffic interval" is 60 seconds.
  google.protobuf.Duration no_traffic_interval = 12 [(validate.rules).duration = {gt {}}];

  // The "unhealthy interval" is a health check interval that is used for hosts that are marked as
  // unhealthy. As soon as the host is marked as healthy, Envoy will shift back to using the
  // standard health check interval that is defined.
  //
  // The default value for "unhealthy interval" is the same as "interval".
  google.protobuf.Duration unhealthy_interval = 14 [(validate.rules).duration = {gt {}}];

  // The "unhealthy edge interval" is a special health check interval that is used for the first
  // health check right after a host is marked as unhealthy. For subsequent health checks
  // Envoy will shift back to using either "unhealthy interval" if present or the standard health
  // check interval that is defined.
  //
  // The default value for "unhealthy edge interval" is the same as "unhealthy interval".
  google.protobuf.Duration unhealthy_edge_interval = 15 [(validate.rules).duration = {gt {}}];

  // The "healthy edge interval" is a special health check interval that is used for the first
  // health check right after a host is marked as healthy. For subsequent health checks
  // Envoy will shift back to using the standard health check interval that is defined.
  //
  // The default value for "healthy edge interval" is the same as the default interval.
  google.protobuf.Duration healthy_edge_interval = 16 [(validate.rules).duration = {gt {}}];

  // Specifies the path to the :ref:`health check event log `.
  // If empty, no event log will be written.
  string event_log_path = 17;

  // If set to true, health check failure events will always be logged. If set to false, only the
  // initial health check failure event will be logged.
  // The default value is false.
  bool always_log_health_check_failures = 19;

  // This allows overriding the cluster TLS settings, just for health check connections.
  TlsOptions tls_options = 21;
}