Use health checks (original) (raw)

Skip to main content

Use health checks

Google Cloud provides health checking mechanisms that determine whether backend instances respond properly to traffic. This document describes how to create and use health checks for load balancers and Cloud Service Mesh.

This page assumes that you are familiar with the following concepts:

Create health checks

Google Cloud lets you create or select a health check when you complete the load balancer's backend configuration in the Google Cloud console.

You can also create a health check independently of load balancer configuration in the Google Cloud console. This is useful if you need to create your health check first, or if you need to use a health check for multiple load balancers. You can create a health check using the Google Cloud console, the Google Cloud CLI, or the REST APIs.

Console

  1. Go to the Health checks page in the Google Cloud console.
    Go to the Health checks page
  2. Click Create a health check.
  3. On the Create a health check page, supply the following information:
    • Name: Provide a name for the health check.
    • Description: Optionally, provide a description.
    • Scope: Select a scope, either Global or Regional,depending on the type of load balancer.
      * If you selected Regional, pick a Region from the drop-down.
    • Protocol: Choose a health check protocol.
    • Port: Provide a port number. When you create a health check in the Google Cloud console, you must specify the port using a port number.
    • Proxy protocol: Optionally, you can append a proxy header to the requests made by the health check probe systems.
    • Request path and Response: For HTTP, HTTPS, and HTTP2 protocols, you can optionally provide a URL path for the health check probe systems to contact. For more information, see Additional flags for HTTP, HTTPS, and HTTP/2 health checks.
    • Request and Response: For TCP and SSL protcols, you can specify an ASCII text string to send and expected text response string. For more information, see Additional flags for SSL and TCP health checks.
    • Check interval: Define the amount of time from the start of one probe to the start of the next one.
    • Timeout: Define the amount of time that Google Cloud waits for a response to a probe. Its value must be less than or equal to the check interval.
    • Healthy threshold: Define the number of sequential probes that must succeed for the VM instance to be considered healthy.
    • Unhealthy threshold: Define the number of sequential probes that must fail for the VM instance to be considered unhealthy.
  4. Click Create.

gcloud

Replace the following:

Terraform

To create a global health check, use thegoogle_compute_health_check resource.

To create a regional health check, use thegoogle_compute_region_health_check resource.

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

API

Modify health checks

You cannot convert a health check to a legacy health check (or the reverse) by modifying the health check. You also cannot change a health check's name or scope (for example, global to regional).

Console

  1. Go to the Health checks page in the Google Cloud console.
    Go to the Health checks page
  2. Click a health check to view its details.
  3. If you need to modify the health check, click Edit, then:
    • Make changes to the parameters as necessary.
    • Click Save.

gcloud

  1. Identify the name and scope of the health check. For instructions, seeList health checks.
  2. Except for a health check's name, protocol, and scope, you can modify any of the common flags, the port specification flags, and other additional flags. To modify an existing health check, use the appropriate compute health-checks updatecommand command. For flags that you omit, preconfigured settings are preserved.
    • Example modification of a global health check: The following command modifies a global HTTP health check named hc-http-port-80 by changing its check interval, timeout, and request path:
      gcloud compute health-checks update http hc-http-port-80 \
      --global \
      --check-interval=20s \
      --timeout=15s \
      --request-path="/health"
    • Example modification of a regional health check: The following command modifies a regional TCP health check in us-west1 namedhc-west1-tcp-ldap by changing its port specification:
      gcloud compute health-checks update tcp hc-west1-tcp-ldap \
      --region=us-west1 \
      --port=631

API

  1. Identify the name and scope of the health check. See Listing health checks for instructions.
  2. Except for a health check's name, protocol, and scope, you can modify any of the common flags, the port specification flags, and other additional flags with these API calls. Use patch API calls to preserve any preconfigured settings that are not explicitly set in the request.

Console

  1. Go to the Health checks page in the Google Cloud console.
    Go to the Health checks page
  2. Click a health check to view its details.

gcloud

To list health checks, use the compute health-checks list command:

After you know the name and scope of a health check, use the compute health-checks describe command to view its current configuration.

API

To list health checks, use these API calls:

To describe a health check's current configuration, use:

Additional flags

This section describes additional flags you can use when creating or modifying a health check. Some flags, such as port specification, must be set by usinggcloud or the API.

Port specification flags

If you create a health check by using the Google Cloud CLI or the API, you have two options to specify the health check's port. The following table shows port specification options for valid load balancer and backend combinations. The term instance group refers to unmanaged instance groups, zonal managed instance groups, or regional managed instance groups.

