consul/proto-public/pbmesh/v1alpha1/cluster.proto

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

syntax = "proto3";

package hashicorp.consul.mesh.v1alpha1;

import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "pbmesh/v1alpha1/header_mutations.proto";
import "pbmesh/v1alpha1/transport_socket.proto";
import "pbmesh/v1alpha1/upstreams_configuration.proto";

message Cluster {
  // 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 = 1;
    EndpointGroup endpoint_group = 2;
  }
  // escape_hatch_cluster_json configures a user configured escape hatch cluster.
  string escape_hatch_cluster_json = 3;
}

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

message FailoverGroupConfig {
  bool use_alt_stat_name = 1;
  google.protobuf.Duration connect_timeout = 2;
}

message EndpointGroup {
  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 {
  // name will be the name of the Envoy cluster created by this endpoint group.
  string name = 1;
  // config configures how to connect to the endpoints.
  DynamicEndpointGroupConfig config = 2;
  // outbound_tls will configure what TLS information to use when connecting to an upstream.
  TransportSocket outbound_tls = 3;
}

message PassthroughEndpointGroup {
  // name will be the name of the Envoy cluster created by this endpoint group.
  string name = 1;
  // config configures how to connect to the endpoints.
  PassthroughEndpointGroupConfig config = 2;
  // outbound_tls will configure what TLS information to use when connecting to an upstream.
  TransportSocket outbound_tls = 3;
}

message DNSEndpointGroup {
  // name will be the name of the Envoy cluster created by this endpoint group.
  string name = 1;
  // config configures how to connect to the endpoints.
  DNSEndpointGroupConfig config = 2;
  // outbound_tls will configure what TLS information to use when connecting to an upstream.
  TransportSocket outbound_tls = 3;
}

// StaticEndpointGroup is used to reach local app ports.
message StaticEndpointGroup {
  // name will be the name of the Envoy cluster created by this endpoint group.
  string name = 1;
  // config configures how to connect to the endpoints.
  StaticEndpointGroupConfig config = 2;
}

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 {
  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 OutlierDetection {
  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;
  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 {
  google.protobuf.Duration connect_timeout = 1;
}

message DNSEndpointGroupConfig {
  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;
}

enum DiscoveryType {
  // buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX
  DISCOVERY_TYPE_LOGICAL = 0;
  DISCOVERY_TYPE_STRICT = 1;
}

message StaticEndpointGroupConfig {
  google.protobuf.Duration connect_timeout = 1;
  CircuitBreakers circuit_breakers = 2;
}