consul/proto-public/pbmesh/v2beta1/pbproxystate/cluster.proto

// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: MPL-2.0

syntax = "proto3";

package hashicorp.consul.mesh.v2beta1.pbproxystate;

import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "pbmesh/v2beta1/pbproxystate/header_mutations.proto";
import "pbmesh/v2beta1/pbproxystate/transport_socket.proto";

message Cluster {
  // name is the name of the cluster.
  string name = 1;
  // group is either a failover group or endpoint group. If this cluster needs to failover to other clusters, use the failover group. If this cluster routes directly to endpoints, use the endpoint group.
  oneof group {
    FailoverGroup failover_group = 2;
    EndpointGroup endpoint_group = 3;
  }
  // escape_hatch_cluster_json configures a user configured escape hatch cluster.
  string escape_hatch_cluster_json = 4;
  // alt_stat_name is the name used for observability in place of cluster name if provided.
  string alt_stat_name = 5;
  // protocol is the local path protocol or the service protocol.
  string protocol = 6;
}

message FailoverGroup {
  // endpoint_groups is an ordered list of which groups to failover to.
  repeated EndpointGroup endpoint_groups = 1;
  FailoverGroupConfig config = 2;
}

message FailoverGroupConfig {
  bool use_alt_stat_name = 1;
  // +kubebuilder:validation:Type=string
  google.protobuf.Duration connect_timeout = 2;
}

message EndpointGroup {
  // name is used to name the cluster created. This is only required when used inside of a FailoverGroup.
  string name = 5;
  oneof group {
    // dynamic endpoint group is used to reach mesh destinations that are dynamically configured from Consul's catalog.
    DynamicEndpointGroup dynamic = 1;
    // static endpoint group is used to reach local app ports.
    StaticEndpointGroup static = 2;
    // dns is used to reach mesh and non-mesh destinations using a hostname.
    DNSEndpointGroup dns = 3;
    // passthrough is used to reach destinations that don't have endpoints saved in Consul.
    PassthroughEndpointGroup passthrough = 4;
  }
}

message DynamicEndpointGroup {
  // config configures how to connect to the endpoints.
  DynamicEndpointGroupConfig config = 1;
  // outbound_tls will configure what TLS information to use when connecting to an upstream.
  TransportSocket outbound_tls = 2;
}

message PassthroughEndpointGroup {
  // config configures how to connect to the endpoints.
  PassthroughEndpointGroupConfig config = 1;
  // outbound_tls will configure what TLS information to use when connecting to an upstream.
  TransportSocket outbound_tls = 2;
}

message DNSEndpointGroup {
  // config configures how to connect to the endpoints.
  DNSEndpointGroupConfig config = 1;
  // outbound_tls will configure what TLS information to use when connecting to an upstream.
  TransportSocket outbound_tls = 2;
}

// StaticEndpointGroup is used to reach local app ports.
message StaticEndpointGroup {
  // config configures how to connect to the endpoints.
  StaticEndpointGroupConfig config = 1;
}

message DestinationCluster {
  // name is the name of the cluster. This will be used to look up a cluster in the clusters map.
  string name = 1;
}

message L4WeightedClusterGroup {
  // clusters to route to by weight.
  repeated L4WeightedDestinationCluster clusters = 1;
}

message L7WeightedClusterGroup {
  // clusters to route to by weight.
  repeated L7WeightedDestinationCluster clusters = 1;
}

message L4WeightedDestinationCluster {
  // name is the name of the cluster. This will be used to look up a cluster in the clusters map.
  string name = 1;
  google.protobuf.UInt32Value weight = 2;
}

message L7WeightedDestinationCluster {
  // name is the name of the cluster. This will be used to look up a cluster in the clusters map.
  string name = 1;
  google.protobuf.UInt32Value weight = 2;
  repeated HeaderMutation header_mutations = 3;
}

message DynamicEndpointGroupConfig {
  // +kubebuilder:validation:Format=duration
  google.protobuf.Duration connect_timeout = 1;
  bool disable_panic_threshold = 2;
  oneof lb_policy {
    LBPolicyLeastRequest least_request = 3;
    LBPolicyRoundRobin round_robin = 4;
    LBPolicyRandom random = 5;
    LBPolicyRingHash ring_hash = 6;
    LBPolicyMaglev maglev = 7;
  }
  CircuitBreakers circuit_breakers = 8;
  OutlierDetection outlier_detection = 9;
  UpstreamConnectionOptions upstream_connection_options = 10;
  bool use_alt_stat_name = 11;
}

message LBPolicyLeastRequest {
  google.protobuf.UInt32Value choice_count = 1;
}
message LBPolicyRoundRobin {}

message LBPolicyRandom {}

message LBPolicyRingHash {
  google.protobuf.UInt64Value minimum_ring_size = 1;
  google.protobuf.UInt64Value maximum_ring_size = 2;
}

message LBPolicyMaglev {}

message CircuitBreakers {
  UpstreamLimits upstream_limits = 1;
}

message UpstreamLimits {
  google.protobuf.UInt32Value max_connections = 1;
  google.protobuf.UInt32Value max_pending_requests = 2;
  google.protobuf.UInt32Value max_concurrent_requests = 3;
}

message OutlierDetection {
  // +kubebuilder:validation:Format=duration
  google.protobuf.Duration interval = 1;
  google.protobuf.UInt32Value consecutive_5xx = 2;
  google.protobuf.UInt32Value enforcing_consecutive_5xx = 3;
  google.protobuf.UInt32Value max_ejection_percent = 4;
  // +kubebuilder:validation:Format=duration
  google.protobuf.Duration base_ejection_time = 5;
}

message UpstreamConnectionOptions {
  google.protobuf.UInt32Value tcp_keepalive_time = 1;
  google.protobuf.UInt32Value tcp_keepalive_interval = 2;
  google.protobuf.UInt32Value tcp_keepalive_probes = 3;
}

message PassthroughEndpointGroupConfig {
  // +kubebuilder:validation:Format=duration
  google.protobuf.Duration connect_timeout = 1;
}

message DNSEndpointGroupConfig {
  // +kubebuilder:validation:Format=duration
  google.protobuf.Duration connect_timeout = 1;
  bool disable_panic_threshold = 2;
  DiscoveryType discovery_type = 3;
  CircuitBreakers circuit_breakers = 4;
  OutlierDetection outlier_detection = 5;
  UpstreamConnectionOptions upstream_connection_options = 6;
  bool use_alt_stat_name = 7;
}

// +kubebuilder:validation:Enum=DISCOVERY_TYPE_LOGICAL;DISCOVERY_TYPE_STRICT
// +kubebuilder:validation:Type=string
enum DiscoveryType {
  // buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX
  DISCOVERY_TYPE_LOGICAL = 0;
  DISCOVERY_TYPE_STRICT = 1;
}

message StaticEndpointGroupConfig {
  // +kubebuilder:validation:Format=duration
  google.protobuf.Duration connect_timeout = 1;
  CircuitBreakers circuit_breakers = 2;
}