Each health check can only use one type of port specification.

Product Backend type Port specification options
Regional external passthrough Network Load Balancer Instance groups and supported NEGs --port: Specify a TCP port by number, from 1 to 65535 The --use-serving-port flag is ignored for a health check associated with an internal passthrough Network Load Balancer because backend services for this load balancer don't subscribe to any named ports. This is because they are passthrough load balancers that deliver packets directly to backends instead of creating new connections from the load balancer to the backend.
Target pools Legacy health checks which support the port number (--port) specification.
Internal passthrough Network Load Balancer Instance groups and supported NEGs --port: Specify a TCP port by number, from 1 to 65535 The --use-serving-port flag is ignored for a health check associated with an internal passthrough Network Load Balancer because backend services for this load balancer don't subscribe to any named ports. This is because they are passthrough load balancers that deliver packets directly to backends instead of creating new connections from the load balancer to the backend.
Global external Application Load Balancer Classic Application Load Balancer Regional external Application Load Balancer Cross-region internal Application Load Balancer Regional internal Application Load Balancer Global external proxy Network Load Balancer Classic proxy Network Load Balancer Regional external proxy Network Load Balancer Cross-region internal proxy Network Load Balancer Regional internal proxy Network Load Balancer Cloud Service Mesh Supported NEGs --port: Specify a TCP port by number, from 1 to 65535 --use-serving-port: Use the port of each endpoint in the network endpoint group.
Instance groups --port: Specify a TCP port by number, from 1 to 65535 --use-serving-port: Use the same instance group named port to which the backend service subscribes.

If you omit the port specification while creating the health check, Google Cloud uses the following defaults:

Additional flags for HTTP, HTTPS, and HTTP/2 health checks

In addition to the common flags and port specification, you can use the following optional flags for HTTP, HTTPS, and HTTP/2 health checks. This example creates an HTTP health check named hc-http-port-80 using port 80 with default interval, timeout, and health threshold criteria.

gcloud compute health-checks create HTTP_PROTOCOL hc-http-port-80
COMMON_FLAGS
PORT_SPECIFICATION
--host=HOST
--proxy-header=PROXY_HEADER
--request-path=REQUEST_PATH
--response=RESPONSE

If Google Cloud finds the expected response string anywhere in the first 1,024 bytes of the received response body, and if the HTTP status is 200 (OK), the probe is considered successful.

The --request-path and --response flags modify the success criteria for the health check probe.

Additional flags for SSL and TCP health checks

In addition to the common flags and port specification, you can use the following optional flags for SSL and TCP health checks. This example creates a TCP health check named hc-tcp-3268 using port 3268 with default interval, timeout, and health threshold criteria.

gcloud compute health-checks create tcp hc-tcp-3268
COMMON_FLAGS
PORT_SPECIFICATION
--proxy-header=PROXY_HEADER
--request=REQUEST_STRING
--response=RESPONSE_STRING

The --request and --response flags modify the success criteria for the health check probe. If you use the --response flag, either by itself or in conjunction with the --requestflag, the response returned must exactly match the expected response string.

Additional flag for gRPC health checks

Your backend gRPC server must implement the gRPC health service as described inthe gRPC health checking protocol. Google Cloud sends a HealthCheckRequest message to your backends by calling the Check method of the health service on your backend. The service parameter in the request is set to an empty string unless a gRPC service name is specified.

A gRPC health check can check the status of a gRPC service. You can include a string, up to 1,024 ASCII characters long, that is the name of a particular gRPC service running on a backend VM or NEG. To do this, use the following optional flag for gRPC health checks:

--grpc-service-name=GRPC_SERVICE_NAME

For example, you might have the following services and status that the backend server registers with your backend's gRPC Health service.

If you create a health check against MyPackage.ServiceA, as follows, the health check probe returns HEALTHY, because the service's status is SERVING.

gcloud compute health-checks create grpc MyGrpcHealthCheckServiceA
--grpc-service-name=MyPackage.ServiceA

If you create a health check against MyPackage.ServiceB, the health check probe returns UNHEALTHY because the service's status isNOT_SERVING.

If you create a health check against MyPackage.ServiceC, which is not registered with the gRPC Health service, the health check probe returns the gRPC status NOT_FOUND, which is the equivalent of UNHEALTHY.

