src/proto/grpc/testing/xds/v3/endpoint.proto

// Copyright 2020 The gRPC Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Local copy of Envoy xDS proto file, used for testing only.

syntax = "proto3";

package envoy.config.endpoint.v3;

import "src/proto/grpc/testing/xds/v3/address.proto";
import "src/proto/grpc/testing/xds/v3/base.proto";
import "src/proto/grpc/testing/xds/v3/percent.proto";

import "google/protobuf/wrappers.proto";

// [#protodoc-title: Endpoints]

// Endpoint health status.
enum HealthStatus {
  // The health status is not known. This is interpreted by Envoy as *HEALTHY*.
  UNKNOWN = 0;

  // Healthy.
  HEALTHY = 1;

  // Unhealthy.
  UNHEALTHY = 2;

  // Connection draining in progress. E.g.,
  // `<https://aws.amazon.com/blogs/aws/elb-connection-draining-remove-instances-from-service-with-care/>`_
  // or
  // `<https://cloud.google.com/compute/docs/load-balancing/enabling-connection-draining>`_.
  // This is interpreted by Envoy as *UNHEALTHY*.
  DRAINING = 3;

  // Health check timed out. This is part of HDS and is interpreted by Envoy as
  // *UNHEALTHY*.
  TIMEOUT = 4;

  // Degraded.
  DEGRADED = 5;
}

// Upstream host identifier.
message Endpoint {
  // The upstream host address.
  //
  // .. attention::
  //
  //   The form of host address depends on the given cluster type. For STATIC or EDS,
  //   it is expected to be a direct IP address (or something resolvable by the
  //   specified :ref:`resolver <envoy_api_field_config.core.v3.SocketAddress.resolver_name>`
  //   in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname,
  //   and will be resolved via DNS.
  core.v3.Address address = 1;
}

// An Endpoint that Envoy can route traffic to.
// [#next-free-field: 6]
message LbEndpoint {
  // Upstream host identifier or a named reference.
  oneof host_identifier {
    Endpoint endpoint = 1;
  }

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

  // The optional load balancing weight of the upstream host; at least 1.
  // 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. The sum of the weights of all endpoints in the
  // endpoint's locality must not exceed uint32_t maximal value (4294967295).
  google.protobuf.UInt32Value load_balancing_weight = 4;
}

// 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.
// [#next-free-field: 7]
message LocalityLbEndpoints {
  // Identifies location of where the upstream hosts run.
  core.v3.Locality locality = 1;

  // The group of endpoints belonging to the locality specified.
  repeated LbEndpoint lb_endpoints = 2;

  // Optional: Per priority/region/zone/sub_zone weight; at least 1. 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. The sum of the weights of all localities at
  // the same priority level must not exceed uint32_t maximal value (4294967295).
  //
  // 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
  // specified when locality weighted load balancing is enabled, the locality is
  // assigned no load.
  google.protobuf.UInt32Value load_balancing_weight = 3;

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

// [#protodoc-title: Endpoint configuration]
// Endpoint discovery :ref:`architecture overview <arch_overview_service_discovery_types_eds>`

// Each route from RDS will map to a single cluster or traffic split across
// clusters using weights expressed in the RDS WeightedCluster.
//
// With EDS, each cluster is treated independently from a LB perspective, with
// LB taking place between the Localities within a cluster and at a finer
// granularity between the hosts within a locality. The percentage of traffic
// for each endpoint is determined by both its load_balancing_weight, and the
// load_balancing_weight of its locality. First, a locality will be selected,
// then an endpoint within that locality will be chose based on its weight.
// [#next-free-field: 6]
message ClusterLoadAssignment {
  // Load balancing policy settings.
  // [#next-free-field: 6]
  message Policy {
    message DropOverload {
      // Identifier for the policy specifying the drop.
      string category = 1;

      // Percentage of traffic that should be dropped for the category.
      type.v3.FractionalPercent drop_percentage = 2;
    }

    // Action to trim the overall incoming traffic to protect the upstream
    // hosts. This action allows protection in case the hosts are unable to
    // recover from an outage, or unable to autoscale or unable to handle
    // incoming traffic volume for any reason.
    //
    // At the client each category is applied one after the other to generate
    // the 'actual' drop percentage on all outgoing traffic. For example:
    //
    // .. code-block:: json
    //
    //  { "drop_overloads": [
    //      { "category": "throttle", "drop_percentage": 60 }
    //      { "category": "lb", "drop_percentage": 50 }
    //  ]}
    //
    // The actual drop percentages applied to the traffic at the clients will be
    //    "throttle"_drop = 60%
    //    "lb"_drop = 20%  // 50% of the remaining 'actual' load, which is 40%.
    //    actual_outgoing_load = 20% // remaining after applying all categories.
    repeated DropOverload drop_overloads = 2;
  }

  // Name of the cluster. This will be the :ref:`service_name
  // <envoy_api_field_config.cluster.v3.Cluster.EdsClusterConfig.service_name>` value if specified
  // in the cluster :ref:`EdsClusterConfig
  // <envoy_api_msg_config.cluster.v3.Cluster.EdsClusterConfig>`.
  string cluster_name = 1;

  // List of endpoints to load balance to.
  repeated LocalityLbEndpoints endpoints = 2;

  // Load balancing policy settings.
  Policy policy = 4;
}