gRPC Health Checks and Server Reflection
On this page
Why gRPC services need health checks
A load balancer or orchestrator needs to know which backends should receive traffic. "The process is running" isn't enough: a server can be up while its database connection is down. gRPC defines a standard health service, so every tool can ask the same question the same way.
The standard gRPC health service
hs := health.NewServer()
healthpb.RegisterHealthServer(srv, hs)
hs.SetServingStatus("shop.v1.OrderService", healthpb.HealthCheckResponse_SERVING)Checked with grpcurl:
grpcurl -plaintext -d '{"service":"shop.v1.OrderService"}' 127.0.0.1:50051 grpc.health.v1.Health/Check{
"status": "SERVING"
}Checkreturns the status for a service name, or for the whole server with an empty name.Watchstreams status changes, so clients learn about problems without polling.- Statuses:
SERVING,NOT_SERVING,UNKNOWN(orSERVICE_UNKNOWNfor unregistered names).
Update the status from your own checks: set NOT_SERVING when a critical dependency is down, and during shutdown, before you stop accepting calls, so balancers move traffic away while in-flight calls finish (srv.GracefulStop()).
How Kubernetes and load balancers use gRPC health checks
- Kubernetes supports gRPC probes natively (since version 1.27 they're generally available):
readinessProbe:
grpc:
port: 50051
service: shop.v1.OrderService
periodSeconds: 5- Client-side health checking: grpc-go can watch backends' health and skip unhealthy ones with round_robin, enabled through service config (
"healthCheckConfig": {"serviceName": "shop.v1.OrderService"}). - Load balancers and meshes (Envoy, cloud load balancers) can use gRPC health checks.
Keep liveness (restart me if I'm stuck) and readiness (send me traffic) separate: a slow database should make the pod not ready, not restart it.
gRPC server reflection
Server reflection publishes the server's service and message definitions over gRPC itself:
reflection.Register(srv)Tools can then explore without .proto files:
grpcurl -plaintext 127.0.0.1:50051 describe shop.v1.OrderServiceshop.v1.OrderService is a service:
service OrderService {
rpc CreateOrder ( .shop.v1.CreateOrderRequest ) returns ( .shop.v1.CreateOrderResponse );
rpc GetOrder ( .shop.v1.GetOrderRequest ) returns ( .shop.v1.GetOrderResponse );
rpc SupportChat ( stream .shop.v1.SupportChatRequest ) returns ( stream .shop.v1.SupportChatResponse );
rpc UploadItems ( stream .shop.v1.UploadItemsRequest ) returns ( .shop.v1.UploadItemsResponse );
rpc WatchOrder ( .shop.v1.WatchOrderRequest ) returns ( stream .shop.v1.WatchOrderResponse );
}grpcurl, Postman, Kreya, grpcui and Evans all use reflection.
Health checks and reflection in production
- Health: always on.
- Reflection: valuable for debugging, but it reveals your full API surface. Enable it on internal endpoints, behind authentication, or only in non-production environments, depending on your threat model. Without it, tools need the
.protofiles (grpcurl -proto ...). - Don't put business data behind health endpoints, and keep them cheap: they're called every few seconds.
Check yourself
The process can be up and accepting connections while a critical dependency, like its database, is down, so it can't serve requests correctly. Health checks should reflect whether it can do its job.
Before it stops accepting calls, so load balancers and clients stop sending new traffic, then GracefulStop lets in-flight calls complete. That makes deploys invisible to callers.
It makes debugging easy, since tools can discover and call methods without the .proto files, but it exposes the full API description to anyone who can reach the endpoint. Many teams enable it only on internal or admin ports.
Kubernetes supports native gRPC probes that call the health service, so liveness and readiness can use it without a separate HTTP endpoint.