Configure Composite Health for automatic cross-region failover

This page describes how service producers can configure Composite Health to support automatic cross-region failover for published services.

Before you begin

Read about Composite Health.
In each region that you want to support, identify or create a target service that meets the following requirements.
- It must use one of the following internal load balancers:
- It must use one of the following backend types:
  - A zonal network endpoint group (NEG) with network endpoint type GCE_VM_IP or GCE_VM_IP_PORT
  - An instance group
The steps to create your target services depend on the load balancer and backend types that you choose. For information on creating target services, see your load balancer's documentation.
Publish each target service by creating a service attachment.
Understand that to use Composite Health for failover, consumers must access your services with load balancers that support cross-region failover.
Enable the Compute Engine API in your project.
Verify that you have the permissions required to complete this guide.

Required roles

To get the permissions that you need to configure Composite Health, ask your administrator to grant you the Compute Network Admin (roles/compute.networkAdmin) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to configure Composite Health. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to configure Composite Health:

compute.regionHealthAggregationPolicies.list
compute.regionHealthAggregationPolicies.get
compute.regionHealthAggregationPolicies.create
compute.regionHealthAggregationPolicies.update
compute.regionHealthAggregationPolicies.delete
compute.regionHealthSources.list
compute.regionHealthSources.get
compute.regionHealthSources.create
compute.regionHealthSources.update
compute.regionHealthSources.delete
compute.regionCompositeHealthChecks.list
compute.regionCompositeHealthChecks.get
compute.regionCompositeHealthChecks.create
compute.regionCompositeHealthChecks.update
compute.regionCompositeHealthChecks.delete

You might also be able to get these permissions with custom roles or other predefined roles.

Configure Composite Health to support automatic cross-region failover

The following sections describe how to configure Composite Health for automatic cross-region failover.

While Composite Health doesn't require configuration by the service consumer, the feature only works if the consumer configures supported Private Service Connect backends in a multi-region deployment. For information about how a service consumer can configure their VPC network to use health Composite Health, see Automatic cross-region failover.

Create a health aggregation policy

Create at least one health aggregation policy in every region where you want to support cross-region failover.

A health aggregation policy is a reusable resource that defines the criteria for a backend service to be considered healthy. You can apply the same policy to multiple backend services, or create different policies for services that have different health requirements.

Console

In the Google Cloud console, go to the Composite Health page:

Go to Composite Health
Click Health aggregation policies.
Click Create health aggregation policy.
Enter a name for the health aggregation policy.
Optional: Enter a description of the policy.
Click Region, and then select a region for the health aggregation policy.
Click Next.
In the Healthy percent threshold box, enter the minimum percentage of endpoints in a backend service that must be healthy for the health source to be considered healthy—for example, 75.
In the Minimum healthy threshold box, enter the minimum number of endpoints in a backend service that must be healthy for the health source to be considered healthy.
Click Create.

gcloud

Use the gcloud compute health-aggregation-policies create command.

gcloud compute health-aggregation-policies create POLICY \
    --region=REGION \
    --healthy-percent-threshold=PERCENT_HEALTHY \
    --min-healthy-threshold=MINIMUM_HEALTHY

Replace the following:

POLICY: the name of the health aggregation policy
REGION: the region of the health aggregation policy
PERCENT_HEALTHY: the minimum percentage of endpoints in a backend service that must be healthy for the health source to be considered healthy—for example, 75

The default is 60. Endpoints can be VMs in an instance group or network endpoints in a network endpoint group (NEG).
MINIMUM_HEALTHY: the minimum number of endpoints in a backend service that must be healthy for the health source to be considered healthy

The default is 1.

API

Send a request to the regionHealthAggregationPolicies.insert method.

HTTP method and URL:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/healthAggregationPolicies

Request JSON body:

{
  "name": "POLICY",
  "policyType": "BACKEND_SERVICE_POLICY",
  "healthyPercentThreshold": PERCENT_HEALTHY,
  "minHealthyThreshold": MINIMUM_HEALTHY
}

Replace the following:

PROJECT_ID: the project ID for the health aggregation policy.
REGION: the region of the health aggregation policy.
POLICY: the name of the health aggregation policy.
PERCENT_HEALTHY: the minimum percentage of endpoints in a backend service that must be healthy for the health source to be considered healthy—for example, 75.

The default is 60. Endpoints can be VMs in an instance group or network endpoints in a network endpoint group (NEG).
MINIMUM_HEALTHY: the minimum number of endpoints in a backend service that must be healthy for the health source to be considered healthy.

The default is 1.

Create a health source

Create a health source for each regional instance of your published service. If an instance of your published service depends on the health of multiple backend services, create a separate health source for each of those backend services.

A health source is the resource that links a health aggregation policy to a specific backend service. A composite health check aggregates the health states from one or more health sources to produce a final composite health state for your service.

Console

In the Google Cloud console, go to the Composite Health page:

