.. _envoy_api_file_envoy/api/v2/endpoint/endpoint_components.proto:

Endpoints
=========


.. _envoy_api_msg_endpoint.Endpoint:

endpoint.Endpoint
-----------------

`[endpoint.Endpoint proto] <https://github.com/envoyproxy/envoy/blob/v1.17.2/api/envoy/api/v2/endpoint/endpoint_components.proto#L23>`_

Upstream host identifier.

.. code-block:: json

  {
    "address": "{...}",
    "health_check_config": "{...}",
    "hostname": "..."
  }

.. _envoy_api_field_endpoint.Endpoint.address:

address
  (:ref:`core.Address <envoy_api_msg_core.Address>`) 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_core.SocketAddress.resolver_name>`
    in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname,
    and will be resolved via DNS.
  
  
.. _envoy_api_field_endpoint.Endpoint.health_check_config:

health_check_config
  (:ref:`endpoint.Endpoint.HealthCheckConfig <envoy_api_msg_endpoint.Endpoint.HealthCheckConfig>`) 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.
  
  
.. _envoy_api_field_endpoint.Endpoint.hostname:

hostname
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 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_api_field_route.RouteAction.auto_host_rewrite>`.
  
  
.. _envoy_api_msg_endpoint.Endpoint.HealthCheckConfig:

endpoint.Endpoint.HealthCheckConfig
-----------------------------------

`[endpoint.Endpoint.HealthCheckConfig proto] <https://github.com/envoyproxy/envoy/blob/v1.17.2/api/envoy/api/v2/endpoint/endpoint_components.proto#L25>`_

The optional health check configuration.

.. code-block:: json

  {
    "port_value": "...",
    "hostname": "..."
  }

.. _envoy_api_field_endpoint.Endpoint.HealthCheckConfig.port_value:

port_value
  (`uint32 <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 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.
  
  
.. _envoy_api_field_endpoint.Endpoint.HealthCheckConfig.hostname:

hostname
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) By default, the host header for L7 health checks is controlled by cluster level configuration
  (see: :ref:`host <envoy_api_field_core.HealthCheck.HttpHealthCheck.host>` and
  :ref:`authority <envoy_api_field_core.HealthCheck.GrpcHealthCheck.authority>`). Setting this
  to a non-empty value allows overriding the cluster level configuration for a specific
  endpoint.
  
  



.. _envoy_api_msg_endpoint.LbEndpoint:

endpoint.LbEndpoint
-------------------

`[endpoint.LbEndpoint proto] <https://github.com/envoyproxy/envoy/blob/v1.17.2/api/envoy/api/v2/endpoint/endpoint_components.proto#L71>`_

An Endpoint that Envoy can route traffic to.

.. code-block:: json

  {
    "endpoint": "{...}",
    "health_status": "...",
    "metadata": "{...}",
    "load_balancing_weight": "{...}"
  }

.. _envoy_api_field_endpoint.LbEndpoint.endpoint:

endpoint
  (:ref:`endpoint.Endpoint <envoy_api_msg_endpoint.Endpoint>`) 
  Upstream host identifier or a named reference.
  
  

.. _envoy_api_field_endpoint.LbEndpoint.health_status:

health_status
  (:ref:`core.HealthStatus <envoy_api_enum_core.HealthStatus>`) Optional health status when known and supplied by EDS server.
  
  
.. _envoy_api_field_endpoint.LbEndpoint.metadata:

metadata
  (:ref:`core.Metadata <envoy_api_msg_core.Metadata>`) 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_api_msg_route.RouteAction>` metadata_match field
  to subset the endpoints considered in cluster load balancing.
  
  
.. _envoy_api_field_endpoint.LbEndpoint.load_balancing_weight:

load_balancing_weight
  (`UInt32Value <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#uint32value>`_) 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).
  
  


.. _envoy_api_msg_endpoint.LocalityLbEndpoints:

endpoint.LocalityLbEndpoints
----------------------------

`[endpoint.LocalityLbEndpoints proto] <https://github.com/envoyproxy/envoy/blob/v1.17.2/api/envoy/api/v2/endpoint/endpoint_components.proto#L109>`_

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.

.. code-block:: json

  {
    "locality": "{...}",
    "lb_endpoints": [],
    "load_balancing_weight": "{...}",
    "priority": "..."
  }

.. _envoy_api_field_endpoint.LocalityLbEndpoints.locality:

locality
  (:ref:`core.Locality <envoy_api_msg_core.Locality>`) Identifies location of where the upstream hosts run.
  
  
.. _envoy_api_field_endpoint.LocalityLbEndpoints.lb_endpoints:

lb_endpoints
  (**repeated** :ref:`endpoint.LbEndpoint <envoy_api_msg_endpoint.LbEndpoint>`) The group of endpoints belonging to the locality specified.
  
  
.. _envoy_api_field_endpoint.LocalityLbEndpoints.load_balancing_weight:

load_balancing_weight
  (`UInt32Value <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#uint32value>`_) 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.
  
  
.. _envoy_api_field_endpoint.LocalityLbEndpoints.priority:

priority
  (`uint32 <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 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.