gRPC Health Check: Multi-Language Guide with K8s Probes
Key takeaways
- A gRPC health check uses the standard grpc.health.v1 Health service, so probes test the real handler and dependencies instead of guessing with a TCP dial or HTTP ping.
- The protocol supports a unary Check RPC for polling and a server-streaming Watch RPC, plus per-service statuses so one port can report different health for different services.
- Go, Java/Spring, and ASP.NET Core all ship built-in health server implementations you register and wire to real dependency checks like database connectivity.
- Kubernetes 1.24+ supports a native grpc probe type, while older clusters use an exec probe running the grpc_health_probe binary inside the container image.
- UNIMPLEMENTED means no health service is registered, connection refused means a binding or port issue, and NOT_SERVING means your own code reported a dependency failure.
A grpc health check is a standard protocol where your gRPC service answers a Health/Check RPC with SERVING, NOT_SERVING, or UNKNOWN, so probes test the actual port and handler instead of guessing with a TCP dial or HTTP ping. This guide gives you working server code in Go, Java, and ASP.NET Core, grpc_health_probe CLI commands, Kubernetes liveness and readiness YAML, and fixes for the UNIMPLEMENTED, connection refused, and NOT_SERVING failures you will hit.
grpc health check: what it is and why URL pings are not enough
A gRPC health check is a standard RPC defined in the gRPC health checking protocol: your service exposes a grpc.health.v1.Health service that answers Check requests with a status like SERVING or NOT_SERVING. That status comes from your application's own logic, not just whether the port is open.
A TCP or HTTP ping only proves the process is listening. A gRPC service can accept connections, then fail every real request because its database pool is exhausted, a dependency is down, or the binary was deployed with a broken constructor. The port stays green while every customer call fails.
The protocol also supports Watch, which streams status changes instead of forcing you to poll. We cover the watch semantics in our guide to gRPC health checks, probing, and watch protocols.
What is the gRPC health checking protocol and how does it work?
The grpc.health.v1 standard defines a health service every gRPC server can expose, so any client or probe asks one consistent question: "are you serving?" It replaces ad-hoc HTTP pings that never touch your actual gRPC port. For a deeper reference, see the guide to the grpc.health.v1 standard.
The Check RPC
Check is a unary call: the client sends a HealthCheckRequest and gets back a status of SERVING, NOT_SERVING, or UNKNOWN. Kubernetes liveness and grpc_health_probe both use this.
The Watch RPC and streaming state changes
Watch is server-streaming: the client subscribes once and receives every future state change without polling. Useful for load balancers pulling instances out of rotation the moment health flips.
Per-service vs overall health
The request's service field targets one service behind the same port, or an empty string for overall server health. A database-backed service can report NOT_SERVING while the rest of the server stays SERVING.
How do you implement a gRPC health check server in Go, Java, and ASP.NET Core?
All three ecosystems ship a health server that implements the standard grpc.health.v1.Health service, so the work is registering it and wiring your real dependencies into the status. The pattern is identical everywhere: start the health service, set it to SERVING once your app is ready, and flip it to NOT_SERVING when a critical dependency (database, queue, cache) fails.
Go: grpc_health_v1 with a custom health server
Go's google.golang.org/grpc/health package gives you a working server in a few lines. Register it with grpc_health_v1.RegisterHealthServer, call SetServingStatus per service name, and use a SetWatch-style goroutine that pings Postgres every few seconds and downgrades the status on failure. The important detail: use named services ("myapp.api") rather than only the empty-string service, so one process can report different statuses for different gRPC services it hosts.
Java/Spring: Actuator gRPC health integration
If you run gRPC-Spring-Boot-Starter, add the grpc-services dependency and register the HealthStatusManager bean. Bridge Spring Actuator's HealthIndicator beans into it: a custom HealthContributor that checks your database can call healthStatusManager.setStatus(SERVICE_NAME, HealthCheckResponse.ServingStatus.SERVING) on recovery. This keeps one source of truth for health across REST and gRPC endpoints.
ASP.NET Core: Grpc.AspNetCore.HealthChecks
The Grpc.AspNetCore.HealthChecks NuGet package maps.NET's existing IHealthCheck registrations onto the gRPC protocol. Add builder.Services.AddGrpcHealthChecks().AddNpgSql(connString), then MapGrpcHealthChecksService() in the pipeline. Your existing EF Core or Npgsql checks now answer gRPC probes with zero extra code.
What "healthy" should actually mean
The mistake most teams make is treating the health service as a heartbeat rather than a verdict. A heartbeat only proves the process is alive; a verdict proves the process can do its job. If your service depends on Postgres and the connection pool is exhausted, returning SERVING is a lie that turns a 10-second incident into a 30-minute one, because Kubernetes keeps routing traffic to a pod that accepts connections and then fails every request. Tie each named health service to the dependency it actually serves: the API service reports NOT_SERVING when the database is unreachable, while a background worker service might stay SERVING through the same outage because it degrades to a retry queue instead. This is also why protocol-level probes beat URL checks: a grpc_health_probe call exercises the real HTTP/2 transport, serialization, and handler path, which we cover in our guide to gRPC health monitoring over HTTP/2 and HTTP/3.
Verify each implementation from the CLI before wiring it into Kubernetes: install grpc_health_probe and run grpc_health_probe -addr=:50051 -service=myapp.api against each named service.
How do you use grpc_health_probe to test a gRPC service from the CLI?
Install and basic usage
Grab the binary from the grpc-health-probe releases page and drop it on your PATH. Then point it at any service that implements the health protocol from the previous section:
grpc_health_probe -addr=localhost:50051
A SERVING response prints and exits 0. If the service reports NOT_SERVING or nothing at all, you get a non-zero exit and a one-line reason.
TLS and -tls flags
For endpoints behind TLS, add -tls and optionally -tls-ca-cert to trust a private CA:
grpc_health_probe -addr=api.example.com:443 -tls -tls-ca-cert=./ca.pem
Skip -tls-ca-cert for endpoints with publicly trusted certs.
Exit codes for scripting
Exit 0 means healthy, 1 means the check failed (connection refused, timeout, NOT_SERVING), and other non-zero codes signal usage errors. That makes it a drop-in CI gate:
grpc_health_probe -addr=localhost:50051 || exit 1
Wire the same command into a smoke-test job after deploys, and pair it with external probes so failures surface even when the cluster itself is unreachable. For what to probe beyond the binary's pass/fail, see database health checks.
How do you wire gRPC health checks into Kubernetes liveness and readiness probes?
Exec probe with grpc_health_probe
The classic approach ships the grpc_health_probe binary in your image and calls it via exec:
livenessProbe:
exec:
command: ["/bin/grpc_health_probe", "-addr=:50051"]
initialDelaySeconds: 10
periodSeconds: 15
readinessProbe:
exec:
command: ["/bin/grpc_health_probe", "-addr=:50051"]
initialDelaySeconds: 5
periodSeconds: 10
Readiness runs more often than liveness so the kubelet notices recovery quickly without killing the pod.
Native gRPC probes (Kubernetes 1.24+)
If your cluster runs Kubernetes 1.24 or newer, skip the binary and use the built-in grpc probe type: grpc: port: 50051. This works only if your server implements the standard health protocol over plaintext (or you configure TLS), and it removes the exec overhead per check. The Kubernetes pod probe documentation covers both probe types.
Liveness vs readiness: avoiding restart storms
Liveness failures restart the container, so keep thresholds generous: 3-5 failures before restart. Use readiness for anything recoverable, like a NOT_SERVING state while a dependency catches up. The same semantic distinction applies outside the cluster, as we cover in GraphQL API health checks.
What is the difference between SERVING, NOT_SERVING, and UNKNOWN health states?
The protocol defines three states your server reports, and each one should trigger a different reaction from your probes.
| State | Meaning | Probe reaction |
|---|---|---|
| SERVING | Service can handle requests now | Liveness and readiness pass |
| NOT_SERVING | Service is up but cannot take traffic | Readiness fails, liveness passes |
| UNKNOWN | State not yet determined, or service does not track it | Treat as failure; restart only on repeated UNKNOWN |
Report NOT_SERVING when dependencies are down but the process is healthy, so Kubernetes pulls the pod from endpoints without restarting it. Reserve liveness failures for cases where a restart would actually help. UNKNOWN usually means the client and server disagree on the health service version, or the server has not finished initializing. If your checks return UNKNOWN persistently, that is a configuration bug, not a transient state.
Why does my health check return UNIMPLEMENTED or connection refused, and how do I fix it?
UNIMPLEMENTED means your server has no health service registered. The client reached the process, but nothing answered the grpc.health.v1.Health/Check path. Fix it by registering the health server before grpc.NewServer starts serving: in Go, healthpb.RegisterHealthServer(s, healthServer) from the grpc-go health package. If you registered it but still see UNIMPLEMENTED, check that the service name string passed to SetServingStatus matches what grpc_health_probe sends (empty string for overall health).
Connection refused means nothing is listening on that host and port. Usual causes: the container binds to localhost instead of 0.0.0.0, the port isn't exposed in the pod spec, or you're probing a TLS port with a plaintext client.
NOT_SERVING is different: the health service works, but your code called SetServingStatus(..., NOT_SERVING). That's your app reporting a dependency failure, not a probe bug.
How do you monitor gRPC health checks externally beyond in-cluster probes?
Kubernetes probes only tell you what the cluster thinks. If your ingress, DNS, or region fails, kubelet still reports SERVING while customers see downtime. SLA reporting needs an outside vantage point.
External probes that speak the gRPC health protocol solve this: they dial your public endpoint, issue a real Check RPC, and record the actual state a customer experiences. That catches TLS misconfigurations, port mapping errors, and regional outages that URL pings miss entirely.
This is why we built StatusPulse: protocol-level gRPC probes plus a public status page, from $5/mo, against Statuspage's $29-199/month pricing (ossalt.com). Free tier: 5 probes, 1 page.
Honest limits: StatusPulse runs from fewer regions than Better Stack or UptimeRobot, has no PagerDuty integration yet, and won't replace in-cluster probes. Use both.
FAQ
Does grpc_health_probe work with TLS or mutual TLS services?
Yes. Add -tls to probe a TLS endpoint, and pass -tls-ca-cert to trust a private CA. Skip the CA flag when the server uses a publicly trusted certificate. The binary does not handle client certificates, so mutual TLS setups need a custom probe client that presents a cert.
Can I check the health of a specific gRPC service instead of the whole server?
Yes. The HealthCheckRequest.service field targets one service behind the same port, and an empty string means overall server health. Register a named status per service, then probe it with grpc_health_probe -service=myapp.api. A database-backed service can report NOT_SERVING while the rest of the server stays SERVING.
How often should Kubernetes probe my gRPC service without hurting performance?
Run readiness more often than liveness: every 10 seconds for readiness, every 15 for liveness is a reasonable baseline. Keep liveness thresholds generous, 3-5 failures before a restart, so a brief dependency blip does not trigger a restart storm. Native gRPC probes avoid exec overhead per check.
Is there a native gRPC Kubernetes probe or do I need the exec binary?
Kubernetes 1.24 and newer supports a native grpc probe type, so you can set grpc: port: 50051 and skip shipping the grpc_health_probe binary entirely. The native probe requires the standard health protocol over plaintext, or TLS configuration. Older clusters need the exec approach with the binary in your image.
How do I expose gRPC health status on a public status page for customers?
In-cluster probes only tell the kubelet what it sees, so pair them with external probes that dial your public endpoint and issue a real Check RPC. StatusPulse runs protocol-level gRPC probes and publishes results on a public status page, from $5/mo, with a free tier of 5 probes and 1 page.