Performing health checks

Active health check

Apigee exposes active health checks at different levels, which you can leverage depending upon the use case.

1. Regional-level / Apigee instance health check: Returns the health of overall Apigee instance in a region.
2. Environment-level health checks: Returns the health of a particular environment in the Apigee instance.
3. Custom health check through an API proxy: For complex use cases, you can configure a dedicated API proxy as a custom health check endpoint.

Performing a regional-level health check

Apigee offers a regional-level / Apigee instance health check to assess the overall health status of the Apigee instance in a specific region. This health check pattern, widely used by load balancers, determines the health status of Apigee instances and performs regional failovers. You can perform a regional-level health check by constructing the request as follows:

• Health check path: /healthz/ingress
• Add request header: User-Agent: GoogleHC.

$ curl -H 'User-Agent: GoogleHC' https://$HOST/healthz/ingress
Apigee Ingress is healthy

Performing an environment-level health check

Apigee offers an environment-level health check to assess the health of a particular environment served by the Apigee instance. This health check pattern is preferred when you want to perform regional failovers based on the health of certain critical/selective environments. You can perform an environment-level health check by calling any valid API proxy in an environment by constructing the request as follows:

• Prepend /healthz/ to the proxy basepath.
• Add request header: User-Agent: GoogleHC.

For example, assume that /catalog is a valid proxy basepath that is deployed in an environment. To do a health check, call the proxy like this:

$ curl -H 'User-Agent: GoogleHC' https://$HOST/healthz/catalog
Server Ready

Performing a custom health check through an API proxy

If you want to perform any additional validations, you can define custom health check logic in an API proxy deployed to an environment. For example, you might fail the healthcheck when multiple environments are down. Or, you could fail the healthcheck based on target health or latency.

In this case, you can perform the health check by making a regular API call to that proxy.

For example, assume that you want to check the health of an environment called prod. Deploy an API proxy to that environment with the basepath /healthcheck-prod. To check the health of the prod environment served by Apigee instance, call the proxy like this:

$ curl https://$HOST/healthcheck-prod

Usage notes

For regional-level and environment-level healthchecks: If they are performed by the Google Cloud load balancers, the load balancer sets the correct User-Agent header. If your own client consumes these health check API calls, you need to make sure the correct User-Agent is set.

For Apigee hybrid: The health check feature is only available for version 1.4 and higher.

PSC health check

Apigee supports health checking with Private Service Connect (PSC), enabling automatic cross-region failover for multi-region deployments. If you have multiple Apigee instances across multiple regions, you can opt in to PSC health checks so that traffic automatically fails over to a healthy region when the Apigee instance in the active region becomes unhealthy. No request from your client or load balancer is required to trigger the check. Google Cloud monitors the instance continuously on your behalf and updates the health state automatically.

The PSC health check feature is configured on the Apigee backend. You do not need to deploy any additional resources, write any code, or change your API proxies.

Prerequisites

• You have an Apigee Pay-as-you-go or Subscription organization.
• Your organization has two or more Apigee instances, each in a different Google Cloud region.
• Your client traffic reaches Apigee through Private Service Connect (PSC).
• Every environment, environment group, API proxy, shared flow, and resource is deployed identically across all Apigee instances that participate in failover. Inconsistent deployments can cause unexpected behavior when traffic shifts between regions.

How to enable

PSC health check is an opt-in feature managed by Google. To request enablement for your organization, contact your Apigee account team or Apigee Support. If enabled, automatic regional failover is active for all instances in your organization. No further configuration is required.

Testing recommendations

Because PSC health check introduces immediate, automatic regional failover that directly affects traffic routing, we recommend that you test the feature in a non-production Apigee environment before enabling it for your production organization. Verify that failover and recovery behave as expected for your API traffic patterns and that your client applications handle the transition transparently.

To simulate a failover scenario and validate your setup, contact your Apigee account team or Apigee Support. The team can assist you in inducing failure conditions in a controlled environment so that you can observe the failover behavior before enabling the feature in production.

How failover works

When PSC health check determines that the Apigee instance in your active region is unhealthy, client traffic is immediately and automatically routed to a healthy Apigee instance in another region. When the unhealthy instance recovers, traffic returns to the original region. The failover and recovery happen transparently to your client applications.

Current limitations

• PSC health check currently detects only complete regional infrastructure outages. It does not trigger on incidents where traffic can still flow, even if the traffic is degraded in error rates or latency. Broader component-level health checking is planned for a future release.

Verifying health state in Cloud Logging

You can observe the per-region health status events for your Apigee instances in Cloud Logging. In the Logs Explorer for the Google Cloud project that hosts your Apigee organization, run the following filter:

resource.type="compute.googleapis.com/NetworkEndpointGroupV2"

For more information, see Monitor composite health check logs.

For each region, look at the healthState field on the matching log entries. A value of HEALTHY indicates that the Apigee instance in that region is reachable and serving traffic. Other values indicate that PSC health check is not currently routing traffic to that region.