grpc_health_probe: Health Check gRPC Services in CI/K8s
grpc_health_probe calls the standard grpc.health.v1.Health/Check service and exits 0 only when the server reports SERVING.
Kubernetes added native gRPC probes, but grpc_health_probe is still common in CI smoke tests and older clusters as a clean exit-code gate on a gRPC Health endpoint.
What it does
grpc_health_probe connects to -addr, calls grpc.health.v1.Health/Check (optionally for a specific -service), and maps the response to an exit code: 0 for SERVING, non-zero otherwise. It is designed to be used directly as a container liveness/readiness command or a CI assertion.
Common usage
# basic readiness check
grpc_health_probe -addr=localhost:50051
# check a named sub-service over TLS
grpc_health_probe -addr=svc:50051 -service=acme.api.v1.UserService \
-tls -tls-ca-cert=/certs/ca.pem
# Kubernetes readinessProbe (older clusters)
# exec:
# command: ["/bin/grpc_health_probe", "-addr=:50051"]Flags and options
| Flag | What it does |
|---|---|
| -addr <host:port> | Target gRPC endpoint |
| -service <name> | Check a specific service name (default: overall server) |
| -connect-timeout <dur> | Timeout for establishing the connection |
| -rpc-timeout <dur> | Timeout for the Check RPC |
| -tls | Use TLS for the connection |
| -tls-ca-cert <file> | CA certificate to verify the server |
| -tls-no-verify | Skip server certificate verification |
In CI
Use grpc_health_probe as a post-deploy gate or to wait for a service container before running integration tests; its exit code makes it scriptable with a simple retry loop. Modern Kubernetes (1.24+) has a built-in grpc probe type, so prefer that in new manifests and keep grpc_health_probe for CI and older clusters.
Common errors in CI
"timeout: failed to connect service ... connection refused" means the server is not listening yet; add a retry loop. "service unhealthy (responded with "NOT_SERVING")" means the server is up but reporting unhealthy. "error: this server does not implement the grpc health protocol (grpc.health.v1.Health): Unimplemented" means the Health service is not registered in the server.