Graceful Shutdown & Signal Handling Design Prompt
Design correct PID 1 signal handling so containers catch SIGTERM, drain in-flight work, and exit cleanly within the stop grace period instead of being SIGKILLed.
- Target user
- DevOps and platform engineers hardening container lifecycle behavior
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior container reliability engineer who specializes in the process lifecycle inside Docker containers. I will provide some or all of: - The Dockerfile (especially the `ENTRYPOINT`/`CMD` lines and any shell wrapper or entrypoint script) - How the process is started (exec form vs shell form, `sh -c`, a supervisor, or a wrapper script) - The application language/runtime and how it currently handles signals (if at all) - The `docker run`/Compose config, including any `stop_grace_period`, `stop_signal`, or `--init` usage - What "in-flight work" means for this service (open HTTP requests, queue messages being processed, DB transactions, buffered writes) Your job: 1. **Diagnose the PID 1 problem** — determine what is actually running as PID 1. Explain that `CMD ["sh", "-c", "node app.js"]` (shell form) makes the shell PID 1, which does not forward `SIGTERM` to the child and does not reap zombies, so `docker stop` waits the full grace period and then `SIGKILL`s the app mid-request. Show whether the current setup has this defect. 2. **Fix signal delivery** — rewrite `ENTRYPOINT`/`CMD` to exec form so the real process becomes PID 1 and receives `SIGTERM` directly, or introduce a minimal init (`tini`, or `docker run --init`) when the process legitimately spawns children that must be reaped. Explain the trade-off between `exec` in the entrypoint script vs a dedicated init. 3. **Design the drain sequence** — specify, in order, what the app must do on `SIGTERM`: stop accepting new work (close the listener / stop pulling from the queue), finish in-flight work up to a deadline, flush buffers, close DB and pool connections, then exit 0. Provide language-appropriate handler pseudocode. 4. **Size the grace period** — recommend a `stop_grace_period` / `--stop-timeout` that is longer than the worst-case drain but bounded, and explain the relationship between that timeout and the app's internal drain deadline (internal deadline must be shorter so the app exits before Docker escalates to `SIGKILL`). 5. **Handle the load-balancer race** — note that in-flight and newly arriving connections during shutdown need a readiness/health flip so the router stops sending traffic before the app stops accepting it; describe the ordering. 6. **Verify** — give exact commands to prove correct behavior: send `docker stop` and observe a clean exit code 0 within the grace period, inspect logs for the drain sequence, and confirm no requests are dropped. Output as: (a) PID 1 diagnosis, (b) corrected Dockerfile ENTRYPOINT/CMD and init decision with rationale, (c) ordered drain sequence with signal-handler pseudocode, (d) recommended stop_grace_period and internal deadline values, (e) load-balancer drain ordering, (f) verification commands. Prefer exec-form ENTRYPOINT and explicit signal handling over relying on Docker's SIGKILL fallback — state the exit-code and dropped-work consequences of getting this wrong.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Related prompts
-
Docker Compose Production-Readiness Review Prompt
Review a docker-compose.yml written for local development and produce a production-hardening checklist covering restart policies, resource limits, healthchecks, secrets, logging, and pinned images.
-
Container Restart Policy Strategy Design Prompt
Design restart-policy strategy for containers across dev, CI, and production, choosing between no/on-failure/always/unless-stopped, tuning backoff, and pairing policies with healthchecks so crashes stay visible.
-
Container Healthcheck & ENTRYPOINT/CMD Design Prompt
Design a correct HEALTHCHECK and fix ENTRYPOINT/CMD so the container starts as PID 1, handles signals, reports real readiness, and shuts down gracefully.
-
Base Image Selection & Digest Pinning Prompt
Choose the right base image family (distroless, alpine, slim, full) for a workload and design a digest-pinning and update strategy that balances size, security, compatibility, and reproducibility.
More Docker with AI prompts & error guides
Browse every Docker with AI 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.