Go to Composite Health
Click Health sources.
Click Create health source.
Enter a name for the health source.
Optional: Enter a description of the health source.
Click Region, and then select a region for the health source.
Click Next.
Click Source, and then select a backend service to associate with the health source.
Click Next.
Click Health aggregation policy, and then select the health aggregation policy to apply to this health source.
Click Create.

gcloud

Use the gcloud compute health-sources create command.

gcloud compute health-sources create HEALTH_SOURCE \
    --region=REGION \
    --source-type=BACKEND_SERVICE \
    --sources=BACKEND_SERVICE \
    --health-aggregation-policy=POLICY

Replace the following:

HEALTH_SOURCE: the name of the health source
REGION: the region of the health source

The health aggregation policy must be in the same region as the health source.
BACKEND_SERVICE: the name of a single backend service to associate with the health source

The backend service must fulfill the following requirements:
- It must have a load balancing scheme of INTERNAL or INTERNAL_MANAGED.
- It must be in the same region as the health source you are creating.
- Its backends must be instance groups or network endpoint groups of type GCE_VM_IP or GCE_VM_IP_PORT.
POLICY: the name of the health aggregation policy to apply to this health source

API

Send a request to the regionHealthSources.insert method.

HTTP method and URL:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/healthSources

Request JSON body:

{
  "name": "HEALTH_SOURCE",
  "sourceType": "BACKEND_SERVICE",
  "sources": [
    "projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE"
  ],
  "healthAggregationPolicy": "projects/PROJECT_ID/regions/REGION/healthAggregationPolicies/POLICY"
}

Replace the following:

PROJECT_ID: the project ID for the health source.
REGION: the region of the health source.

The health aggregation policy must be in the same region as the health source.
HEALTH_SOURCE: the name of the health source.
BACKEND_SERVICE: the name of a single backend service to associate with the health source.

The backend service must fulfill the following requirements:
- It must have a load balancing scheme of INTERNAL or INTERNAL_MANAGED.
- It must be in the same region as the health source you are creating.
- Its backends must be instance groups or network endpoint groups of type GCE_VM_IP or GCE_VM_IP_PORT.
POLICY: the name of the health aggregation policy to apply to this health source.

Create a composite health check

Create a composite health check for each regional instance of your published service.

A composite health check aggregates the health states of its associated health sources, creating a final composite health state. The final health state is applied to the regional published service that is associated with the forwarding rule that you specify as a health destination.

Console

In the Google Cloud console, go to the Composite Health page:

Go to Composite Health
Click Composite health checks.
Click Create composite health check.
Enter a name for the composite health check.
Optional: Enter a description of the composite health check.
Click Region, and then select a region for the composite health check.
Click Next.
Click Health source, and then select a health source to associate with the composite health check. You can add more health sources by clicking Add health source and then selecting another health source.
Click Next.
Click Load balancer type, and then select the type of load balancer to use as the health destination.
Click Load balancer, and then select the load balancer to use as the health destination.
If your load balancer is associated with multiple forwarding rules, click Forwarding rule, and then select the forwarding rule to use as the health destination.
Click Create.

gcloud

Use the gcloud compute composite-health-checks create command.

gcloud compute composite-health-checks create COMPOSITE_HEALTH_CHECK \
    --region=REGION \
    --health-sources=HEALTH_SOURCES \
    --health-destination=HEALTH_DESTINATION

Replace the following:

COMPOSITE_HEALTH_CHECK: the name of the composite health check
REGION: the region of the composite health check
HEALTH_SOURCES: the names of one or more health sources to associate with the composite health check

You can include multiple health sources in a comma-separated list.
HEALTH_DESTINATION: the URI of the forwarding rule that receives the composite health state from this composite health check—for example, projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE

The forwarding rule must be associated with a producer load balancer that supports Composite Health and fulfills the following requirements:
- It must have a load balancing scheme of INTERNAL or INTERNAL_MANAGED.
- It must be in the same region as the composite health check.

API

Send a request to the regionCompositeHealthChecks.insert method.

HTTP method and URL:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/compositeHealthChecks

Request JSON body:

{
  "name": "COMPOSITE_HEALTH_CHECK",
  "healthSources": [
    "projects/PROJECT_ID/regions/REGION/healthSources/HEALTH_SOURCE"
  ],
  "healthDestination": "HEALTH_DESTINATION"
}

Replace the following:

PROJECT_ID: the project ID for the composite health check.
REGION: the region of the composite health check.
COMPOSITE_HEALTH_CHECK: the name of the composite health check.
HEALTH_SOURCE: the name of a health source to associate with the composite health check. You can include multiple health sources in the healthSources array.
HEALTH_DESTINATION: the URI of the forwarding rule that receives the composite health state from this composite health check—for example, projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE

The forwarding rule must be associated with a producer load balancer that supports Composite Health and fulfills the following requirements:
- It must have a load balancing scheme of INTERNAL or INTERNAL_MANAGED.
- It must be in the same region as the composite health check.

What's next

To monitor your published service with Composite Health, see Monitor Composite Health.
To manage Composite Health configuration, see View, update, and delete Composite Health configuration.