gRPC is a high-performance RPC framework increasingly used for service-to-service communication. Nginx supports proxying gRPC traffic natively, with some specific configuration differences from standard HTTP proxying.
What Makes gRPC Different from Regular HTTP
gRPC uses HTTP/2 exclusively and has specific framing requirements — standard proxy_pass configuration for HTTP/1.1 backends doesn't correctly handle gRPC's binary protocol; Nginx provides a dedicated grpc_pass directive instead.
Prerequisites
- Nginx 1.13.10 or later (native gRPC support)
- A gRPC backend service
Basic gRPC Proxy Configuration
server {
listen 443 ssl http2;
server_name grpc.yourdomain.com;
ssl_certificate /etc/letsencrypt/live/grpc.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/grpc.yourdomain.com/privkey.pem;
location / {
grpc_pass grpc://backend:50051;
}
}listen ... http2 is required since gRPC depends on HTTP/2; grpc_pass (not proxy_pass) correctly handles the gRPC-specific framing.
Using grpcs:// for TLS to the Backend
location / {
grpc_pass grpcs://backend:50051;
}Use grpcs:// instead of grpc:// if the backend itself also requires TLS for the connection between Nginx and the actual gRPC service.
Setting Appropriate Timeouts
location / {
grpc_pass grpc://backend:50051;
grpc_read_timeout 300s;
grpc_send_timeout 300s;
}gRPC streaming calls can be long-lived — adjust timeouts to match your specific service's expected call duration, similar in spirit to WebSocket timeout considerations.
Load Balancing gRPC Traffic
upstream grpc_backend {
server 10.0.0.10:50051;
server 10.0.0.11:50051;
}
server {
location / {
grpc_pass grpc://grpc_backend;
}
}Passing Metadata/Headers
location / {
grpc_pass grpc://backend:50051;
grpc_set_header X-Real-IP $remote_addr;
}Testing a gRPC Endpoint
grpcurl -plaintext localhost:50051 listA command-line gRPC testing tool, useful for verifying connectivity and available services directly, similar in purpose to how curl is used for testing REST APIs.
Combining gRPC and Regular HTTP on the Same Server
location /api/ {
proxy_pass http://rest_backend;
}
location /grpc/ {
grpc_pass grpc://grpc_backend;
}Different paths can route to entirely different backend types, letting you serve both REST and gRPC APIs from a single Nginx instance.
Common Errors
"upstream sent unexpected content-type" — verify you're using grpc_pass, not the standard proxy_pass, and that http2 is enabled on the listening block.
Streaming calls disconnect prematurely — increase grpc_read_timeout/grpc_send_timeout to accommodate your service's actual expected call duration.
Continue Reading
- How to Enable HTTP/2 and HTTP/3 on Nginx
- How to Configure Nginx for WebSocket Proxying
- How to Build and Secure a REST API on a VPS
Browse more articles in Web Servers.
