This project demonstrates how to implement graceful shutdowns using FastAPI and kubernetes, that uses websockets client connections and internal background queues.
I have written a blog post on this project. You can read it here. In this blog post, I have explained the importance of graceful shutdowns and how to implement them in FastAPI with websockets.
When deploying a new version of an application, it is essential to ensure that no tasks are lost during the deployment process. This is especially important for applications that use websockets to maintain real-time connections with clients. In such cases, abruptly terminating the application can lead to data loss and client disconnections.
Here we have a FastAPI server, deployed in a pod of Kubernetes with min-replicas set to 1 for simplicity. It has a rest API to send tasks, a WebSocket interface for sending task status events to the clients, and a signal listener that listens to pod termination signals sent by Kubernetes. Through the rest API, a task is created and enqueued to the inbuilt fast-api background queue and is later processed by the worker. Once, the task is processed the client is notified via WebSocket. The custom-implemented signal listener listens to all the SIGTERM signals send by the Kubernetes controller when a pod termination happens. This is the watcher that steers the entire graceful shutdown part.
✅ Ensure zero task loss during deployments
🔗 Keep existing clients connected while preventing new connections to a terminating pod
📣 Provide real-time feedback to clients through WebSocket notifications
🚦 Mitigate race conditions between pod termination and task creation
-
Clone the repository:
git clone https://github.com/jainal09/fastapi-gracefulshutdown-websockets.git
-
Install the dependencies:
You will need poetry to install the project dependencies.
poetry install --no-dev # for production # or poetry install # for development
-
Start the FastAPI application:
python main.py
-
Open your web browser and navigate to
http://localhost:8000/docsto access the application.
-
Deploy the application to a Kubernetes cluster:
kubectl apply -f k8s/deployment.yaml
-
Access the application at
http://localhost:30000/docs.
Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
-
Lint the code using ruff:
ruff check --fix .
-
Run the type checker:
mypy .
-
Image available on Docker Hub: jainal09/grs-fast-api
-
Build the Docker imag locally:
docker build -t jainal09/grs-fast-api:v9 . 
If you like my content, please subscribe to my newsletter Scale Bites. I will keep you updated on the latest articles, projects, and cool stuff I am working on. Subscribe here.
This project is licensed under the MIT License.