data-plane-api/api/cds.proto

syntax = "proto3";

package envoy.api.v2;

import "api/address.proto";
import "api/base.proto";
import "api/discovery.proto";
import "api/health_check.proto";
import "api/protocol.proto";
import "api/sds.proto";

import "google/api/annotations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

// [#protodoc-title: Clusters and CDS]

// Return list of all clusters this proxy will load balance to.
service ClusterDiscoveryService {
  rpc StreamClusters(stream DiscoveryRequest)
      returns (stream DiscoveryResponse) {
  }

  rpc FetchClusters(DiscoveryRequest)
      returns (DiscoveryResponse) {
    option (google.api.http) = {
      post: "/v2/discovery:clusters"
      body: "*"
    };
  }
}

// An extensible structure containing the address Envoy should bind to when establishing upstream
// connections.
message UpstreamBindConfig {
  // The address Envoy should bind to when establishing upstream connections.
  Address source_address = 1;
}

// Circuit breaking settings can be specified individually for each defined
// priority.
message CircuitBreakers {
  message Thresholds {
    RoutingPriority priority = 1;
    // The maximum number of connections that Envoy will make to the upstream
    // cluster. If not specified, the default is 1024. See the circuit
    // breaking overview for more information.
    google.protobuf.UInt32Value max_connections = 2;
    // The maximum number of pending requests that Envoy will allow to the
    // upstream cluster. If not specified, the default is 1024. See the circuit
    // breaking overview for more information.
    google.protobuf.UInt32Value max_pending_requests = 3;
    // The maximum number of parallel requests that Envoy will make to the
    // upstream cluster. If not specified, the default is 1024. See the circuit
    // breaking overview for more information.
    google.protobuf.UInt32Value max_requests = 4;
    // The maximum number of parallel retries that Envoy will allow to the
    // upstream cluster. If not specified, the default is 3. See the circuit
    // breaking overview for more information.
    google.protobuf.UInt32Value max_retries = 5;
  }
  repeated Thresholds thresholds = 1;
}

