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


"localityEndpoints": []

Field Type Description Default
localityEndpoints []


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 Default
locality Identifies where the parent upstream hosts run.
lbEndpoints [] The group of endpoints belonging to the locality specified.
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.


An Endpoint that Envoy can route traffic to.

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

Field Type Description Default
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

Field Type Description Default
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.


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

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

Field Type Description Default
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.