NGINX gRPC & HTTP/2 Proxying Prompt
Generate a correct grpc_pass server block that terminates TLS, speaks HTTP/2 to your gRPC backend, and handles trailers and timeouts — instead of a plain proxy_pass that silently mangles streaming RPCs.
- Target user
- Engineers fronting a gRPC service with NGINX for TLS termination or routing
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior infrastructure engineer who has shipped NGINX in front of gRPC services in production. You know that gRPC is HTTP/2-only, that it relies on trailers, and that a stray `proxy_pass` instead of `grpc_pass` will break streaming in ways that look like random hangs.
I will provide:
- The gRPC backend address(es): [DESCRIBE BACKEND host:port OR upstream]
- Whether the backend speaks plaintext h2c or TLS: [h2c / TLS + DETAILS]
- The TLS setup at the edge (terminating here, passthrough, mTLS): [DESCRIBE TLS]
- Which RPC types you use (unary, server-streaming, bidi): [DESCRIBE]
- Max message size and any long-lived streams: [DESCRIBE LIMITS/TIMEOUTS]
Build the config:
1. **Listener** — `listen 443 ssl;` plus `http2 on;` (or the legacy `listen 443 ssl http2;` and tell me which NGINX version each requires). Explain why HTTP/1.1 is not an option for gRPC.
2. **Upstream** — a named `upstream {}` block. If the backend is TLS, show `grpc_pass grpcs://...`; if plaintext, `grpc_pass grpc://...`. Note the scheme difference explicitly.
3. **grpc_pass location** — use `grpc_pass`, not `proxy_pass`. Add `grpc_set_header` for any headers the backend needs and explain that gRPC metadata rides as HTTP/2 headers.
4. **Timeouts and sizes** — `grpc_read_timeout` / `grpc_send_timeout` sized for streaming RPCs, and `client_max_body_size` / `grpc_buffer_size` for large messages. Call out which default would silently truncate a big message.
5. **Error mapping** — show how to return a clean gRPC status via `error_page` and `default_type application/grpc` for the no-backend case, so clients get a proper status, not an HTML 502.
Output: (a) the complete commented `upstream {}` + `server {}` block, (b) a table of every gRPC-specific directive and what breaks without it, (c) a `grpcurl` smoke-test command and the `nginx -t` line. Treat the config as a reviewable artifact: validate with `nginx -t` and reload — do not edit a live prod file in place.
Why this prompt works
gRPC is not “HTTP with protobuf” — it is HTTP/2 with mandatory trailers and long-lived multiplexed streams, and NGINX has a dedicated grpc_pass module precisely because the generic proxy_pass path does not preserve those semantics. The most common production failure is reaching for the proxy directives an engineer already knows, getting working unary calls, and then chasing phantom hangs on streaming RPCs weeks later. By forcing the model to use grpc_pass, declare http2 on, and explain why HTTP/1.1 cannot carry gRPC, the prompt eliminates that entire class of bug up front.
The numbered structure also pins down the two settings people forget until they page someone: streaming timeouts and message-size limits. NGINX’s default read timeout will quietly kill a server-streaming RPC that goes idle, and the default buffer sizes truncate large protobuf messages with an opaque error. Asking for these as explicit, justified directives turns invisible defaults into reviewed decisions.
Finally, the grpcurl smoke test and the directive-explanation table keep a human in the loop. You verify the proxy with a real streaming call rather than trusting that nginx -t passing means the RPCs flow — nginx -t validates syntax, not whether trailers survive the hop.
Related prompts
-
NGINX Reverse-Proxy vhost Design Prompt
Generate a clean, production-ready reverse-proxy server block for your backend app — correct headers, timeouts, keepalive, and WebSocket support — instead of copy-pasting a Stack Overflow snippet that leaks the client IP.
-
NGINX TLS/SSL Hardening Prompt
Harden your NGINX TLS config to a modern, A-grade baseline — protocols, cipher suites, HSTS, OCSP stapling, session settings — without breaking older clients you actually need to support.