Q: How do you expose a gRPC service in Kubernetes?
To expose a gRPC service in Kubernetes, put it behind a Service for in-cluster traffic and an HTTP/2-aware entry point (an Ingress or Gateway API route with TLS, or a Layer 4 load balancer) for external traffic.
Want to master this scenario in a live sandbox? KodeKloud's CKA & CKAD Hands-On Certification Track covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: To <strong>expose a gRPC service in Kubernetes</strong>, put it behind a Service for in-cluster traffic and an HTTP/2-aware entry point (an Ingress or Gateway API route with TLS, or a Layer 4 load balancer) for external traffic. The catch is that gRPC multiplexes many calls over one long-lived HTTP/2 connection, so a plain ClusterIP Service balances connections, not requests, and one pod can end up with all the load. Interviewers ask this to see whether you understand HTTP/2, connection-level versus request-level load balancing, and how ingress controllers treat backend protocols.
Mental model: why gRPC breaks default Service load balancing
kube-proxy balances at Layer 4, which is the wrong granularity for a protocol that reuses one TCP connection for thousands of calls.
- Connection-level balancing: a ClusterIP Service picks a backend pod when a TCP connection is opened. A gRPC client that opens one channel and keeps it will stay pinned to that pod, even after you scale the Deployment out.
- Request-level options: either use client-side load balancing against a headless Service (
clusterIP: None, resolverdns:///, policyround_robin), or place an L7 proxy such as Envoy, NGINX, or a service mesh sidecar that understands HTTP/2 streams. - Protocol hint: set
appProtocolon the Service port.kubernetes.io/h2cmarks cleartext HTTP/2, and many controllers and meshes use it to pick the right behaviour. - External versus internal: east-west traffic is usually solved by headless Service plus client balancing or a mesh; north-south traffic needs an ingress, Gateway, or load balancer that speaks HTTP/2 end to end.
Hands-on: expose a gRPC service in Kubernetes with a Service
Declare the port as gRPC-capable and, for client-side balancing, add a headless twin of the Service.
apiVersion: v1
kind: Service
metadata:
name: my-grpc
namespace: prod
spec:
selector:
app: my-grpc
ports:
- name: grpc
port: 50051
targetPort: 50051
appProtocol: kubernetes.io/h2c
---
apiVersion: v1
kind: Service
metadata:
name: my-grpc-headless
namespace: prod
spec:
clusterIP: None # DNS returns all pod IPs
selector:
app: my-grpc
ports:
- name: grpc
port: 50051
- Named port and appProtocol: expose the container port with a name and set
appProtocol: kubernetes.io/h2c(orhttpswhen the pod terminates TLS itself). - Headless Service:
clusterIP: Nonemakes DNS return every ready pod IP, so the gRPC resolver can open one subchannel per pod. - Readiness matters: only Ready pods are published in the endpoints, so pair this with a proper gRPC readiness probe.
- Client config: in grpc-go use a target like
dns:///my-grpc-headless.prod.svc.cluster.local:50051with theround_robinservice config. Resolvers re-resolve on a timer, so new pods are picked up slowly; set a max connection age on the server to force reconnects.
Expose it externally: Ingress, Gateway API or a load balancer
Pick the entry point based on whether you need L7 routing, TLS termination and host-based rules.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-grpc
namespace: prod
annotations:
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
spec:
ingressClassName: nginx
tls:
- hosts: [grpc.example.com]
secretName: grpc-example-tls
rules:
- host: grpc.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: my-grpc
port:
number: 50051
- ingress-nginx: add
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"(useGRPCSif the backend speaks TLS). gRPC over the controller requires HTTP/2, which in practice means the Ingress must have atlssection. - Gateway API: the
GRPCRoutekind is part of the standard channel from Gateway API v1.1 onward and lets you match on service and method. Confirm your controller implements it before relying on it. - Layer 4 alternative: a
type: LoadBalancerService or NLB passes the TCP stream through. It is simple and fast but gives no per-request balancing and no path routing. - Timeouts: long-lived streaming RPCs need generous proxy read and send timeouts, otherwise the proxy resets streams that are merely idle.
Verify with grpcurl and read the failure signals
Test with a real gRPC client, because curl over HTTP/1.1 tells you nothing about the HTTP/2 path.
# in-cluster test without exposing anything
kubectl -n prod port-forward svc/my-grpc 50051:50051 &
grpcurl -plaintext localhost:50051 list
# external test
grpcurl grpc.example.com:443 grpc.health.v1.Health/Check
- List services:
grpcurl grpc.example.com:443 listworks only if server reflection is enabled; otherwise pass-protofiles. - Call a method:
grpcurl -d '{"name":"test"}' grpc.example.com:443 my.pkg.Greeter/SayHello. - Check distribution: hit the endpoint in a loop and compare per-pod request counters or logs to confirm requests are spread, not pinned.
- Typical errors:
Unavailablewith a 502 often means the ingress spoke HTTP/1.1 to the backend;Unimplementedmeans the path or service name is wrong; TLS handshake errors mean a hostname or certificate mismatch.
Production practice: health, mesh and graceful shutdown
Reliability for gRPC depends on connection lifecycle as much as on routing.
- Health probes: use the native
grpcprobe or the health protocol so Ready means the gRPC server is actually serving. - Graceful shutdown: handle SIGTERM with
GracefulStop()(or the equivalent) and setterminationGracePeriodSecondslong enough to drain streams. - Connection recycling: configure max connection age with a grace period on the server so clients rebalance after scale-out.
- Mesh option: Istio and Linkerd balance gRPC per request out of the box, at the cost of sidecar or ambient-mode overhead.
- A gRPC service is HTTP/2 over long-lived connections, so I expose it through an HTTP/2-aware ingress, Gateway or L4 load balancer.
- I avoid connection pinning with a headless Service and round_robin client balancing, or an L7 proxy or mesh, and verify with grpcurl and per-pod metrics.
- I automate native gRPC probes, graceful shutdown and max connection age so rollouts and scale-outs do not drop streams.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Relying on a ClusterIP Service to spread gRPC traffic kube-proxy balances per connection, so a single long-lived channel keeps hitting one pod and new replicas stay idle.
- Creating an NGINX Ingress for gRPC without TLS or the backend-protocol annotation The controller then talks HTTP/1.1 or plaintext to the backend and clients see 502 or Unavailable errors.
- Testing with curl instead of grpcurl curl over HTTP/1.1 cannot prove the HTTP/2 path, trailers and framing that gRPC needs.
- Leaving default proxy timeouts on streaming RPCs Idle bidirectional streams get reset mid-session when proxy read timeouts expire.