You just finished deploying the newest backend version to the server. Then seconds later the monitoring channel floods with 502 Bad Gateway and Connection Reset by Peer alerts from users. 😅
After digging in, a checkout transaction had failed halfway. The balance was already cut at the payment gateway, but the order status never got updated in the database.
The culprit is often trivial: the old server process was killed abruptly, an un-graceful shutdown. We just slash the process without offering a proper goodbye.
Think of it like having dinner in a restaurant. If at exactly 22.00 the manager turns off the lights, locks the door, and shoos out guests whose food is half served, you would be furious, right? That is the forced version.
The civilized version is different. At 21.30 the staff announce "last order" and stop taking new guests. But anyone already seated is still welcome to finish the meal. Only once every table is empty and the cashier has closed the books does the door get locked.
In software, graceful shutdown is server etiquette: finish all the work in progress (in-flight requests) before actually killing the process. Skip this step and every open HTTP connection drops mid-flight, database transactions hang, and the connection pool leaks.
To let your backend be updated at any time without users hitting errors, this mechanism is mandatory. Let's go through how it works.
Key takeaways
- Graceful shutdown is server etiquette: finish every in-flight request before the process actually dies.
- Without it, database transactions hang, the connection pool leaks, and users get a 502 Bad Gateway right during the deploy.
- A SIGTERM signal asks the application to stop politely, while SIGKILL severs the process without compromise and cannot be refused.
- A lifespan handler in FastAPI, exec form in the Dockerfile,
terminationGracePeriodSeconds, and apreStophook together make a deployment without downtime.
The Unix Signals: SIGINT, SIGTERM, and SIGKILL
The operating system, including Docker and Kubernetes, talks to a backend application through standard POSIX signals.
SIGINT is sent when you press Ctrl + C in the terminal. The application usually responds by stopping execution gracefully.
SIGTERM is the one you see most in production. Docker (docker stop) or Kubernetes sends it during a rolling update or a pod scale down. The message is roughly: "Please prepare to stop, and finish the active tasks!"
SIGKILL (signal 9) is the final word, and an application cannot refuse or catch it (uninterceptable). The kernel severs the process instantly. If the application does not finish within its grace period, the system fires SIGKILL.
What Does an Ideal Graceful Shutdown Cycle Look Like?
When an orchestrator like Kubernetes or Docker wants to stop a backend container, five stages ideally happen in order.
First, the application receives the SIGTERM signal from the OS.
Second, the application refuses new traffic. Its health check or readiness probe status is marked unhealthy, so the load balancer stops routing requests to this server.
Third, requests already in-flight are finished. Allow a pause (grace period, say 10-30 seconds) so running HTTP requests, database transactions, or file uploads can complete.
Fourth, external connections are closed in order. Disconnect the database pool (PostgreSQL, MySQL), save cache state (Redis), and send acknowledge/nack to the message queue (RabbitMQ).
Finally, the process exits cleanly with exit code 0. The server says goodbye properly, with no drama. 😎
A Lifespan Example in FastAPI and Uvicorn
Modern frameworks like FastAPI, together with the ASGI server Uvicorn, already provide an elegant lifespan context manager for handling startup and graceful shutdown.
import asyncio
from contextlib import asynccontextmanager
from fastapi import FastAPI
import asyncpg
# Global variable for the connection pool
db_pool = None
@asynccontextmanager
async def lifespan(app: FastAPI):
global db_pool
# [STARTUP PHASE]
print("🚀 [STARTUP] Menginisialisasi Database Connection Pool...")
db_pool = await asyncpg.create_pool(
dsn="postgresql://user:***@localhost:5432/mydb",
min_size=5,
max_size=20
)
print("✅ [STARTUP] Koneksi Database siap menerima traffic!")
yield # Aplikasi berjalan dan melayani request di sini
# [GRACEFUL SHUTDOWN PHASE - On receiving SIGTERM]
print("🛑 [SHUTDOWN] Sinyal terminasi diterima! Memulai Graceful Shutdown...")
# Allow time for in-flight requests to finish
await asyncio.sleep(2)
# Close the database connections in order
if db_pool:
print("🔒 [SHUTDOWN] Menutup Database Connection Pool...")
await db_pool.close()
print("✅ [SHUTDOWN] Seluruh koneksi DB berhasil dilepas.")
print("👋 [SHUTDOWN] Aplikasi backend berhenti dengan aman.")
app = FastAPI(lifespan=lifespan)
@app.get("/api/data")
async def get_data():
async with db_pool.acquire() as connection:
return await connection.fetch("SELECT * FROM users LIMIT 10")
When a docker stop command or a SIGTERM signal arrives, Uvicorn automatically stops accepting new requests, waits for active requests to finish, then runs the code block after yield inside the lifespan function.
Important Configuration in Docker and Kubernetes
For the mechanism to work optimally in a cloud or container environment, there are a few things to check.
Use exec form in the Dockerfile. Make sure the CMD command is a JSON array, for example CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]. If you use shell form (CMD uvicorn ...), the SIGTERM signal gets stuck in the /bin/sh shell and never reaches the Python application. This trap is very subtle.
Also set terminationGracePeriodSeconds in Kubernetes. The default is 30 seconds before SIGKILL is sent. If your application needs longer for a background job, raise the value, say to 60 seconds, in the Deployment manifest.
Finally, use a preStop hook. Add a sleep (say 5 seconds) in the Kubernetes pod container, so the load balancer has enough time to cross the pod IP off its active endpoint list before the pod starts killing its process.
So, Why Does This Matter So Much?
Writing feature code that runs is only half the journey. Making sure the application can start and stop gracefully is the key to building a system that is resilient, consistent in its data, and free of downtime while your team ships every day.
Happy devops, and may your server always say goodnight before it sleeps. 👋