1syntax = "proto3";
2
3package envoy.config.endpoint.v3;
4
5import "envoy/config/core/v3/address.proto";
6import "envoy/config/core/v3/base.proto";
7import "envoy/config/core/v3/config_source.proto";
8import "envoy/config/core/v3/health_check.proto";
9
10import "google/protobuf/wrappers.proto";
11
12import "udpa/annotations/status.proto";
13import "udpa/annotations/versioning.proto";
14import "validate/validate.proto";
15
16option java_package = "io.envoyproxy.envoy.config.endpoint.v3";
17option java_outer_classname = "EndpointComponentsProto";
18option java_multiple_files = true;
19option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/endpoint/v3;endpointv3";
20option (udpa.annotations.file_status).package_version_status = ACTIVE;
21
22// [#protodoc-title: Endpoints]
23
24// Upstream host identifier.
25message Endpoint {
26  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.Endpoint";
27
28  // The optional health check configuration.
29  message HealthCheckConfig {
30    option (udpa.annotations.versioning).previous_message_type =
31        "envoy.api.v2.endpoint.Endpoint.HealthCheckConfig";
32
33    // Optional alternative health check port value.
34    //
35    // By default the health check address port of an upstream host is the same
36    // as the host's serving address port. This provides an alternative health
37    // check port. Setting this with a non-zero value allows an upstream host
38    // to have different health check address port.
39    uint32 port_value = 1 [(validate.rules).uint32 = {lte: 65535}];
40
41    // By default, the host header for L7 health checks is controlled by cluster level configuration
42    // (see: :ref:`host <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.host>` and
43    // :ref:`authority <envoy_v3_api_field_config.core.v3.HealthCheck.GrpcHealthCheck.authority>`). Setting this
44    // to a non-empty value allows overriding the cluster level configuration for a specific
45    // endpoint.
46    string hostname = 2;
47
48    // Optional alternative health check host address.
49    //
50    // .. attention::
51    //
52    //   The form of the health check host address is expected to be a direct IP address.
53    core.v3.Address address = 3;
54
55    // Optional flag to control if perform active health check for this endpoint.
56    // Active health check is enabled by default if there is a health checker.
57    bool disable_active_health_check = 4;
58  }
59
60  // The upstream host address.
61  //
62  // .. attention::
63  //
64  //   The form of host address depends on the given cluster type. For STATIC or EDS,
65  //   it is expected to be a direct IP address (or something resolvable by the
66  //   specified :ref:`resolver <envoy_v3_api_field_config.core.v3.SocketAddress.resolver_name>`
67  //   in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname,
68  //   and will be resolved via DNS.
69  core.v3.Address address = 1;
70
71  // The optional health check configuration is used as configuration for the
72  // health checker to contact the health checked host.
73  //
74  // .. attention::
75  //
76  //   This takes into effect only for upstream clusters with
77  //   :ref:`active health checking <arch_overview_health_checking>` enabled.
78  HealthCheckConfig health_check_config = 2;
79
80  // The hostname associated with this endpoint. This hostname is not used for routing or address
81  // resolution. If provided, it will be associated with the endpoint, and can be used for features
82  // that require a hostname, like
83  // :ref:`auto_host_rewrite <envoy_v3_api_field_config.route.v3.RouteAction.auto_host_rewrite>`.
84  string hostname = 3;
85}
86
87// An Endpoint that Envoy can route traffic to.
88// [#next-free-field: 6]
89message LbEndpoint {
90  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.LbEndpoint";
91
92  // Upstream host identifier or a named reference.
93  oneof host_identifier {
94    Endpoint endpoint = 1;
95
96    // [#not-implemented-hide:]
97    string endpoint_name = 5;
98  }
99
100  // Optional health status when known and supplied by EDS server.
101  core.v3.HealthStatus health_status = 2;
102
103  // The endpoint metadata specifies values that may be used by the load
104  // balancer to select endpoints in a cluster for a given request. The filter
105  // name should be specified as ``envoy.lb``. An example boolean key-value pair
106  // is ``canary``, providing the optional canary status of the upstream host.
107  // This may be matched against in a route's
108  // :ref:`RouteAction <envoy_v3_api_msg_config.route.v3.RouteAction>` metadata_match field
109  // to subset the endpoints considered in cluster load balancing.
110  core.v3.Metadata metadata = 3;
111
112  // The optional load balancing weight of the upstream host; at least 1.
113  // Envoy uses the load balancing weight in some of the built in load
114  // balancers. The load balancing weight for an endpoint is divided by the sum
115  // of the weights of all endpoints in the endpoint's locality to produce a
116  // percentage of traffic for the endpoint. This percentage is then further
117  // weighted by the endpoint's locality's load balancing weight from
118  // LocalityLbEndpoints. If unspecified, will be treated as 1. The sum
119  // of the weights of all endpoints in the endpoint's locality must not
120  // exceed uint32_t maximal value (4294967295).
121  google.protobuf.UInt32Value load_balancing_weight = 4 [(validate.rules).uint32 = {gte: 1}];
122}
123
124// [#not-implemented-hide:]
125// A configuration for a LEDS collection.
126message LedsClusterLocalityConfig {
127  // Configuration for the source of LEDS updates for a Locality.
128  core.v3.ConfigSource leds_config = 1;
129
130  // The xDS transport protocol glob collection resource name.
131  // The service is only supported in delta xDS (incremental) mode.
132  string leds_collection_name = 2;
133}
134
135// A group of endpoints belonging to a Locality.
136// One can have multiple LocalityLbEndpoints for a locality, but only if
137// they have different priorities.
138// [#next-free-field: 9]
139message LocalityLbEndpoints {
140  option (udpa.annotations.versioning).previous_message_type =
141      "envoy.api.v2.endpoint.LocalityLbEndpoints";
142
143  // [#not-implemented-hide:]
144  // A list of endpoints of a specific locality.
145  message LbEndpointList {
146    repeated LbEndpoint lb_endpoints = 1;
147  }
148
149  // Identifies location of where the upstream hosts run.
150  core.v3.Locality locality = 1;
151
152  // The group of endpoints belonging to the locality specified.
153  // [#comment:TODO(adisuissa): Once LEDS is implemented this field needs to be
154  // deprecated and replaced by ``load_balancer_endpoints``.]
155  repeated LbEndpoint lb_endpoints = 2;
156
157  // [#not-implemented-hide:]
158  oneof lb_config {
159    // The group of endpoints belonging to the locality.
160    // [#comment:TODO(adisuissa): Once LEDS is implemented the ``lb_endpoints`` field
161    // needs to be deprecated.]
162    LbEndpointList load_balancer_endpoints = 7;
163
164    // LEDS Configuration for the current locality.
165    LedsClusterLocalityConfig leds_cluster_locality_config = 8;
166  }
167
168  // Optional: Per priority/region/zone/sub_zone weight; at least 1. The load
169  // balancing weight for a locality is divided by the sum of the weights of all
170  // localities  at the same priority level to produce the effective percentage
171  // of traffic for the locality. The sum of the weights of all localities at
172  // the same priority level must not exceed uint32_t maximal value (4294967295).
173  //
174  // Locality weights are only considered when :ref:`locality weighted load
175  // balancing <arch_overview_load_balancing_locality_weighted_lb>` is
176  // configured. These weights are ignored otherwise. If no weights are
177  // specified when locality weighted load balancing is enabled, the locality is
178  // assigned no load.
179  google.protobuf.UInt32Value load_balancing_weight = 3 [(validate.rules).uint32 = {gte: 1}];
180
181  // Optional: the priority for this LocalityLbEndpoints. If unspecified this will
182  // default to the highest priority (0).
183  //
184  // Under usual circumstances, Envoy will only select endpoints for the highest
185  // priority (0). In the event all endpoints for a particular priority are
186  // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the
187  // next highest priority group.
188  //
189  // Priorities should range from 0 (highest) to N (lowest) without skipping.
190  uint32 priority = 5 [(validate.rules).uint32 = {lte: 128}];
191
192  // Optional: Per locality proximity value which indicates how close this
193  // locality is from the source locality. This value only provides ordering
194  // information (lower the value, closer it is to the source locality).
195  // This will be consumed by load balancing schemes that need proximity order
196  // to determine where to route the requests.
197  // [#not-implemented-hide:]
198  google.protobuf.UInt32Value proximity = 6;
199}
200