You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "abhijeets25012-tech (via GitHub)" <gi...@apache.org> on 2026/02/05 13:26:32 UTC
[PR] Add documentation for running Uvicorn on Kubernetes [airflow]
abhijeets25012-tech opened a new pull request, #61494:
URL: https://github.com/apache/airflow/pull/61494
### Description
This PR adds documentation about running the API server with `server_type = uvicorn` on Kubernetes.
Unlike `gunicorn`, uvicorn runs as a single long-lived process per pod and does not support rolling worker restarts. In long-running Kubernetes environments this can lead to gradual memory growth or stale internal state. The new section explains recommended operational practices such as Kubernetes rolling restarts, Helm-based restarts, and scheduled pod recycling.
The goal is to help users operating Airflow on Kubernetes understand when periodic pod restarts are necessary and when switching to `gunicorn` may be a better production choice.
### What is included
* New documentation section: **Running Uvicorn on Kubernetes**
* Operational best practices for long-running deployments
* Example `kubectl rollout restart` command
* Guidance on uvicorn vs gunicorn behavior
### Why this change
Users deploying with uvicorn on Kubernetes may assume automatic worker recycling similar to gunicorn. This clarification improves reliability guidance and reduces confusion for production setups.
### Testing
* Documentation build checked locally
* RST formatting verified
* No functional code changes
### Notes
This is a documentation-only change.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for running Uvicorn on Kubernetes [airflow]
Posted by "jason810496 (via GitHub)" <gi...@apache.org>.
jason810496 merged PR #61494:
URL: https://github.com/apache/airflow/pull/61494
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for running Uvicorn on Kubernetes [airflow]
Posted by "abhijeets25012-tech (via GitHub)" <gi...@apache.org>.
abhijeets25012-tech commented on PR #61494:
URL: https://github.com/apache/airflow/pull/61494#issuecomment-3863470550
Thanks for the review and approval, @jason810496! All checks have passed and there are no conflicts, so this should be ready to merge.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for running Uvicorn on Kubernetes [airflow]
Posted by "abhijeets25012-tech (via GitHub)" <gi...@apache.org>.
abhijeets25012-tech commented on code in PR #61494:
URL: https://github.com/apache/airflow/pull/61494#discussion_r2776738246
##########
airflow-core/docs/administration-and-deployment/web-stack.rst:
##########
@@ -138,3 +138,36 @@ Use the default uvicorn when:
- Running on Windows
- Running in development or testing environments
- Running short-lived containers (e.g., Kubernetes pods that get recycled)
+
+.. _running-uvicorn-on-kubernetes:
+
+Running Uvicorn on Kubernetes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When running the API server with ``server_type = uvicorn`` on Kubernetes,
+the API server runs as a single long-lived process per pod and does not
+support rolling worker restarts like ``gunicorn``.
+
+In long-running Kubernetes deployments, this may lead to gradual memory
+growth or stale internal state over time. For this reason, it is recommended
+to periodically restart API server pods when using uvicorn.
+
+Recommended approaches include:
+
+- **Kubernetes rolling restarts** of the API server Deployment to recycle pods
+ without downtime.
+- ``Helm-based restarts``, such as triggering a ``rollout`` during a Helm upgrade
+ or by changing a restart annotation.
+- **Cluster-level mechanisms** (for example, scheduled restarts) when running
+ uvicorn for extended periods.
Review Comment:
Thanks for the clarification! Noted about #61432. Glad this PR can be merged now
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for running Uvicorn on Kubernetes [airflow]
Posted by "abhijeets25012-tech (via GitHub)" <gi...@apache.org>.
abhijeets25012-tech commented on PR #61494:
URL: https://github.com/apache/airflow/pull/61494#issuecomment-3858263976
Hi @jason810496, all CI checks are passing now.
Please let me know if any changes are needed from my side
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for running Uvicorn on Kubernetes [airflow]
Posted by "jason810496 (via GitHub)" <gi...@apache.org>.
jason810496 commented on code in PR #61494:
URL: https://github.com/apache/airflow/pull/61494#discussion_r2776709898
##########
airflow-core/docs/administration-and-deployment/web-stack.rst:
##########
@@ -138,3 +138,36 @@ Use the default uvicorn when:
- Running on Windows
- Running in development or testing environments
- Running short-lived containers (e.g., Kubernetes pods that get recycled)
+
+.. _running-uvicorn-on-kubernetes:
+
+Running Uvicorn on Kubernetes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When running the API server with ``server_type = uvicorn`` on Kubernetes,
+the API server runs as a single long-lived process per pod and does not
+support rolling worker restarts like ``gunicorn``.
+
+In long-running Kubernetes deployments, this may lead to gradual memory
+growth or stale internal state over time. For this reason, it is recommended
+to periodically restart API server pods when using uvicorn.
+
+Recommended approaches include:
+
+- **Kubernetes rolling restarts** of the API server Deployment to recycle pods
+ without downtime.
+- ``Helm-based restarts``, such as triggering a ``rollout`` during a Helm upgrade
+ or by changing a restart annotation.
+- **Cluster-level mechanisms** (for example, scheduled restarts) when running
+ uvicorn for extended periods.
Review Comment:
We could even mention #61432 here, but it's fine to merge it right now. I will tracking in #61432 to update this part.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for running Uvicorn on Kubernetes [airflow]
Posted by "abhijeets25012-tech (via GitHub)" <gi...@apache.org>.
abhijeets25012-tech commented on PR #61494:
URL: https://github.com/apache/airflow/pull/61494#issuecomment-3863479301
Merged! Thanks for the review and support.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org