NGINX Stream (TCP/UDP) Load Balancing Prompt
Load-balance non-HTTP traffic through NGINX's stream module — TCP services like databases and message brokers, or UDP like DNS and syslog — with health checks, PROXY protocol, timeouts, and TLS passthrough or termination.
- Target user
- Engineers balancing L4 TCP/UDP services with NGINX stream
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior infrastructure engineer who load-balances L4 (TCP/UDP) services through NGINX's stream module. You know the stream context is separate from http and has its own directives and limits.
I will provide:
- `nginx -V` output (to confirm `--with-stream` and TLS support): [PASTE]
- The service being balanced and protocol (TCP or UDP): [e.g. Postgres/TCP, DNS/UDP, MQTT/TCP]
- The backend nodes as host:port: [LIST]
- Whether TLS should be passed through untouched, terminated at NGINX, or added by NGINX: [DESCRIBE]
- Whether backends need the real client IP (PROXY protocol): [YES/NO]
Design the stream config:
1. **Top-level stream block** — a `stream { upstream ... { } server { listen ...; proxy_pass ...; } }` at the correct top level (not inside http). For UDP, include `listen <port> udp;` and set `proxy_responses`/`proxy_timeout` appropriately.
2. **Load-balancing method** — choose round-robin, `least_conn`, or `hash $remote_addr consistent` based on whether the service needs session affinity; explain the choice for MY protocol.
3. **Health & resilience** — passive checks (`max_fails`, `fail_timeout`) for OSS, or active `health_check` if I'm on Plus; plus `proxy_connect_timeout` and `proxy_timeout` sized for the service.
4. **Client IP preservation** — if backends need the real source IP, enable PROXY protocol (`proxy_protocol on` toward backends that understand it) and note what must change on the backend to accept it.
5. **TLS handling** — passthrough (`proxy_pass` to a TLS backend, no termination), termination (`ssl_preread` for SNI routing, or `listen ... ssl` with certs), or origination toward the backend — whichever I asked for, with the exact directives.
6. **Logging** — a stream `log_format` + `access_log` (stream logging is opt-in and looks different from http).
Output: (a) the complete `stream {}` block, commented; (b) which nginx build/module requirements apply; (c) how to test — `nc`/`psql`/`dig` against the listener and how to confirm balancing and failover; (d) `nginx -t` verification. Apply only after `nginx -t` passes and reload.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
Most stream-module mistakes are structural: engineers try to configure TCP/UDP balancing inside http {}, or run it on a build without --with-stream, and the config either errors or silently does nothing HTTP-like. The prompt anchors everything in a top-level stream {} block and makes you verify the module with nginx -V first.
UDP and TCP need different care — UDP is connectionless, so proxy_responses and proxy_timeout govern how NGINX decides a “session” is done, while TCP cares about connection draining and affinity. By stating the protocol and whether affinity matters, you get the right balancing method (least_conn, consistent hash) instead of a generic round-robin that breaks sticky protocols.
TLS is the other fork: passthrough, termination, and ssl_preread-based SNI routing are genuinely different configs. Forcing you to pick one — plus PROXY protocol when backends need the real client IP — produces a config that matches your topology instead of a template that leaks NGINX’s IP to every backend.
Related prompts
-
NGINX Real Client IP Behind a Load Balancer Prompt
Recover the true client IP when NGINX sits behind an L7 load balancer or CDN — configure real_ip / X-Forwarded-For or PROXY protocol with trusted-proxy scoping — so rate limits, geo rules, and access logs stop keying on the load balancer's address.
-
NGINX Upstream Health Checks & Load Balancing Prompt
Design an upstream block with the right load-balancing algorithm, passive health checks, and failover tuning — so a single sick backend stops poisoning your error rate instead of getting quietly removed from rotation.
-
NGINX Canary & Blue-Green Routing Prompt
Design percentage-based canary and blue-green traffic routing in NGINX using split_clients and upstream weighting — with a sticky cohort, an instant rollback path, and a way to force yourself onto the canary for testing.
-
NGINX CORS & Preflight Proxy Prompt
Get correct, secure CORS handling in NGINX for a reverse-proxied API — OPTIONS preflight, Access-Control-* headers, credentials, and per-origin allow-listing — without the classic duplicate-header and wildcard-with-credentials footguns.
More NGINX prompts & error guides
Browse every NGINX prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.