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