message Cluster {
  // Supplies the name of the cluster which must be unique across all clusters.
  // Any : in the cluster name will be converted to _ when emitting statistics.
  // TODO(htuch): cross-link to
  // https://www.envoyproxy.io/envoy/operations/cli#cmdoption-max-obj-name-len.
  string name = 1;

  // The service discovery type to use for resolving the cluster.
  enum DiscoveryType {
    STATIC = 0;
    STRICT_DNS = 1;
    LOGICAL_DNS = 2;
    EDS = 3;
    ORIGINAL_DST = 4;
  }
  DiscoveryType type = 2;

  // Only valid when discovery type is EDS.
  message EdsClusterConfig {
    ConfigSource eds_config = 1;
    // Optional alternative to cluster name to present to EDS. This does not
    // have the same restrictions as cluster name, i.e. it may be arbritary
    // length.
    string service_name = 2;
  }
  EdsClusterConfig eds_cluster_config = 3;

  // The timeout for new network connections to hosts in the cluster.
  google.protobuf.Duration connect_timeout = 4;
  // Soft limit on size of the cluster’s connections read and write buffers. If
  // unspecified, an implementation defined default is applied (1MiB).
  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;

  // The load balancer type to use when picking a host in the cluster.
  enum LbPolicy {
    ROUND_ROBIN = 0;
    LEAST_REQUEST = 1;
    RING_HASH = 2;
    RANDOM = 3;
    ORIGINAL_DST_LB = 4;
  }
  LbPolicy lb_policy = 6;

  // If the service discovery type is STATIC, STRICT_DNS or LOGICAL_DNS, then
  // hosts is required.
  repeated Address hosts = 7;

  // Optional active health checking configuration for the cluster. If no
  // configuration is specified no health checking will be done and all cluster
  // members will be considered healthy at all times.
  repeated HealthCheck health_checks = 8;

  // Optional maximum requests for a single upstream connection. This parameter
  // is respected by both the HTTP/1.1 and HTTP/2 connection pool
  // implementations. If not specified, there is no limit. Setting this
  // parameter to 1 will effectively disable keep alive.
  google.protobuf.UInt32Value max_requests_per_connection = 9;

  // Optional circuit breaking settings for the cluster.
  CircuitBreakers circuit_breakers = 10;

  // The TLS configuration for connections to the upstream cluster. If no TLS
  // configuration is specified, TLS will not be used for new connections.
  UpstreamTlsContext tls_context = 11;

  oneof protocol_options {
    // [#not-implemented-hide:]
    TcpProtocolOptions tcp_protocol_options = 12;
    Http1ProtocolOptions http_protocol_options = 13;
    // Even if default HTTP2 protocol options are desired, this field must be
    // set so that Envoy will assume that the upstream supports HTTP/2 when
    // making new HTTP connection pool connections. Currently, Envoy only
    // supports prior knowledge for upstream connections. Even if TLS is used
    // with ALPN, http2 must be specified. As an aside this allows HTTP/2
    // connections to happen over plain text.
    Http2ProtocolOptions http2_protocol_options = 14;
    // [#not-implemented-hide:]
    GrpcProtocolOptions grpc_protocol_options = 15;
  }

  // If the dns refresh rate is specified and the cluster type is either
  // STRICT_DNS, or LOGICAL_DNS, this value is used as the cluster’s dns refresh
  // rate. If this setting is not specified, the value defaults to 5000. For
  // cluster types other than STRICT_DNS and LOGICAL_DNS this setting is
  // ignored.
  google.protobuf.Duration dns_refresh_rate = 16;

  // The DNS IP address resolution policy. The options are V4_ONLY, V6_ONLY, and
  // AUTO. If this setting is not specified, the value defaults to V4_ONLY. When
  // V4_ONLY is selected, the DNS resolver will only perform a lookup for
  // addresses in the IPv4 family. If V6_ONLY is selected, the DNS resolver will
  // only perform a lookup for addresses in the IPv6 family. If AUTO is
  // specified, the DNS resolver will first perform a lookup for addresses in
  // the IPv6 family and fallback to a lookup for addresses in the IPv4 family.
  // For cluster types other than STRICT_DNS and LOGICAL_DNS, this setting is
  // ignored.
  enum DnsLookupFamily {
    AUTO = 0;
    V4_ONLY = 1;
    V6_ONLY = 2;
  }
  DnsLookupFamily dns_lookup_family = 17;

  // If DNS resolvers are specified and the cluster type is either STRICT_DNS,
  // or LOGICAL_DNS, this value is used to specify the cluster’s dns resolvers.
  // If this setting is not specified, the value defaults to the default
  // resolver, which uses /etc/resolv.conf for configuration. For cluster types
  // other than STRICT_DNS and LOGICAL_DNS this setting is ignored.
  repeated Address dns_resolvers = 18;

  // If specified, outlier detection will be enabled for this upstream cluster.
  message OutlierDetection {
    // The number of consecutive 5xx responses before a consecutive 5xx ejection
    // occurs. Defaults to 5.
    google.protobuf.UInt32Value consecutive_5xx = 1;
    // The time interval between ejection analysis sweeps. This can result in
    // both new ejections as well as hosts being returned to service. Defaults
    // to 10000ms or 10s.
    google.protobuf.Duration interval = 2;
    // The base time that a host is ejected for. The real time is equal to the
    // base time multiplied by the number of times the host has been ejected.
    // Defaults to 30000ms or 30s.
    google.protobuf.Duration base_ejection_time = 3;
    // The maximum % of an upstream cluster that can be ejected due to outlier
    // detection. Defaults to 10%.
    google.protobuf.UInt32Value max_ejection_percent = 4;
    // The % chance that a host will be actually ejected when an outlier status
    // is detected through consecutive 5xx. This setting can be used to disable
    // ejection or to ramp it up slowly. Defaults to 100.
    google.protobuf.UInt32Value enforcing_consecutive_5xx = 5;
    // The % chance that a host will be actually ejected when an outlier status
    // is detected through success rate statistics. This setting can be used to
    // disable ejection or to ramp it up slowly. Defaults to 100.
    google.protobuf.UInt32Value enforcing_success_rate = 6;
    // The number of hosts in a cluster that must have enough request volume to
    // detect success rate outliers. If the number of hosts is less than this
    // setting, outlier detection via success rate statistics is not performed
    // for any host in the cluster. Defaults to 5.
    google.protobuf.UInt32Value success_rate_minimum_hosts = 7;
    // The minimum number of total requests that must be collected in one
    // interval (as defined by the interval duration above) to include this host
    // in success rate based outlier detection. If the volume is lower than this
    // setting, outlier detection via success rate statistics is not performed
    // for that host. Defaults to 100.
    google.protobuf.UInt32Value success_rate_request_volume = 8;
    // This factor is used to determine the ejection threshold for success rate
    // outlier ejection. The ejection threshold is the difference between the
    // mean success rate, and the product of this factor and the standard
    // deviation of the mean success rate: mean - (stdev *
    // success_rate_stdev_factor). This factor is divided by a thousand to get a
    // double. That is, if the desired factor is 1.9, the runtime value should
    // be 1900. Defaults to 1900.
    google.protobuf.UInt32Value success_rate_stdev_factor = 9;
    // The number of consecutive gateway failures (502, 503, 504 status or
    // connection errors that are mapped to one of those status codes) before a
    // consecutive gateway failure ejection occurs. Defaults to 5.
    google.protobuf.UInt32Value consecutive_gateway_failure = 10;
    // The % chance that a host will be actually ejected when an outlier status
    // is detected through consecutive gateway failures. This setting can be
    // used to disable ejection or to ramp it up slowly. Defaults to 0.
    google.protobuf.UInt32Value enforcing_consecutive_gateway_failure = 11;
  }
  OutlierDetection outlier_detection = 19;

  // The interval for removing stale hosts from a cluster type
  // ORIGINAL_DST.  Hosts are considered stale if they have not been used
  // as upstream destinations during this interval.  New hosts are added
  // to original destination clusters on demand as new connections are
  // redirected to Envoy, causing the number of hosts in the cluster to
  // grow over time.  Hosts that are not stale (they are actively used as
  // destinations) are kept in the cluster, which allows connections to
  // them remain open, saving the latency that would otherwise be spent
  // on opening new connections.  If this setting is not specified, the
  // value defaults to 5000ms. For cluster types other than ORIGINAL_DST
  // this setting is ignored.
  google.protobuf.Duration cleanup_interval = 20;

  // Optional configuration used to bind newly established upstream connections.
  // This overrides any bind_config specified in the bootstrap proto.
  // If the addres and port are empty, no bind will be performed.
  BindConfig upstream_bind_config = 21;

  // Optionally divide the endpoints in this cluster into subsets defined by
  // endpoint metadata and selected by route and weighted cluster metadata.
  message LbSubsetConfig {
    // The behavior used when no endpoint subset matches the selected route's
    // metadata. The options are NO_FALLBACK, ANY_ENDPOINT, or DEFAULT_SUBSET.
    // The value defaults to NO_FALLBACK. If NO_FALLBACK is selected, a result
    // equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected,
    // any cluster endpoint may be returned (subject to policy, health checks,
    // etc). If DEFAULT_SUBSET is selected, load balancing is performed over the
    // endpoints matching the values from the default_subset field.
    enum LbSubsetFallbackPolicy {
      NO_FALLBACK = 0;
      ANY_ENDPOINT = 1;
      DEFAULT_SUBSET = 2;
    }
    LbSubsetFallbackPolicy fallback_policy = 1;

    // Specifies the default subset of endpoints used during fallback if
    // fallback_policy is DEFAULT_SUBSET. Each field in default_subset is
    // compared to the matching LbEndpoint.Metadata under the "envoy.lb"
    // namespace. It is valid for no hosts to match, in which case the behavior
    // is the same as a fallback_policy of NO_FALLBACK.
    google.protobuf.Struct default_subset = 2;

    // Specifications for subsets. For each entry, LbEndpoint.Metadata's
    // "envoy.lb" namespace is traversed and a subset is created for each unique
    // combination of key and value. For example:
    //
    // .. code-block:: json
    //
    //   { "subset_selectors": [
    //       { "keys": [ "version" ] },
    //       { "keys": [ "stage", "hardware_type" ] }
    //   ]}
    //
    // A subset is matched when the metadata from the selected route and
    // weighted cluster contains the same keys and values as the subset's
    // metadata. The same host may appear in multiple subsets.
    message LbSubsetSelector {
      repeated string keys = 1;
    }
    repeated LbSubsetSelector subset_selectors = 3;
  }
  LbSubsetConfig lb_subset_config = 22;

  message RingHashLbConfig {
    // Minimum hash ring size, i.e. total virtual nodes. A larger size
    // will provide better request distribution since each host in the
    // cluster will have more virtual nodes. Defaults to 1024. In the case
    // that total number of hosts is greater than the minimum, each host will
    // be allocated a single virtual node.
    google.protobuf.UInt64Value minimum_ring_size = 1;

    message DeprecatedV1 {
      // Defaults to true, meaning that std::hash is used to hash hosts onto
      // the ketama ring. std::hash can vary by platform. For this reason,
      // Envoy will eventually use xxHash by default. This field exists for
      // migration purposes and will eventually be deprecated. Set it to false
      // to use xxHash now.
      google.protobuf.BoolValue use_std_hash = 1;
    }
    DeprecatedV1 deprecated_v1 = 2;
  }

  // Optional configuration for the load balancing algorithm selected by
  // LbPolicy. Currently only RING_HASH has additional configuration options.
  // Specifying ring_hash_lb_config without setting the LbPolicy to RING_HASH
  // will generate an error at runtime.
  oneof lb_config {
    RingHashLbConfig ring_hash_lb_config = 23;
  }

  // See base.TransportSocket description.
  TransportSocket transport_socket = 24;
}