About Composite Health for automatic cross-region failover

Composite Health lets service producers define criteria that determine health states for regional published services. These health states support automatic cross-region failover for service consumers that use Private Service Connect backends. The health states are based on the aggregated health of the service producer's backends (VMs or network endpoints), providing consumers with a more accurate failover signal than outlier detection, which infers health from response failures.

To enable cross-region failover, both the service producer and consumer must use a multi-region deployment. When you configure Composite Health, the health state of each regional published service is automatically propagated to the consumer's load balancer. If a published service in one region becomes unhealthy, the consumer's load balancer stops routing traffic to that service and instead routes traffic to a healthy instance of the published service that is in an alternate region.

Deployment requirements

This section describes how service producers and service consumers can configure their resources for a multi-region deployment that supports automatic cross-region failover with Composite Health.

For more information about requirements for load balancer and backend types, see Specifications.

Producer configuration:

Consumer configuration:

The following diagram shows a multi-region deployment:

A multi-region deployment consists of a consumer load balancer that connects to services published in multiple regions using Private Service Connect.

This example shows a consumer global external Application Load Balancer that connects to a service that is published in multiple regions. Accessing a multi-region service with a supported global or cross-regional load balancer lets the service consumer take advantage of Composite Health for automatic cross-region failover (click to enlarge).

Composite Health components

Composite Health uses the following components to support automatic cross-region failover.

Multiple health sources, each with a health aggregation policy, are combined in a composite health check, which updates the Health Destination.

The preceding diagram shows the key components of Composite Health. Health aggregation policies define conditions for health sources to be considered healthy. Health states for individual health sources are combined into a single state by a composite health check, and the result is delivered to a health destination.

Health aggregation policy

A health aggregation policy is a resource that you create to define the conditions that a backend service must meet to be considered healthy. A policy aggregates the health states of a backend service's backends (VMs in an instance group or network endpoints in a NEG), as determined by regular health checks.

A backend service is considered healthy if two configurable conditions are met:

  • Percentage of healthy endpoints: The minimum percentage of backends that must be healthy. The default is 60%.

  • Minimum number of healthy endpoints: The minimum number of backends that must be healthy. The default value is 1.

For example, you can create a policy that specifies a backend service must have at least 75% of its backends healthy and at least three healthy backends. If the number of healthy backends falls below either of those thresholds, the backend service is considered unhealthy.

Health source

A health source is a resource that makes the health of a single backend service available for aggregation as part of a composite health check. When you create a health source, you specify the following:

  • A backend service to monitor
  • A health aggregation policy that determines the backend service's health

The health source uses the conditions defined in the health aggregation policy to determine the health state of the associated backend service.

Composite health check

A composite health check is a resource that aggregates the health states of one or more health sources to produce a single composite health state for a regional published service. The published service is considered healthy if each of the associated health sources are healthy. If any of the health sources are unhealthy, the service is considered unhealthy.

Health destination

A health destination receives the final composite health state from a composite health check. For a published service, the health destination is the forwarding rule of the producer's load balancer. The health state is automatically propagated to consumer load balancers that connect to this forwarding rule.

Specifications

Composite Health has the following specifications.

  • Behavior:

    • The health of individual backends within a backend service is determined by standard health checks.
    • A configurable health aggregation policy determines the overall health state of a backend service based on the health of its individual backends.
    • A composite health check aggregates the health states from one or more backend services that are configured as health sources, creating a composite health state.
    • The composite health state is provided to a health destination, which must be the forwarding rule of a published service.
    • The composite health state is automatically propagated to connected consumer load balancers, where unhealthy states trigger automatic cross-region failover.
    • By default, health state transitions are recorded by Cloud Logging. Producers can view logs for health sources and composite health checks. Consumers can view logs for Private Service Connect NEGs that connect to published services that use Composite Health. For more information, see Monitor Composite Health.

  • Configuration:

Health states

Composite Health uses the following states to represent the health of published services and backend services.

Health state Monitored resource Description
HEALTHY Health source The associated backend service is healthy as defined by its health aggregation policy.
Composite health check The published service is healthy because each of its associated health sources is healthy.
Private Service Connect NEG The associated published service is healthy as defined by the producer's composite health check.
UNHEALTHY Health source The backend service does not meet the criteria defined by its health aggregation policy.
Composite health check The published service is unhealthy because one or more of the associated health sources are unhealthy.
Private Service Connect NEG The associated published service is unhealthy as defined by the producer's composite health check; this status can trigger cross-region failover.
UNKNOWN Health source The health state is not available yet. This is a transient state that occurs when resources are newly created or configured.
Composite health check No associated health sources are unhealthy, but one or more health sources are unknown.
Private Service Connect NEG The health state of the associated published service is not available yet.

Limitations

Composite Health has the following limitations:

  • Composite Health is supported only for resources—including producer forwarding rules, service attachments, and Private Service Connect NEGs—created after October 20, 2025. If you configure Composite Health for resources created before this date, the composite health status might not be correctly recognized. If you need composite health status for resources created before October 20, 2025, you must recreate the resources.
  • All Composite Health resources, including the backend services and forwarding rules they reference, must exist in the same project.
  • You can't use the composite health state of one service as a health source for another service.
  • There is no mode to test a health check configuration that doesn't affect connected consumers. Any configured composite health checks can immediately trigger failover.
  • Composite Health only supports Private Service Connect backends that access published services.

Pricing

For information about pricing, see VPC pricing.

What's next