If you create a health check against the empty service name, the health check probe returns the status UNHEALTHY, because the empty service name is registered with the status NOT_SERVING.

Legacy health checks

This section describes how to create, modify, and list legacy HTTP and HTTPS health checks. You cannot convert a legacy health check to a health check, and you cannot convert a health check to a legacy health check.

To learn which types of load balancers support legacy health checks, see theLoad balancer guide.

Create legacy health checks

Console

Although the Google Cloud console's health checks page lists and lets you edit both health checks and legacy health checks, you cannot_create_ a new legacy health check from the Google Cloud console's health checks page.

You can create a legacy health check in the Google Cloud console_only while_ creating a target pool-based regional external passthrough Network Load Balancer. To create the legacy health check by itself, use this section's gcloudor API instructions.

gcloud

To create a legacy health check, use the compute http-health-checks createcommand:

gcloud compute LEGACY_CHECK_TYPE create NAME
--description=DESCRIPTION
--check-interval=CHECK_INTERVAL
--timeout=TIMEOUT
--healthy-threshold=HEALTHY_THRESHOLD
--unhealthy-threshold=UNHEALTHY_THRESHOLD
--host=HOST
--port=PORT
--request-path=REQUEST_PATH

Replace the following:

API

Terraform

Modify legacy health checks

Console

  1. Go to the Health checks page in the Google Cloud console.
    Go to the Health checks page
  2. Click a health check to view its details.
  3. Click Edit , make changes, and then click Save.

gcloud

API

Except for a legacy health check's name and type, you can modify any ofthe flags used for its creation. The patchAPI calls preserve any preconfigured settings that are not explicitly set in the patch request.

List legacy health checks

Console

  1. Go to the Health checks page in the Google Cloud console.
    Go to the Health checks page
  2. Click a legacy health check to view its details.

gcloud

  1. To list legacy HTTP health checks, use the compute http-health-checks list command:
    gcloud compute http-health-checks list
    To list legacy HTTPS health checks, use the compute https-health-checks list command:
    gcloud compute https-health-checks list
  2. To describe a legacy HTTP health check, use the compute http-health-checks describecommand, replacing NAME with its name.
    gcloud compute http-health-checks describe NAME
    To describe a legacy HTTPS health check, use the compute https-health-checks describecommand, replacing NAME with its name.
    gcloud compute https-health-checks describe NAME

API

  1. To list legacy health checks:
  2. To describe a legacy health check:

Create required firewall rules

You need to create ingress firewall rules applicable to all VMs being load balanced to allow traffic from health check prober IP ranges. The following example creates a firewall rule that is applicable to VM instances identified by a specific target tag.

This example allows all TCP traffic from Google Cloud health check systems to your VM instances. (TCP traffic includes SSL, HTTP, HTTPS, and HTTP/2 traffic.) If you prefer, you can specify ports along with the TCP protocol; however, if you specify ports, your firewall rules might become specific to a particular health check. If you use tcp:80 for the protocol and port, this allows TCP traffic on port 80, so Google Cloud could contact your VMs using HTTP on port 80, but it couldn't contact them using HTTPS on port 443.

Console

  1. In the Google Cloud console, go to the Firewall policies page.
    Go to Firewall policies
  2. Click Create firewall rule.
  3. On the Create a firewall rule page, supply the following information:
    • Name: Provide a name for the rule. For this example, usefw-allow-health-checks.
    • Network: Choose a VPC network.
    • Priority: Enter a number for the priority. Lower numbers have higher priorities. Be sure that the firewall rule has a higher priority than other rules that might deny ingress traffic.
    • Direction of traffic: Choose ingress.
    • Action on match: Choose allow.
    • Targets: Choose Specified target tags, and then enter tags in the Target tags field. For this example, useallow-health-checks.
    • Source filter: Choose IP ranges.
    • Source IP ranges: Enter the source IP range depending on your load balancer type, traffic type, and health check type. See Probe IP ranges and firewall rules.
    • Allowed protocols and ports: Use tcp and the port configured in your health check. TCP is the underlying protocol for all health check protocols.
    • Click Create.
  4. On each of your instances being load balanced, add the network tagso that this new ingress firewall rule applies to them. This example uses allow-health-checks for the network tag.

