Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 3 · Lesson 20 · 3 min read

gRPC Health Checks and Server Reflection

On this page
  1. Why gRPC services need health checks
  2. The standard gRPC health service
  3. How Kubernetes and load balancers use gRPC health checks
  4. gRPC server reflection
  5. Health checks and reflection in production
  6. Check yourself

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

Code
hs := health.NewServer()
healthpb.RegisterHealthServer(srv, hs)
hs.SetServingStatus("shop.v1.OrderService", healthpb.HealthCheckResponse_SERVING)

Checked with grpcurl:

Code
grpcurl -plaintext -d '{"service":"shop.v1.OrderService"}' 127.0.0.1:50051 grpc.health.v1.Health/Check
JSON
{
  "status": "SERVING"
}
  • Check returns the status for a service name, or for the whole server with an empty name.
  • Watch streams status changes, so clients learn about problems without polling.
  • Statuses: SERVING, NOT_SERVING, UNKNOWN (or SERVICE_UNKNOWN for 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()).

The health service reports serving status to load balancers and Kubernetes probes; reflection describes the server's services so tools like grpcurl can call them without .proto files.
The health service reports serving status to load balancers and Kubernetes probes; reflection describes the server's services so tools like grpcurl can call them without .proto files.

How Kubernetes and load balancers use gRPC health checks

  • Kubernetes supports gRPC probes natively (since version 1.27 they're generally available):
YAML
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:

Code
reflection.Register(srv)

Tools can then explore without .proto files:

Code
grpcurl -plaintext 127.0.0.1:50051 describe shop.v1.OrderService
Protobuf
shop.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 .proto files (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.