1// Copyright 2020 The gRPC Authors 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15// Local copy of Envoy xDS proto file, used for testing only. 16 17syntax = "proto3"; 18 19package envoy.config.endpoint.v3; 20 21import "src/proto/grpc/testing/xds/v3/address.proto"; 22import "src/proto/grpc/testing/xds/v3/base.proto"; 23import "src/proto/grpc/testing/xds/v3/health_check.proto"; 24import "src/proto/grpc/testing/xds/v3/percent.proto"; 25 26import "google/protobuf/wrappers.proto"; 27 28// [#protodoc-title: Endpoints] 29 30// Upstream host identifier. 31message Endpoint { 32 message AdditionalAddress { 33 // Additional address that is associated with the endpoint. 34 core.v3.Address address = 1; 35 } 36 37 // The upstream host address. 38 // 39 // .. attention:: 40 // 41 // The form of host address depends on the given cluster type. For STATIC or EDS, 42 // it is expected to be a direct IP address (or something resolvable by the 43 // specified :ref:`resolver <envoy_api_field_config.core.v3.SocketAddress.resolver_name>` 44 // in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname, 45 // and will be resolved via DNS. 46 core.v3.Address address = 1; 47 48 // An ordered list of addresses that together with `address` comprise the 49 // list of addresses for an endpoint. The address given in the `address` is 50 // prepended to this list. It is assumed that the list must already be 51 // sorted by preference order of the addresses. This will only be supported 52 // for STATIC and EDS clusters. 53 repeated AdditionalAddress additional_addresses = 4; 54} 55 56// An Endpoint that Envoy can route traffic to. 57// [#next-free-field: 6] 58message LbEndpoint { 59 // Upstream host identifier or a named reference. 60 oneof host_identifier { 61 Endpoint endpoint = 1; 62 } 63 64 // Optional health status when known and supplied by EDS server. 65 core.v3.HealthStatus health_status = 2; 66 67 // The optional load balancing weight of the upstream host; at least 1. 68 // Envoy uses the load balancing weight in some of the built in load 69 // balancers. The load balancing weight for an endpoint is divided by the sum 70 // of the weights of all endpoints in the endpoint's locality to produce a 71 // percentage of traffic for the endpoint. This percentage is then further 72 // weighted by the endpoint's locality's load balancing weight from 73 // LocalityLbEndpoints. If unspecified, each host is presumed to have equal 74 // weight in a locality. The sum of the weights of all endpoints in the 75 // endpoint's locality must not exceed uint32_t maximal value (4294967295). 76 google.protobuf.UInt32Value load_balancing_weight = 4; 77} 78 79// A group of endpoints belonging to a Locality. 80// One can have multiple LocalityLbEndpoints for a locality, but this is 81// generally only done if the different groups need to have different load 82// balancing weights or different priorities. 83// [#next-free-field: 7] 84message LocalityLbEndpoints { 85 // Identifies location of where the upstream hosts run. 86 core.v3.Locality locality = 1; 87 88 // The group of endpoints belonging to the locality specified. 89 repeated LbEndpoint lb_endpoints = 2; 90 91 // Optional: Per priority/region/zone/sub_zone weight; at least 1. The load 92 // balancing weight for a locality is divided by the sum of the weights of all 93 // localities at the same priority level to produce the effective percentage 94 // of traffic for the locality. The sum of the weights of all localities at 95 // the same priority level must not exceed uint32_t maximal value (4294967295). 96 // 97 // Locality weights are only considered when :ref:`locality weighted load 98 // balancing <arch_overview_load_balancing_locality_weighted_lb>` is 99 // configured. These weights are ignored otherwise. If no weights are 100 // specified when locality weighted load balancing is enabled, the locality is 101 // assigned no load. 102 google.protobuf.UInt32Value load_balancing_weight = 3; 103 104 // Optional: the priority for this LocalityLbEndpoints. If unspecified this will 105 // default to the highest priority (0). 106 // 107 // Under usual circumstances, Envoy will only select endpoints for the highest 108 // priority (0). In the event all endpoints for a particular priority are 109 // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the 110 // next highest priority group. 111 // 112 // Priorities should range from 0 (highest) to N (lowest) without skipping. 113 uint32 priority = 5; 114} 115 116// [#protodoc-title: Endpoint configuration] 117// Endpoint discovery :ref:`architecture overview <arch_overview_service_discovery_types_eds>` 118 119// Each route from RDS will map to a single cluster or traffic split across 120// clusters using weights expressed in the RDS WeightedCluster. 121// 122// With EDS, each cluster is treated independently from a LB perspective, with 123// LB taking place between the Localities within a cluster and at a finer 124// granularity between the hosts within a locality. The percentage of traffic 125// for each endpoint is determined by both its load_balancing_weight, and the 126// load_balancing_weight of its locality. First, a locality will be selected, 127// then an endpoint within that locality will be chose based on its weight. 128// [#next-free-field: 6] 129message ClusterLoadAssignment { 130 // Load balancing policy settings. 131 // [#next-free-field: 6] 132 message Policy { 133 message DropOverload { 134 // Identifier for the policy specifying the drop. 135 string category = 1; 136 137 // Percentage of traffic that should be dropped for the category. 138 type.v3.FractionalPercent drop_percentage = 2; 139 } 140 141 // Action to trim the overall incoming traffic to protect the upstream 142 // hosts. This action allows protection in case the hosts are unable to 143 // recover from an outage, or unable to autoscale or unable to handle 144 // incoming traffic volume for any reason. 145 // 146 // At the client each category is applied one after the other to generate 147 // the 'actual' drop percentage on all outgoing traffic. For example: 148 // 149 // .. code-block:: json 150 // 151 // { "drop_overloads": [ 152 // { "category": "throttle", "drop_percentage": 60 } 153 // { "category": "lb", "drop_percentage": 50 } 154 // ]} 155 // 156 // The actual drop percentages applied to the traffic at the clients will be 157 // "throttle"_drop = 60% 158 // "lb"_drop = 20% // 50% of the remaining 'actual' load, which is 40%. 159 // actual_outgoing_load = 20% // remaining after applying all categories. 160 repeated DropOverload drop_overloads = 2; 161 } 162 163 // Name of the cluster. This will be the :ref:`service_name 164 // <envoy_api_field_config.cluster.v3.Cluster.EdsClusterConfig.service_name>` value if specified 165 // in the cluster :ref:`EdsClusterConfig 166 // <envoy_api_msg_config.cluster.v3.Cluster.EdsClusterConfig>`. 167 string cluster_name = 1; 168 169 // List of endpoints to load balance to. 170 repeated LocalityLbEndpoints endpoints = 2; 171 172 // Load balancing policy settings. 173 Policy policy = 4; 174} 175