gcloud

  1. Use the following gcloud command to create a firewall rule namedfw-allow-health-checks that lets incoming TCP connections, from Google Cloud health check systems, to instances in your VPC network with the allow-health-checks tag. Based on the load balancer type, a different set ofprobe IP ranges and firewall rulesis supported for IPv6 traffic to the backends.
    Replace NETWORK_NAME with the name of your VPC network and replace PORT with the ports used by your load balancer.
    gcloud compute firewall-rules create fw-allow-health-checks \
    --network=NETWORK_NAME \
    --action=ALLOW \
    --direction=INGRESS \
    --source-ranges=SOURCE_IP_RANGE \
    --target-tags=allow-health-checks \
    --rules=tcp:PORT
    The value for SOURCE_IP_RANGE depends on your load balancer type, traffic type, and health check type. See Probe IP ranges and firewall rules.
  2. On each of your instances being load balanced, add the network tagso that this new ingress firewall rule applies to them. This example uses allow-health-checks for the network tag.

Refer to the gcloud firewall rules documentation and the API documentation for more details.

Related documentation:

Associate health checks with load balancers

If you haven't already done so, review the Health checks overview: Select a health check.

To associate a health check with a new load balancer, refer to the setup guide for the respective load balancer. This section describes how to associate a health check with an existing load balancer's backend service.

This section assumes that you have already:

Console

To associate a health check with an existing load balancer:

  1. Go to the Load balancing page in the Google Cloud console.
    Go to the Load balancing page
  2. Click a load balancer to view its details.
  3. Click Edit , and then click Backend configuration.
  4. Choose a health check from the Health check menu.
  5. Click Update.

gcloud

To associate a health check with an existing backend service, follow these steps.

  1. Identify the name and scope of the backend service. The passthrough Network Load Balancers andproxy Network Load Balancers have only one backend service per load balancer. The Application Load Balancers have one or more backend services associated with a single URL map.
    • To list backend services for internal passthrough Network Load Balancers, run the following command.
      gcloud compute backend-services list \
      --region=REGION \
      --filter="loadBalancingScheme=INTERNAL"
    • To list backend services for regional external passthrough Network Load Balancers, run the following command.
      gcloud compute backend-services list \
      --region=REGION \
      --filter="loadBalancingScheme=EXTERNAL"
    • To list backend services for global external proxy Network Load Balancers, run the following command.
      gcloud compute backend-services list \
      --global \
      --filter="loadBalancingScheme=EXTERNAL_MANAGED" \
      --filter="protocol=(SSL,TCP)"
    • To list backend services for classic proxy Network Load Balancers, run the following command.
      gcloud compute backend-services list \
      --global \
      --filter="loadBalancingScheme=EXTERNAL" \
      --filter="protocol=(SSL,TCP)"
    • To list backend services for cross-region internal proxy Network Load Balancers, run the following command.
      gcloud compute backend-services list \
      --global \
      --filter="loadBalancingScheme=INTERNAL_MANAGED" \
      --filter="protocol=(SSL,TCP)"
    • To list backend services for regional external proxy Network Load Balancers, run the following command.
      gcloud compute backend-services list \
      --region=REGION \
      --filter="loadBalancingScheme=EXTERNAL_MANAGED" \
      --filter="protocol=(SSL,TCP)"
    • To list backend services for regional internal proxy Network Load Balancers, run the following command.
      gcloud compute backend-services list \
      --region=REGION \
      --filter="loadBalancingScheme=INTERNAL_MANAGED" \
      --filter="protocol=(SSL,TCP)"
    • To identify backend services for global external Application Load Balancers, classic Application Load Balancers, and cross-region internal Application Load Balancers, first identify a URL map, and then describe the map. URL maps and backend services for these load balancers are always global, regardless of the Network Service Tier. Replace URL_MAP_NAME with the name of the URL map. The backend services used by the load balancer are listed in the response.
      gcloud compute url-maps list \
      --global
      gcloud compute url-maps describe URL_MAP_NAME \
      --global
    • To identify backend services for either a regional external Application Load Balancer or a regional internal Application Load Balancer, first identify a URL map, and then describe the map. Both URL maps and backend services for these load balancers are regional. Replace REGION_LIST with a comma-delimited list of Google Cloud regions to query. ReplaceURL_MAP_NAME with the name of the URL map andREGION with its region. The backend services used by the load balancer are listed in the response.
      gcloud compute url-maps list \
      --regions=REGION_LIST
      gcloud compute url-maps describe URL_MAP_NAME \
      --region=REGION
  2. Identify a health check. See Listing health checks.
  3. Associate a health check with the backend service by using the compute backend-services update command. Each backend service must reference a single health check. In the following commands, replace BACKEND_SERVICE_NAME with the name of the backend service, HEALTH_CHECK_NAME with the name of the health check, and, if necessary REGION with the Google Cloud region of the backend service, the health check, or both.
    • To change the health check for an internal passthrough Network Load Balancer: An internal passthrough Network Load Balancer's backend service is regional. It can reference a global or regional health check. The following example shows a regional health check reference. If you're using a global health check with your internal passthrough Network Load Balancer, use --global-health-checks instead of--health-checks-region.
      gcloud compute backend-services update BACKEND_SERVICE_NAME \
      --region=REGION \
      --health-checks=HEALTH_CHECK_NAME \
      --health-checks-region=REGION
    • To change the health check for a backend service-based regional external passthrough Network Load Balancer: A regional external passthrough Network Load Balancer's backend service is regional. It can reference a regional health check.
      gcloud compute backend-services update BACKEND_SERVICE_NAME \
      --region=REGION \
      --health-checks=HEALTH_CHECK_NAME \
      --health-checks-region=REGION
    • To change the health check for a global external proxy Network Load Balancer, classic proxy Network Load Balancer, global external Application Load Balancer, classic Application Load Balancer, or a cross-region internal Application Load Balancer: Both the backend service and health check are global for these load balancers. Application Load Balancers can reference more than one health check if it references more than one backend service.
      gcloud compute backend-services update BACKEND_SERVICE_NAME \
      --global \
      --health-checks HEALTH_CHECK_NAME \
      --global-health-checks
    • To change the health check for either a regional external Application Load Balancer, a regional external proxy Network Load Balancer, a regional internal Application Load Balancer, or a regional internal proxy Network Load Balancer: Both the backend service and health check are regional. Some load balancers might reference more than one health check if they can reference more than one backend service.
      gcloud compute backend-services update BACKEND_SERVICE_NAME \
      --region=REGION \
      --health-checks=HEALTH_CHECK_NAME \
      --health-checks-region=REGION

