Source File:


Failover configuration for an upstream.

Failover allows for optional fallback endpoints in the case that the primary set of endpoints is deemed unhealthy. As failover requires knowledge of the health of each set of endpoints, active or passive health checks must be configured on an upstream using failover in order for it to work properly.

Failover closely resembles the Envoy config which this is translated to, with one notable exception. The priorities are not defined on the LocalityLbEndpoints but rather inferred from the list of PrioritizedLocality. More information on envoy prioritization can be found here. In practice this means that the priority of a given set of LocalityLbEndpoints is determined by its index in the list, first being 0 through n-1.

"prioritizedLocalities": []

Field Type Description
prioritizedLocalities [] PrioritizedLocality is an implicitly prioritized list of lists of LocalityLbEndpoints. The priority of each list of LocalityLbEndpoints is determined by its index in the list.
policy Load balancing policy settings.


"localityEndpoints": []

Field Type Description
localityEndpoints []


"overprovisioningFactor": .google.protobuf.UInt32Value

Field Type Description
overprovisioningFactor .google.protobuf.UInt32Value 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>.


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.

"lbEndpoints": []
"loadBalancingWeight": .google.protobuf.UInt32Value

Field Type Description
locality Identifies where the parent upstream hosts run.
lbEndpoints [] The group of endpoints belonging to the locality specified. Note: If any address is DNS resolvable than lb_endpoints[].load_balancing_weight is not allowed on any of this locality’s endpoints.
loadBalancingWeight .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. To enable locality weighted load balancing, load_balancer_config.locality_weighted_lb_config must be set as well.


An Endpoint that Envoy can route traffic to.

"address": string
"port": int
"loadBalancingWeight": .google.protobuf.UInt32Value

Field Type Description
address string Address (hostname or IP).
port int Port the instance is listening on.
healthCheckConfig The optional health check configuration is used as configuration for the health checker to contact the health checked host. This takes into effect only for upstreams with active health checking enabled.
loadBalancingWeight .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 optional health check configuration.

"portValue": int
"hostname": string
"path": string
"method": string

Field Type Description
portValue int 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.
hostname string By default, the host header for L7 health checks is controlled by cluster level configuration. Setting this to a non-empty value allows overriding the cluster level configuration for a specific endpoint.
path string Path to use when health checking this failover endpoint. Default is empty path.
method string Method to use when health checking this failover endpoint. Defaults to GET.


Identifies location of where either Envoy runs or where upstream hosts run.

"region": string
"zone": string
"subZone": string

Field Type Description
region string Region this zone belongs to.
zone string Defines the local service zone where Envoy is running. The meaning of zone is context dependent, e.g. Availability Zone (AZ) <>_ on AWS, Zone <>_ on GCP, etc.
subZone string When used for locality of upstream hosts, this field further splits zone into smaller chunks of sub-zones so they can be load balanced independently.