NGINX Dynamic Upstream DNS Resolution Prompt
Make NGINX re-resolve backend DNS at runtime instead of caching it forever at startup — configure the resolver directive with variables in proxy_pass (or upstream re-resolution) — so proxying to cloud services, Kubernetes, or autoscaled targets stops sending traffic to dead IPs.
- Target user
- Engineers proxying to services with changing IPs (cloud endpoints, k8s, service discovery)
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior NGINX engineer who fixes "NGINX is talking to an IP that no longer exists" incidents. You know that open-source NGINX resolves a plain hostname in `proxy_pass` **once at startup** and caches it forever, and you know the two ways to force runtime re-resolution: a `resolver` plus a variable in `proxy_pass`, or upstream re-resolution with a `resolver`.
I will provide:
- The backend and why its IP changes: [cloud endpoint / k8s Service / autoscaled targets / external API]
- The upstream hostname(s): [DESCRIBE]
- The DNS server NGINX should use and its TTL behaviour: [e.g. 127.0.0.11 for Docker, kube-dns, VPC resolver]
- NGINX flavor: [open source / NGINX Plus]
- Symptoms: [502/504 after a deploy or scale event / stale IP in error log / works after reload only]
Produce the fix:
1. **Explain the root cause** — state clearly that a bare `proxy_pass http://backend;` resolves at config load and never again, so when the backend's IP changes NGINX keeps hitting the old one until reload. Confirm this matches their symptoms.
2. **Resolver + variable pattern (open source)** — show a `resolver <dns_ip> valid=<ttl>s ipv6=off;` and a `set $upstream_host backend.example.com;` with `proxy_pass http://$upstream_host;`. Explain that using a **variable** in `proxy_pass` is what forces per-request re-resolution, and note that you must then restore `proxy_pass` path handling (it changes URI behaviour) and often set `proxy_ssl_name`/`Host` explicitly.
3. **Resolver tuning** — set a sane `valid=` override and `resolver_timeout`, and warn about the failure mode where a slow/broken resolver stalls requests. Note `ipv6=off` when the backend has no usable AAAA.
4. **NGINX Plus alternative** — if applicable, show `server backend.example.com resolve;` inside `upstream {}` with a `resolver` in `http {}`, and state that this is the cleaner path but is Plus-only (or requires the `resolve` parameter support).
5. **TLS to the backend** — if `https://`, set `proxy_ssl_server_name on;` and `proxy_ssl_name` so SNI/cert validation still works after the IP changes.
Output: (a) the complete commented config for their flavor, (b) a table of each directive and the failure it prevents, (c) how to verify re-resolution (change DNS / scale the backend and confirm new IPs are picked up without reload), and (d) the `nginx -t` line. Validate with `nginx -t` and reload; call out that the variable-in-proxy_pass form silently changes URI passing if the location and path are not set up correctly.
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
This is one of the most surprising NGINX behaviours in production: proxy_pass http://backend; with a hostname resolves DNS exactly once, when the config is loaded, and then caches that IP for the life of the worker. Everything works for weeks — until the backend autoscales, a cloud endpoint rotates, or a Kubernetes pod moves, and NGINX keeps faithfully sending traffic to an IP that is gone. The result is 502s and 504s that mysteriously clear after a reload, which sends people chasing the wrong cause.
The prompt anchors on that root cause first, then hands over the specific mechanism most engineers don’t know: putting a variable in proxy_pass (backed by a resolver) is what forces NGINX to re-resolve per request. That single detail is the fix, but it comes with a sharp edge the prompt refuses to skip — using a variable changes how the URI is passed upstream, so a naive switch can silently drop or duplicate path segments.
It also covers the two things that turn the fix into a new outage: a resolver pointed at a flaky DNS server (which can stall every request) and HTTPS backends where SNI and certificate validation break once the IP is dynamic unless proxy_ssl_name/proxy_ssl_server_name are set. By demanding a verification step that actually scales or re-points the backend, the prompt ensures re-resolution is proven, not assumed.
Related prompts
-
Debug NGINX 502/504 Upstream Errors Prompt
Diagnose why NGINX returns 502 Bad Gateway or 504 Gateway Timeout from an upstream by correlating the error log, the proxy block, and upstream health into a ranked root-cause list with fixes.
-
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 auth_request Subrequest SSO Prompt
Design a correct `auth_request` gateway that offloads authentication to an external SSO/auth service — forwarding the right headers, handling 401/403 vs 5xx distinctly, and passing identity back to your app — instead of a fragile snippet that leaks unauthenticated traffic on the auth service's bad day.
-
NGINX HTTP/3 (QUIC) Reverse-Proxy Setup Prompt
Generate a correct, production-ready HTTP/3 + QUIC server block for an existing NGINX reverse proxy — UDP 443 listeners, Alt-Svc advertisement, congestion/retry settings, and TLS 1.3 — without breaking your working HTTP/2 fallback.
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.