FailoverPolicy
FailoverPolicy API reference.
Proto: failover_policy.proto
Package: resilience.policy.gloo.solo.io
Use a failover policy to determine where to reroute traffic in case of failure. If a backing service in a virtual destination is unhealthy, Gloo Mesh re-routes traffic to another healthy backing service by locality, as specified in the FailoverPolicy config. FailoverPolicies are applied at the Destination level.
About failover policies
Note that you can use failover policies in combination with other policies, such as outlier detection or retry policies.
- FailoverPolicy: Choose where to direct traffic to, based on locality.
- OutlierDetectionPolicy: Determine when and for how long to remove unhealthy destinations from the pool of healthy destinations.
- RetryTimeoutPolicy: Decide how many times to retry requests before the outlier detection policy considers the request as failing and removes the service from the pool of healthy destinations.
To fine-tune traffic flow according to your operational needs, Istio has several locality settings that you can configure via the FailoverPolicy, as shown in the following example configurations.
Distribute with weight example
Distribute traffic based on locality to enhance user experience in terms of performance, or to manage the load across resources more efficiently. Note that this setting does not fail over traffic, but instead distributes traffic.
apiVersion: resilience.policy.gloo.solo.io/v2
kind: FailoverPolicy
metadata:
annotations:
cluster.solo.io/cluster: ""
name: locality-based-failover
namespace: bookinfo
spec:
applyToDestinations:
- kind: VIRTUAL_DESTINATION
selector: {}
config:
localityMappings:
- from:
region: us-east
to:
- region: us-west
weight: 50
- region: us-east
weight: 50
Failover example
This example selects all virtual destinations in the workspace,
and fails over traffic from any destinations served in the us-east region
to any matching destinations only in the us-west region.
apiVersion: resilience.policy.gloo.solo.io/v2
kind: FailoverPolicy
metadata:
annotations:
cluster.solo.io/cluster: ""
name: locality-based-failover
namespace: bookinfo
spec:
applyToDestinations:
- kind: VIRTUAL_DESTINATION
selector: {}
config:
localityMappings:
- from:
region: us-east
to:
- region: us-west
Failover priority example
The following example prioritizes destinations for failover traffic based on key-value labels. Destinations that match the most labels are prioritized first. For more information, including about important limitations especially in multicluster scenarios, see the failover guide.
apiVersion: resilience.policy.gloo.solo.io/v2
kind: FailoverPolicy
metadata:
annotations:
cluster.solo.io/cluster: ""
name: locality-based-failover-with-priority
namespace: bookinfo
spec:
applyToDestinations:
- kind: VIRTUAL_DESTINATION
selector: {}
config:
priorityLabels:
labels:
- version=v1
- version=v4
- topology.istio.io/subzone=a
DestinationToSelectedOutlierDetection
| Field | Description |
|---|---|
destination | (common.gloo.solo.io.DestinationReference)The destination to which the selected outlier detection policy is applied. |
selectedOutlierDetection | (common.gloo.solo.io.ObjectReference)The selected outlier detection policy. |
FailoverPolicyReport
The report shows the resources that the policy selects after the policy is successfully applied.
| Field | Description |
|---|---|
workspaces | (repeated FailoverPolicyReport.WorkspacesEntry)A list of workloads selected by the policy. |
selectedDestinationPorts | (repeated common.gloo.solo.io.DestinationReference)A list of destination ports selected by the policy. |
correspondingOutlierDetectionPolicies | (repeated DestinationToSelectedOutlierDetection)A list of selected outlier detection policies. |
FailoverPolicyReport.WorkspacesEntry
| Field | Description |
|---|---|
key | (string) |
value | (common.gloo.solo.io.Report) |
FailoverPolicySpec
Specifications for the policy.
| Field | Description |
|---|---|
applyToDestinations | (repeated common.gloo.solo.io.DestinationSelector)Select the destinations to apply the policy to by using labels. If empty, the policy applies to all destinations in the workspace. The destinations can be Kubernetes services or virtual destinations. Note that external services are not supported as destinations with this policy. |
config | (FailoverPolicySpec.Config)The details of the failover policy to apply to the selected virtual destinations. |
FailoverPolicySpec.Config
| Field | Description |
|---|---|
localityMappings | (repeated FailoverPolicySpec.Config.LocalityMappings)Map the localities to fail over traffic from one region, zone, or subzone to another in case of failure. The locality is determined by the Kubernetes labels on the node where the destination’s app runs. For more information, see the Istio docs. You can exclude this setting to enable the locality load balancer settings without mappings. Only priority labels or locality mappings can be specified, not both. |
priorityLabels | (FailoverPolicySpec.Config.PriorityLabels)Prioritize destinations to fail over traffic to by configuring priority labels. In general, destinations that match the most labels have higher priority during failover. For more information, see the Istio docs. When using priority labels, you must specify either an ordered list of label keys or an ordered list of label key-value pairs. For example, you can specify ["region"] or ["region=us-east-1", "availabilityzone=1a", "datacenter=4"]. You cannot have an ordered list that includes both label keys and label key-value pairs.Only priority labels or locality mappings can be specified, not both. If you specify both, Gloo Mesh will give precedence to the locality mappings. You can use locality labels in your list of priority labels, such as the Kubernetes topology.kubernetes.io/region node label. |
FailoverPolicySpec.Config.LocalityMappings
| Field | Description |
|---|---|
from | (FailoverPolicySpec.Config.LocalityMappings.OriginatingLocality)The locality of the destination where Gloo Mesh originally tried to fulfill the request. |
to | (repeated FailoverPolicySpec.Config.LocalityMappings.DestinationLocality)The localities of the destination where Gloo Mesh can reroute requests. You must specify the region, and optionally the zone and subzone. If you have multiple to destinations, you can optionally set a weight. |
FailoverPolicySpec.Config.LocalityMappings.DestinationLocality
A geographic location defined by a region, zone, and sub-zone along with the weight for the destination.
| Field | Description |
|---|---|
region | (string)The locality’s region. |
zone | (string)(Optional) The locality’s zone. |
subZone | (string)(Optional) The locality’s sub-zone. |
weight | (google.protobuf.UInt32Value)(Optional) Weight for destination locality. All weights must add up to 100. If not provided, weight is determined based on other destination locality weights. For information about the value format, see the Google protocol buffer documentation. |
FailoverPolicySpec.Config.LocalityMappings.OriginatingLocality
A geographic location defined by a region, zone, and sub-zone.
| Field | Description |
|---|---|
region | (string)The locality’s region. |
zone | (string)(Optional) The locality’s zone. |
subZone | (string)(Optional) The locality’s sub-zone. |
FailoverPolicySpec.Config.PriorityLabels
| Field | Description |
|---|---|
labels | (repeated string) |
FailoverPolicyStatus
The status of the policy after it is applied to your Gloo environment.
| Field | Description |
|---|---|
common | (common.gloo.solo.io.Status)The state and workspace conditions of the applied resource. |
numSelectedDestinationPorts | (uint32)The number of destination ports selected by the policy. |