data-plane-api/envoy/api/v2/cds.proto

syntax = "proto3";

package envoy.api.v2;

import "envoy/api/v2/address.proto";
import "envoy/api/v2/auth/cert.proto";
import "envoy/api/v2/base.proto";
import "envoy/api/v2/config_source.proto";
import "envoy/api/v2/discovery.proto";
import "envoy/api/v2/health_check.proto";
import "envoy/api/v2/protocol.proto";
import "envoy/api/v2/cluster/circuit_breaker.proto";
import "envoy/api/v2/cluster/outlier_detection.proto";

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

import "validate/validate.proto";
import "gogoproto/gogo.proto";

// 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: "*"
    };
  }
}

// [#protodoc-title: Clusters]

message Cluster {
  // Supplies the name of the cluster which must be unique across all clusters.
  // The cluster name is used when emitting
  // :ref:`statistics <config_cluster_manager_cluster_stats>`.
  // Any ``:`` in the cluster name will be converted to ``_`` when emitting statistics.
  // By default, the maximum length of a cluster name is limited to 60
  // characters. This limit can be increased by setting the
  // :option:`--max-obj-name-len` command line argument to the desired value.
  string name = 1 [(validate.rules).string.min_bytes = 1];

  // Refer to :ref:`service discovery type <arch_overview_service_discovery_types>`
  // for an explanation on each type.
  enum DiscoveryType {
    // Refer to the :ref:`static discovery type<arch_overview_service_discovery_types_static>`
    // for an explanation.
    STATIC = 0;

    // Refer to the :ref:`strict DNS discovery
    // type<arch_overview_service_discovery_types_strict_dns>`
    // for an explanation.
    STRICT_DNS = 1;

    // Refer to the :ref:`logical DNS discovery
    // type<arch_overview_service_discovery_types_logical_dns>`
    // for an explanation.
    LOGICAL_DNS = 2;

    // Refer to the :ref:`service discovery type<arch_overview_service_discovery_types_sds>`
    // for an explanation.
    EDS = 3;

    // Refer to the :ref:`original destination discovery
    // type<arch_overview_service_discovery_types_original_destination>`
    // for an explanation.
    ORIGINAL_DST = 4;
  }
  // The :ref:`service discovery type <arch_overview_service_discovery_types>`
  // to use for resolving the cluster.
  DiscoveryType type = 2 [(validate.rules).enum.defined_only = true];

  // Only valid when discovery type is EDS.
  message EdsClusterConfig {
    // Configuration for the source of EDS updates for this Cluster.
    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 arbitrary
    // length.
    string service_name = 2;
  }
  // Configuration to use for EDS updates for the Cluster.
  EdsClusterConfig eds_cluster_config = 3;

  // The timeout for new network connections to hosts in the cluster.
  google.protobuf.Duration connect_timeout = 4 [
    (validate.rules).duration.gt = {},
    (gogoproto.stdduration) = true,
    (gogoproto.nullable) = false
  ];

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

  // Refer to :ref:`load balancer type <arch_overview_load_balancing_types>` architecture
  // overview section for information on each type.
  enum LbPolicy {

    // Refer to the :ref:`round robin load balancing
    // policy<arch_overview_load_balancing_types_round_robin>`
    // for an explanation.
    ROUND_ROBIN = 0;

    // Refer to the :ref:`least request load balancing
    // policy<arch_overview_load_balancing_types_least_request>`
    // for an explanation.
    LEAST_REQUEST = 1;

    // Refer to the :ref:`ring hash load balancing
    // policy<arch_overview_load_balancing_types_ring_hash>`
    // for an explanation.
    RING_HASH = 2;

    // Refer to the :ref:`random load balancing
    // policy<arch_overview_load_balancing_types_random>`
    // for an explanation.
    RANDOM = 3;

    // Refer to the :ref:`original destination load balancing
    // policy<arch_overview_load_balancing_types_original_destination>`
    // for an explanation.
    ORIGINAL_DST_LB = 4;
  }
  // The :ref:`load balancer type <arch_overview_load_balancing_types>` to use
  // when picking a host in the cluster.
  LbPolicy lb_policy = 6 [(validate.rules).enum.defined_only = true];

  // If the service discovery type is
  // :ref:`STATIC<envoy_api_enum_value_Cluster.DiscoveryType.STATIC>`,
  // :ref:`STRICT_DNS<envoy_api_enum_value_Cluster.DiscoveryType.STRICT_DNS>`
  // or :ref:`LOGICAL_DNS<envoy_api_enum_value_Cluster.DiscoveryType.LOGICAL_DNS>`,
  // then hosts is required.
  repeated Address hosts = 7;

  // Optional :ref:`active health checking <arch_overview_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 :ref:`circuit breaking <arch_overview_circuit_break>` for the cluster.
  envoy.api.v2.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.
  //
  // .. attention::
  //
  //   Server certificate verification is not enabled by default. Configure
  //   :ref:`trusted_ca<envoy_api_field_auth.CertificateValidationContext.trusted_ca>` to enable
  //   verification.
  auth.UpstreamTlsContext tls_context = 11;

  reserved 12;

  // Additional options when handling HTTP1 requests.
  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_protocol_options` must be specified. As an aside this allows HTTP/2
  // connections to happen over plain text.
  Http2ProtocolOptions http2_protocol_options = 14;

  reserved 15;

  // If the DNS refresh rate is specified and the cluster type is either
  // :ref:`STRICT_DNS<envoy_api_enum_value_Cluster.DiscoveryType.STRICT_DNS>`,
  // or :ref:`LOGICAL_DNS<envoy_api_enum_value_Cluster.DiscoveryType.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
  // :ref:`STRICT_DNS<envoy_api_enum_value_Cluster.DiscoveryType.STRICT_DNS>`
  // and :ref:`LOGICAL_DNS<envoy_api_enum_value_Cluster.DiscoveryType.LOGICAL_DNS>`
  // this setting is ignored.
  google.protobuf.Duration dns_refresh_rate = 16
      [(validate.rules).duration.gt = {}, (gogoproto.stdduration) = true];

  // 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
  // :ref:`STRICT_DNS<envoy_api_enum_value_Cluster.DiscoveryType.STRICT_DNS>` and
  // :ref:`LOGICAL_DNS<envoy_api_enum_value_Cluster.DiscoveryType.LOGICAL_DNS>`,
  // this setting is
  // ignored.
  enum DnsLookupFamily {
    AUTO = 0;
    V4_ONLY = 1;
    V6_ONLY = 2;
  }

  // The DNS IP address resolution policy. If this setting is not specified, the
  // value defaults to
  // :ref:`AUTO<envoy_api_enum_value_Cluster.DnsLookupFamily.AUTO>`.
  DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum.defined_only = true];

  // If DNS resolvers are specified and the cluster type is either
  // :ref:`STRICT_DNS<envoy_api_enum_value_Cluster.DiscoveryType.STRICT_DNS>`,
  // or :ref:`LOGICAL_DNS<envoy_api_enum_value_Cluster.DiscoveryType.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
  // :ref:`STRICT_DNS<envoy_api_enum_value_Cluster.DiscoveryType.STRICT_DNS>`
  // and :ref:`LOGICAL_DNS<envoy_api_enum_value_Cluster.DiscoveryType.LOGICAL_DNS>`
  // this setting is ignored.
  repeated Address dns_resolvers = 18;

  // If specified, outlier detection will be enabled for this upstream cluster.
  // Each of the configuration values can be overridden via
  // :ref:`runtime values <config_cluster_manager_cluster_runtime_outlier_detection>`.
  envoy.api.v2.cluster.OutlierDetection outlier_detection = 19;

  // The interval for removing stale hosts from a cluster type
  // :ref:`ORIGINAL_DST<envoy_api_enum_value_Cluster.DiscoveryType.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
  // :ref:`ORIGINAL_DST<envoy_api_enum_value_Cluster.DiscoveryType.ORIGINAL_DST>`
  // this setting is ignored.
  google.protobuf.Duration cleanup_interval = 20
      [(validate.rules).duration.gt = {}, (gogoproto.stdduration) = true];

  // 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 {

    // 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;
    }

    // The behavior used when no endpoint subset matches the selected route's
    // metadata. The value defaults to
    // :ref:`NO_FALLBACK<envoy_api_enum_value_Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.NO_FALLBACK>`.
    LbSubsetFallbackPolicy fallback_policy = 1 [(validate.rules).enum.defined_only = true];

    // Specifies the default subset of endpoints used during fallback if
    // fallback_policy is
    // :ref:`DEFAULT_SUBSET<envoy_api_enum_value_Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.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
    // :ref:`NO_FALLBACK<envoy_api_enum_value_Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.NO_FALLBACK>`.
    google.protobuf.Struct default_subset = 2;

    // Specifications for subsets.
    message LbSubsetSelector {
      // List of keys to match with the weighted cluster metadata.
      repeated string keys = 1;
    }

    // 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.
    repeated LbSubsetSelector subset_selectors = 3;
  }

  // Configuration for load balancing subsetting.
  LbSubsetConfig lb_subset_config = 22;

  // Specific configuration for the :ref:`RingHash<arch_overview_load_balancing_types_ring_hash>`
  // load balancing policy.
  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 <https://github.com/Cyan4973/xxHash>`_
      // by default. This field exists for
      // migration purposes and will eventually be deprecated. Set it to false
      // to use `xxHash <https://github.com/Cyan4973/xxHash>`_ now.
      google.protobuf.BoolValue use_std_hash = 1;
    }
    // Deprecated settings from v1 config.
    DeprecatedV1 deprecated_v1 = 2 [deprecated = true];
  }

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

  // See :ref:`base.TransportSocket<envoy_api_msg_TransportSocket>` description.
  TransportSocket transport_socket = 24;

  // The Metadata field can be used to provide additional information about the
  // cluster. It can be used for stats, logging, and varying filter behavior.
  // Fields should use reverse DNS notation to denote which entity within Envoy
  // will need the information. For instance, if the metadata is intended for
  // the Router filter, the filter name should be specified as *envoy.router*.
  Metadata metadata = 25;

  enum ClusterProtocolSelection {
    // Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2).
    // If :ref:`http2_protocol_options <envoy_api_field_Cluster.http2_protocol_options>` are
    // present, HTTP2 will be used, otherwise HTTP1.1 will be used.
    USE_CONFIGURED_PROTOCOL = 0;
    // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection.
    USE_DOWNSTREAM_PROTOCOL = 1;
  }
  ClusterProtocolSelection protocol_selection = 26;
}

// 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;
}