This is an automated email from the ASF dual-hosted git repository.
kaxilnaik pushed a commit to branch v3-2-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-2-test by this push:
new ff7097240a4 [v3-2-test] Add FAQ entry for API server memory growth
with gunicorn worker recycling (#65036) (#65037)
ff7097240a4 is described below
commit ff7097240a431b32cf68dbeb5ceebfed14a163fb
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Sat Apr 11 02:26:09 2026 +0100
[v3-2-test] Add FAQ entry for API server memory growth with gunicorn worker
recycling (#65036) (#65037)
* Add FAQ entry for API server memory growth with gunicorn fix
Users experiencing API server memory growth from accumulated
serialized DAG cache entries can use gunicorn with rolling worker
restarts as the recommended solution. This FAQ entry documents the
configuration and cross-references the dag version inflation FAQ.
* Add version availability note for gunicorn support
(cherry picked from commit 74283fb2a865dd7463690082bfb171079aacd68a)
Co-authored-by: Kaxil Naik <[email protected]>
---
airflow-core/docs/faq.rst | 37 +++++++++++++++++++++++++++++++++++++
1 file changed, 37 insertions(+)
diff --git a/airflow-core/docs/faq.rst b/airflow-core/docs/faq.rst
index fe48c3695dc..a5064cc3dfa 100644
--- a/airflow-core/docs/faq.rst
+++ b/airflow-core/docs/faq.rst
@@ -666,6 +666,43 @@ try pausing the Dag again, or check the console or server
logs if the
issue recurs.
+API Server
+^^^^^^^^^^
+
+.. _faq:api-server-memory-growth:
+
+How to prevent API server memory growth?
+-----------------------------------------
+
+The API server caches serialized Dag objects in memory. Over time, as Dag
versions accumulate
+(see :ref:`faq:dag-version-inflation`), this cache grows and can consume
several gigabytes of memory.
+
+The recommended solution (available since Airflow 3.2.0) is to use
**gunicorn** with **rolling worker
+restarts**. Gunicorn periodically recycles worker processes, releasing all
accumulated memory. It also
+uses ``preload`` + ``fork``, so workers share read-only memory pages via
copy-on-write, reducing overall
+memory usage by 40-50% compared to uvicorn's multiprocess mode.
+
+To enable gunicorn with worker recycling:
+
+.. code-block:: ini
+
+ [api]
+ server_type = gunicorn
+ # Restart each worker every 12 hours (43200 seconds)
+ worker_refresh_interval = 43200
+ worker_refresh_batch_size = 1
+
+This requires the ``apache-airflow-core[gunicorn]`` extra to be installed.
+
+See :ref:`config:api__server_type`,
:ref:`config:api__worker_refresh_interval`, and
+:ref:`config:api__worker_refresh_batch_size` for the full configuration
reference.
+
+.. note::
+
+ Worker recycling handles memory growth from *any* source, not just the Dag
cache. It is the
+ recommended approach for production API server deployments.
+
+
MySQL and MySQL variant Databases
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