API

  1. You can list backend services with thebackendServices.listAPI call.
  2. View health checks.
  3. To associate a health check with a backend service, use one of these API calls:

Associate legacy health checks with target pool-based regional external passthrough Network Load Balancers

To associate a legacy health check with a new regional external passthrough Network Load Balancer, refer to Set up a regional external passthrough Network Load Balancer with a target pool. This section describes how to associate a legacy health check with a target pool-based regional external passthrough Network Load Balancer.

This section assumes that you have already:

Console

To associate a health check with an existing target pool-based regional external passthrough Network Load Balancer:

  1. Go to the Load balancing page in the Google Cloud console.
    Go to the Load balancing page
  2. Click a load balancer to view its details.
  3. Click Edit , and then click Backend configuration.
  4. Choose a legacy health check from the Health check menu. (Only eligible legacy health checks are shown.)
  5. Click Update.

gcloud

To associate a health check with an existing target pool-based regional external passthrough Network Load Balancer:

  1. Identify the target pool(s). A regional external passthrough Network Load Balancer has at least one target pool, and might have a secondary backup pool.
    gcloud compute target-pools list
  2. Identify a legacy health check using the HTTP protocol. View legacy health checks if necessary.
  3. Associate the legacy health check with the target pool(s). In the following commands, replace TARGET_POOL_NAME with the name of the target pool, REGION with its region, andLEGACY_CHECK_NAME with the name of the legacy health check. The legacy health check must use the HTTP protocol.
    • To remove a legacy HTTP health check from a target pool:
      gcloud compute target-pools remove-health-checks TARGET_POOL_NAME \
      --region=REGION \
      --http-health-check LEGACY_CHECK_NAME
    • To add a legacy HTTP health check to a target pool:
      gcloud compute target-pools add-health-checks TARGET_POOL_NAME \
      --region=REGION \
      --http-health-check LEGACY_CHECK_NAME

API

  1. You can list target pools with thetargetPools.listAPI call.
  2. View legacy health checksand identify a legacy HTTP health check.
  3. To associate a legacy HTTP health check with a target pool use the API call targetPools.addHealthCheck.

Check health check status

After you associate a health check with a backend service or a target pool, you can get the instantaneous health check state for the load balancer's backends.

Console

  1. Go to the load balancing summary page.
    Go to the Load balancing page
  2. Click the name of a load balancer.
  3. Under Backend, inspect the Healthy column. Health status is reported for each backend instance group or network endpoint group.

gcloud

API

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-15 UTC.