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

syntax = "proto3";

package envoy.api.v2.endpoint;
option go_package = "endpoint";

import "envoy/api/v2/core/address.proto";
import "envoy/api/v2/core/base.proto";
import "envoy/api/v2/core/health_check.proto";

import "google/protobuf/wrappers.proto";

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

option (gogoproto.equal_all) = true;

// [#protodoc-title: Endpoints]

// Upstream host identifier.
message Endpoint {
  // The upstream host address.
  core.Address address = 1;

  // [#not-implemented-hide:] The optional health check configuration.
  message HealthCheckConfig {
    // Optional alternative health check port value.
    //
    // By default the health check address port of an upstream host is the same
    // as the host's serving address port. This provides an alternative health
    // check port. Setting this with a non-zero value allows an upstream host
    // to have different health check address port.
    uint32 port_value = 1;
  }

  // [#not-implemented-hide:] The optional health check configuration is used as
  // configuration for the health checker to contact the health checked host.
  //
  // .. attention::
  //
  //   This takes into effect only for upstream clusters with
  //   :ref:`active health checking <arch_overview_health_checking>` enabled.
  HealthCheckConfig health_check_config = 2;
}

// An Endpoint that Envoy can route traffic to.
message LbEndpoint {
  // Upstream host identifier
  Endpoint endpoint = 1;

  // Optional health status when known and supplied by EDS server.
  core.HealthStatus health_status = 2;

  // The endpoint metadata specifies values that may be used by the load
  // balancer to select endpoints in a cluster for a given request. The filter
  // name should be specified as *envoy.lb*. An example boolean key-value pair
  // is *canary*, providing the optional canary status of the upstream host.
  // This may be matched against in a route's ForwardAction metadata_match field
  // to subset the endpoints considered in cluster load balancing.
  core.Metadata metadata = 3;

  // The optional load balancing weight of the upstream host, in the range 1 -
  // 128. Envoy uses the load balancing weight in some of the built in load
  // balancers. The load balancing weight for an endpoint is divided by the sum
  // of the weights of all endpoints in the endpoint's locality to produce a
  // percentage of traffic for the endpoint. This percentage is then further
  // weighted by the endpoint's locality's load balancing weight from
  // LocalityLbEndpoints. If unspecified, each host is presumed to have equal
  // weight in a locality.
  //
  // .. attention::
  //
  //   The limit of 128 is somewhat arbitrary, but is applied due to performance
  //   concerns with the current implementation and can be removed when
  //   `this issue <https://github.com/envoyproxy/envoy/issues/1285>`_ is fixed.
  google.protobuf.UInt32Value load_balancing_weight = 4
      [(validate.rules).uint32 = {gte: 1, lte: 128}];
}

// A group of endpoints belonging to a Locality.
// One can have multiple LocalityLbEndpoints for a locality, but this is
// generally only done if the different groups need to have different load
// balancing weights or different priorities.
message LocalityLbEndpoints {
  // Identifies location of where the upstream hosts run.
  core.Locality locality = 1;

  // The group of endpoints belonging to the locality specified.
  repeated LbEndpoint lb_endpoints = 2 [(gogoproto.nullable) = false];

  // Optional: Per priority/region/zone/sub_zone weight - range 1-128. The load
  // balancing weight for a locality is divided by the sum of the weights of all
  // localities  at the same priority level to produce the effective percentage
  // of traffic for the locality.
  //
  // Locality weights are only considered when :ref:`locality weighted load
  // balancing <arch_overview_load_balancing_locality_weighted_lb>` is
  // configured. These weights are ignored otherwise. If no weights are
  // specificed when locality weighted load balancing is enabled, the cluster is
  // assumed to have a weight of 1.
  //
  // .. attention::
  //
  //   The limit of 128 is somewhat arbitrary, but is applied due to performance
  //   concerns with the current implementation and can be removed when
  //   `this issue <https://github.com/envoyproxy/envoy/issues/1285>`_ is fixed.
  google.protobuf.UInt32Value load_balancing_weight = 3
      [(validate.rules).uint32 = {gte: 1, lte: 128}];

  // Optional: the priority for this LocalityLbEndpoints. If unspecified this will
  // default to the highest priority (0).
  //
  // Under usual circumstances, Envoy will only select endpoints for the highest
  // priority (0). In the event all endpoints for a particular priority are
  // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the
  // next highest priority group.
  //
  // Priorities should range from 0 (highest) to N (lowest) without skipping.
  uint32 priority = 5;
}