package envoy.config.endpoint.v3

Get desktop application:
View/edit binary Protocol Buffers messages

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]

Used in: cluster.v3.Cluster

• string cluster_name = 1

  Name of the cluster. This will be the :ref:`service_name <envoy_v3_api_field_config.cluster.v3.Cluster.EdsClusterConfig.service_name>` value if specified in the cluster :ref:`EdsClusterConfig <envoy_v3_api_msg_config.cluster.v3.Cluster.EdsClusterConfig>`.

• repeated LocalityLbEndpoints endpoints = 2

  List of endpoints to load balance to.

• map<string, Endpoint> named_endpoints = 5

  Map of named endpoints that can be referenced in LocalityLbEndpoints. [#not-implemented-hide:]

• optional ClusterLoadAssignment.Policy policy = 4

  Load balancing policy settings.

Load balancing policy settings. [#next-free-field: 7]

Used in: ClusterLoadAssignment

• repeated Policy.DropOverload drop_overloads = 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. Envoy supports only one element and will NACK if more than one element is present. Other xDS-capable data planes will not necessarily have this limitation. In Envoy, this ``drop_overloads`` config can be overridden by a runtime key "load_balancing_policy.drop_overload_limit" setting. This runtime key can be set to any integer number between 0 and 100. 0 means drop 0%. 100 means drop 100%. When both ``drop_overloads`` config and "load_balancing_policy.drop_overload_limit" setting are in place, the min of these two wins.

• optional google.protobuf.UInt32Value overprovisioning_factor = 3

  Priority levels and localities are considered overprovisioned with this factor (in percentage). This means that we don't consider a priority level or locality unhealthy until the fraction of healthy hosts multiplied by the overprovisioning factor drops below 100. With the default value 140(1.4), Envoy doesn't consider a priority level or a locality unhealthy until their percentage of healthy hosts drops below 72%. For example: .. code-block:: json { "overprovisioning_factor": 100 } Read more at :ref:`priority levels <arch_overview_load_balancing_priority_levels>` and :ref:`localities <arch_overview_load_balancing_locality_weighted_lb>`.

• optional google.protobuf.Duration endpoint_stale_after = 4

  The max time until which the endpoints from this assignment can be used. If no new assignments are received before this time expires the endpoints are considered stale and should be marked unhealthy. Defaults to 0 which means endpoints never go stale.

• bool weighted_priority_health = 6

  If true, use the :ref:`load balancing weight <envoy_v3_api_field_config.endpoint.v3.LbEndpoint.load_balancing_weight>` of healthy and unhealthy hosts to determine the health of the priority level. If false, use the number of healthy and unhealthy hosts to determine the health of the priority level, or in other words assume each host has a weight of 1 for this calculation. Note: this is not currently implemented for :ref:`locality weighted load balancing <arch_overview_load_balancing_locality_weighted_lb>`.

Used in: Policy

• string category = 1

  Identifier for the policy specifying the drop.

• optional type.v3.FractionalPercent drop_percentage = 2

  Percentage of traffic that should be dropped for the category.

Per cluster load stats. Envoy reports these stats a management server in a :ref:`LoadStatsRequest<envoy_v3_api_msg_service.load_stats.v3.LoadStatsRequest>` Next ID: 7 [#next-free-field: 7]

Used in: service.load_stats.v3.LoadStatsRequest

• string cluster_name = 1

  The name of the cluster.

• string cluster_service_name = 6

  The eds_cluster_config service_name of the cluster. It's possible that two clusters send the same service_name to EDS, in that case, the management server is supposed to do aggregation on the load reports.

• repeated UpstreamLocalityStats upstream_locality_stats = 2

  Need at least one.

• uint64 total_dropped_requests = 3

  Cluster-level stats such as total_successful_requests may be computed by summing upstream_locality_stats. In addition, below there are additional cluster-wide stats. The total number of dropped requests. This covers requests deliberately dropped by the drop_overload policy and circuit breaking.

• repeated ClusterStats.DroppedRequests dropped_requests = 5

  Information about deliberately dropped requests for each category specified in the DropOverload policy.

• optional google.protobuf.Duration load_report_interval = 4

  Period over which the actual load report occurred. This will be guaranteed to include every request reported. Due to system load and delays between the ``LoadStatsRequest`` sent from Envoy and the ``LoadStatsResponse`` message sent from the management server, this may be longer than the requested load reporting interval in the ``LoadStatsResponse``.

Used in: ClusterStats

• string category = 1

  Identifier for the policy specifying the drop.

• uint64 dropped_count = 2

  Total number of deliberately dropped requests for the category.

Upstream host identifier.

Used in: ClusterLoadAssignment, LbEndpoint, service.health.v3.EndpointHealth, service.health.v3.LocalityEndpoints

• optional core.v3.Address address = 1

  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_v3_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.

• optional Endpoint.HealthCheckConfig health_check_config = 2

  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.

• string hostname = 3

  The hostname associated with this endpoint. This hostname is not used for routing or address resolution. If provided, it will be associated with the endpoint, and can be used for features that require a hostname, like :ref:`auto_host_rewrite <envoy_v3_api_field_config.route.v3.RouteAction.auto_host_rewrite>`.

• repeated Endpoint.AdditionalAddress additional_addresses = 4

  An ordered list of addresses that together with ``address`` comprise the list of addresses for an endpoint. The address given in the ``address`` is prepended to this list. It is assumed that the list must already be sorted by preference order of the addresses. This will only be supported for STATIC and EDS clusters.

Used in: Endpoint

• optional core.v3.Address address = 1

  Additional address that is associated with the endpoint.

The optional health check configuration.

Used in: Endpoint

• uint32 port_value = 1

  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.

• string hostname = 2

  By default, the host header for L7 health checks is controlled by cluster level configuration (see: :ref:`host <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.host>` and :ref:`authority <envoy_v3_api_field_config.core.v3.HealthCheck.GrpcHealthCheck.authority>`). Setting this to a non-empty value allows overriding the cluster level configuration for a specific endpoint.

• optional core.v3.Address address = 3

  Optional alternative health check host address. .. attention:: The form of the health check host address is expected to be a direct IP address.

• bool disable_active_health_check = 4

  Optional flag to control if perform active health check for this endpoint. Active health check is enabled by default if there is a health checker.

Used in: UpstreamEndpointStats, UpstreamLocalityStats

• string metric_name = 1

  Name of the metric; may be empty.

• uint64 num_requests_finished_with_metric = 2

  Number of calls that finished and included this metric.

• double total_metric_value = 3

  Sum of metric values across all calls that finished with this metric for load_reporting_interval.

An Endpoint that Envoy can route traffic to. [#next-free-field: 6]

Used in: LocalityLbEndpoints, LocalityLbEndpoints.LbEndpointList

• oneof host_identifier

  Upstream host identifier or a named reference.

  • Endpoint endpoint = 1

  • string endpoint_name = 5

    [#not-implemented-hide:]

• core.v3.HealthStatus health_status = 2

  Optional health status when known and supplied by EDS server.

• optional core.v3.Metadata metadata = 3

  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 :ref:`RouteAction <envoy_v3_api_msg_config.route.v3.RouteAction>` metadata_match field to subset the endpoints considered in cluster load balancing.

• optional google.protobuf.UInt32Value load_balancing_weight = 4

  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, will be treated as 1. The sum of the weights of all endpoints in the endpoint's locality must not exceed uint32_t maximal value (4294967295).

LbEndpoint list collection. Entries are `LbEndpoint` resources or references. [#not-implemented-hide:]

• optional xds.core.v3.CollectionEntry entries = 1

A configuration for an LEDS collection.

Used in: LocalityLbEndpoints

• optional core.v3.ConfigSource leds_config = 1

  Configuration for the source of LEDS updates for a Locality.

• string leds_collection_name = 2

  The name of the LbEndpoint collection resource. If the name ends in ``/*``, it indicates an LbEndpoint glob collection, which is supported only in the xDS incremental protocol variants. Otherwise, it indicates an LbEndpointCollection list collection. Envoy currently supports only glob collections.

A group of endpoints belonging to a Locality. One can have multiple LocalityLbEndpoints for a locality, but only if they have different priorities. [#next-free-field: 10]

Used in: ClusterLoadAssignment

• optional core.v3.Locality locality = 1

  Identifies location of where the upstream hosts run.

• optional core.v3.Metadata metadata = 9

  Metadata to provide additional information about the locality endpoints in aggregate.

• repeated LbEndpoint lb_endpoints = 2

  The group of endpoints belonging to the locality specified. This is ignored if :ref:`leds_cluster_locality_config <envoy_v3_api_field_config.endpoint.v3.LocalityLbEndpoints.leds_cluster_locality_config>` is set.

• oneof lb_config

  • LocalityLbEndpoints.LbEndpointList load_balancer_endpoints = 7

    [#not-implemented-hide:] Not implemented and deprecated.

  • LedsClusterLocalityConfig leds_cluster_locality_config = 8

    LEDS Configuration for the current locality. If this is set, the :ref:`lb_endpoints <envoy_v3_api_field_config.endpoint.v3.LocalityLbEndpoints.lb_endpoints>` field is ignored.

• optional google.protobuf.UInt32Value load_balancing_weight = 3

  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.

• uint32 priority = 5

  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 that enough endpoints for a particular priority are unavailable/unhealthy, Envoy will fail over to selecting endpoints for the next highest priority group. Read more at :ref:`priority levels <arch_overview_load_balancing_priority_levels>`. Priorities should range from 0 (highest) to N (lowest) without skipping.

• optional google.protobuf.UInt32Value proximity = 6

  Optional: Per locality proximity value which indicates how close this locality is from the source locality. This value only provides ordering information (lower the value, closer it is to the source locality). This will be consumed by load balancing schemes that need proximity order to determine where to route the requests. [#not-implemented-hide:]

[#not-implemented-hide:] A list of endpoints of a specific locality.

Used in: LocalityLbEndpoints

• repeated LbEndpoint lb_endpoints = 1

Same as EndpointLoadMetricStats, except without the metric_name field.

Used in: UpstreamLocalityStats

• uint64 num_requests_finished_with_metric = 1

  Number of calls that finished and included this metric.

• double total_metric_value = 2

  Sum of metric values across all calls that finished with this metric for load_reporting_interval.

[#next-free-field: 8]

Used in: UpstreamLocalityStats

• optional core.v3.Address address = 1

  Upstream host address.

• optional google.protobuf.Struct metadata = 6

  Opaque and implementation dependent metadata of the endpoint. Envoy will pass this directly to the management server.

• uint64 total_successful_requests = 2

  The total number of requests successfully completed by the endpoints in the locality. These include non-5xx responses for HTTP, where errors originate at the client and the endpoint responded successfully. For gRPC, the grpc-status values are those not covered by total_error_requests below.

• uint64 total_requests_in_progress = 3

  The total number of unfinished requests for this endpoint.

• uint64 total_error_requests = 4

  The total number of requests that failed due to errors at the endpoint. For HTTP these are responses with 5xx status codes and for gRPC the grpc-status values: - DeadlineExceeded - Unimplemented - Internal - Unavailable - Unknown - DataLoss

• uint64 total_issued_requests = 7

  The total number of requests that were issued to this endpoint since the last report. A single TCP connection, HTTP or gRPC request or stream is counted as one request.

• repeated EndpointLoadMetricStats load_metric_stats = 5

  Stats for multi-dimensional load balancing.

These are stats Envoy reports to the management server at a frequency defined by :ref:`LoadStatsResponse.load_reporting_interval<envoy_v3_api_field_service.load_stats.v3.LoadStatsResponse.load_reporting_interval>`. Stats per upstream region/zone and optionally per subzone. [#next-free-field: 15]

Used in: ClusterStats

• optional core.v3.Locality locality = 1

  Name of zone, region and optionally endpoint group these metrics were collected from. Zone and region names could be empty if unknown.

• uint64 total_successful_requests = 2

  The total number of requests successfully completed by the endpoints in the locality.

• uint64 total_requests_in_progress = 3

  The total number of unfinished requests

• uint64 total_error_requests = 4

  The total number of requests that failed due to errors at the endpoint, aggregated over all endpoints in the locality.

• uint64 total_issued_requests = 8

  The total number of requests that were issued by this Envoy since the last report. This information is aggregated over all the upstream endpoints in the locality.

• uint64 total_active_connections = 9

  The total number of connections in an established state at the time of the report. This field is aggregated over all the upstream endpoints in the locality. In Envoy, this information may be based on ``upstream_cx_active metric``. [#not-implemented-hide:]

• uint64 total_new_connections = 10

  The total number of connections opened since the last report. This field is aggregated over all the upstream endpoints in the locality. In Envoy, this information may be based on ``upstream_cx_total`` metric compared to itself between start and end of an interval, i.e. ``upstream_cx_total``(now) - ``upstream_cx_total``(now - load_report_interval). [#not-implemented-hide:]

• uint64 total_fail_connections = 11

  The total number of connection failures since the last report. This field is aggregated over all the upstream endpoints in the locality. In Envoy, this information may be based on ``upstream_cx_connect_fail`` metric compared to itself between start and end of an interval, i.e. ``upstream_cx_connect_fail``(now) - ``upstream_cx_connect_fail``(now - load_report_interval). [#not-implemented-hide:]

• optional UnnamedEndpointLoadMetricStats cpu_utilization = 12

  CPU utilization stats for multi-dimensional load balancing. This typically comes from endpoint metrics reported via ORCA.

• optional UnnamedEndpointLoadMetricStats mem_utilization = 13

  Memory utilization for multi-dimensional load balancing. This typically comes from endpoint metrics reported via ORCA.

• optional UnnamedEndpointLoadMetricStats application_utilization = 14

  Blended application-defined utilization for multi-dimensional load balancing. This typically comes from endpoint metrics reported via ORCA.

• repeated EndpointLoadMetricStats load_metric_stats = 5

  Named stats for multi-dimensional load balancing. These typically come from endpoint metrics reported via ORCA.

• repeated UpstreamEndpointStats upstream_endpoint_stats = 7

  Endpoint granularity stats information for this locality. This information is populated if the Server requests it by setting :ref:`LoadStatsResponse.report_endpoint_granularity<envoy_v3_api_field_service.load_stats.v3.LoadStatsResponse.report_endpoint_granularity>`.

• uint32 priority = 6

  [#not-implemented-hide:] The priority of the endpoint group these metrics were collected from.