Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


ci GitHub all releases

The grpc_health_probe utility allows you to query health of gRPC services that expose service their status through the gRPC Health Checking Protocol.

grpc_health_probe is meant to be used for health checking gRPC applications in Kubernetes, using the exec probes.

⚠️ Kubernetes v1.23 has now introduced built-in gRPC health checking capability as an alpha feature. As a result, you might no longer need to use this tool and use the native Kubernetes feature instead.

This tool can still be useful if you are on older versions of Kubernetes, or using advanced configuration (such as custom metadata, TLS or finer timeout tuning), or not using Kubernetes at all.

This command-line utility makes a RPC to / If it responds with a SERVING status, the grpc_health_probe will exit with success, otherwise it will exit with a non-zero exit code (documented below).


$ grpc_health_probe -addr=localhost:5000
healthy: SERVING
$ grpc_health_probe -addr=localhost:9999 -connect-timeout 250ms -rpc-timeout 100ms
failed to connect service at "localhost:9999": context deadline exceeded
exit status 2


It is recommended to use a version-stamped binary distribution:

  • Choose a binary from the Releases page.

Installing from source (not recommended):

  • Make sure you have git and go installed.
  • Run: go install
  • This will compile the binary into your $GOPATH/bin (or $HOME/go/bin).

Using the gRPC Health Checking Protocol

To make use of the grpc_health_probe, your application must implement the gRPC Health Checking Protocol v1. This means you must to register the Health service and implement the rpc Check that returns a SERVING status.

Since the Health Checking protocol is part of the gRPC core, it has packages/libraries available for the languages supported by gRPC:

[health.proto] [Go] [Java] [Python] [C#/NuGet] [Ruby] ...

Most of the languages listed above provide helper functions that hides implementation details. This eliminates the need for you to implement the Check rpc yourself.

Example: gRPC health checking on Kubernetes

Kubernetes does not natively support gRPC health checking since it does not favor one RPC framework over another. Similarly, HTTP health probes Kubernetes has is not sufficient to craft a valid gRPC request. As a solution, grpc_health_probe can be used for Kubernetes to health-check gRPC servers running in the Pod.

You are recommended to use Kubernetes exec probes and define liveness and/or readiness checks for your gRPC server pods.

You can bundle the statically compiled grpc_health_probe in your container image. Choose a binary release and download it in your Dockerfile:

    wget -qO/bin/grpc_health_probe${GRPC_HEALTH_PROBE_VERSION}/grpc_health_probe-linux-amd64 && \
    chmod +x /bin/grpc_health_probe

In your Kubernetes Pod specification manifest, specify a livenessProbe and/or readinessProbe for the container:

  - name: server
    image: "[YOUR-DOCKER-IMAGE]"
    - containerPort: 5000
        command: ["/bin/grpc_health_probe", "-addr=:5000"]
      initialDelaySeconds: 5
        command: ["/bin/grpc_health_probe", "-addr=:5000"]
      initialDelaySeconds: 10

This approach provide proper readiness/liveness checking to your applications that implement the gRPC Health Checking Protocol.

Health Checking TLS Servers

If a gRPC server is serving traffic over TLS, or uses TLS client authentication to authorize clients, you can still use grpc_health_probe to check health with command-line options:

Option Description
-tls use TLS (default: false)
-tls-ca-cert path to file containing CA certificates (to override system root CAs)
-tls-client-cert client certificate for authenticating to the server
-tls-client-key private key for for authenticating to the server
-tls-no-verify use TLS, but do not verify the certificate presented by the server (INSECURE) (default: false)
-tls-server-name override the hostname used to verify the server certificate

Health checking TLS Servers with SPIFFE issued credentials

If your gRPC server requires authentication, you can use the following command line options and set the SPIFFE_ENDPOINT_SOCKET environment variable.

Option Description
-spiffe use SPIFFE Workload API to retrieve TLS credentials (default: false)

Other Available Flags

Option Description
-v verbose logs (default: false)
-connect-timeout timeout for establishing connection
-rpc-timeout timeout for health check rpc
-rpc-header sends metadata in the RPC request context (default: empty map)
-user-agent user-agent header value of health check requests (default: grpc_health_probe)
-service service name to check (default: "") - empty string is convention for server health
-gzip use GZIPCompressor for requests and GZIPDecompressor for response (default: false)


  1. Start the route_guide example server with TLS by running:

    go run server/server.go -tls
  2. Run grpc_client_probe with the CA certificate (in the testdata/ directory) and hostname override the cert is signed for:

    $ grpc_health_probe -addr \
        -tls \
        -tls-ca-cert /path/to/testdata/ca.pem \ \
        -rpc-header=foo:bar \
    status: SERVING

Exit codes

It is not recommended to rely on specific exit statuses. Any failure will be a non-zero exit code.

Exit Code Description
0 success: rpc response is SERVING.
1 failure: invalid command-line arguments
2 failure: connection failed or timed out
3 failure: rpc failed or timed out
4 failure: rpc successful, but the response is not SERVING
20 failure: could not retrieve TLS credentials using the SPIFFE Workload API

This is not an official Google project.