NGINX Zero-Downtime Reload & Binary Upgrade Prompt
Apply NGINX config and binary changes with zero dropped connections — safe reload workflow, graceful worker draining, on-the-fly binary upgrades with USR2/QUIT, and a rollback plan when a reload goes wrong.
- Target user
- Engineers changing production NGINX config without downtime
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior operations engineer who changes production NGINX without dropping traffic. You understand the master/worker signal model and the difference between reload, restart, and binary upgrade. I will provide: - What I'm changing (config only, or the NGINX binary/module too): [DESCRIBE] - The traffic profile — short HTTP requests, or long-lived connections (WebSocket, SSE, streaming, large uploads)?: [DESCRIBE] - How NGINX is managed (systemd, raw master process, container): [DESCRIBE] - My current `worker_shutdown_timeout` / graceful settings, if any: [PASTE] - Whether this is behind a load balancer that can drain the node: [YES/NO] Give me a safe procedure: 1. **Validate first** — `nginx -t` (and `nginx -T` to dump the effective config) as a hard gate. Explain why a failed reload is safe (old workers stay) but a failed restart is not (service down). 2. **Config reload** — the exact reload command for MY management method (`nginx -s reload`, `systemctl reload nginx`, or `kill -HUP <master>`), and what happens to old vs new workers. 3. **Graceful draining** — how old workers finish in-flight requests, the role of `worker_shutdown_timeout`, and what happens to long-lived connections. Recommend a timeout for MY traffic and note the tradeoff. 4. **Binary/module upgrade** — the on-the-fly upgrade dance with `USR2` (start new master), verify, then `WINCH`/`QUIT` to drain and retire the old master — with the exact PID/signal steps and how to abort back to the old binary if the new one misbehaves. 5. **Load-balancer draining (if applicable)** — how to pull the node out of rotation, reload, verify, and add it back, so no user ever hits a mid-reload node. 6. **Rollback** — the precise steps to revert config and reload, and to fall back to the previous binary, if something breaks. Output: (a) a numbered runbook for MY exact scenario; (b) the signal/command reference (`HUP`, `USR2`, `WINCH`, `QUIT`, `TERM`) with what each does; (c) verification at each step (`nginx -t`, `ps` for master/worker PIDs, `stub_status`, a smoke `curl`); (d) the rollback path. Emphasize `nginx -t` before every 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
The dangerous myth is that “restarting NGINX” applies config. A reload on a broken config is safe — the old workers keep serving — but a stop/start on a broken config leaves you hard down. The prompt makes nginx -t a gate and teaches the reload-vs-restart distinction, which is the difference between a non-event and an outage.
Graceful draining is where long-lived connections bite. A reload spawns new workers and asks old ones to finish, but WebSockets and streaming responses can pin old workers indefinitely unless worker_shutdown_timeout forces them closed — and forcing them closed drops those users. By stating your traffic profile, you get a timeout recommendation tuned to your reality instead of the default.
The on-the-fly binary upgrade (USR2 → verify → QUIT) and the load-balancer drain give you two independent zero-downtime paths, each with a concrete rollback. Verifying master/worker PIDs and a smoke curl at each step turns “I think the reload worked” into something you confirmed.
Related prompts
-
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.
-
NGINX Custom Error Pages & Fallback Prompt
Design clean custom error pages and graceful fallbacks in NGINX — branded 404/50x pages, an upstream-down maintenance page, and error interception that doesn't leak backend errors or break API JSON responses.
-
NGINX GeoIP2 Country Access Control Prompt
Add country- or ASN-based access control and routing to NGINX with the ngx_http_geoip2 module — allow/deny by country, route regional traffic, and set headers — while correctly resolving the real client IP behind a CDN or load balancer.
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.