(airflow) branch main updated: Document running multiple Airflow instances on the same host (#75056)

[we...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

Lee-W pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/main by this push:
     new 26395211972 Document running multiple Airflow instances on the same host (#75056)
26395211972 is described below

commit 263952119723e5ca38e1e65bc933dd7d3da2bc50
Author: W. H. Wang <ma...@gmail.com>
AuthorDate: Mon Oct 19 17:38:19 2026 +0800

    Document running multiple Airflow instances on the same host (#75056)
---
 airflow-core/docs/howto/run-behind-proxy.rst | 32 ++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/airflow-core/docs/howto/run-behind-proxy.rst b/airflow-core/docs/howto/run-behind-proxy.rst
index ae28cb23b33..161b1e56719 100644
--- a/airflow-core/docs/howto/run-behind-proxy.rst
+++ b/airflow-core/docs/howto/run-behind-proxy.rst
@@ -70,6 +70,38 @@ To do so, you need to set the following setting in your ``airflow.cfg``::
 - Please make sure your proxy does not enforce http-only status on the Set-Cookie headers.
   Airflow frontend needs to access the cookies through javascript, and a http-only flag would disturb this functionality.
 
+Running multiple Airflow instances on the same host
+---------------------------------------------------
+
+If you serve several Airflow instances from the same host name (for example ``https://lab.mycompany.com``,
+or ``localhost`` on different ports), give each instance its own path in ``[api] base_url``. Browsers scope
+cookies by host name and path, not by port, so instances that share the same ``base_url`` path also share
+the authentication cookie: logging in to one instance logs you out of the others.
+
+Airflow scopes its authentication cookie to the ``base_url`` path since Airflow 3.1.8. With the FAB,
+Keycloak or AWS auth manager, this also requires ``apache-airflow-providers-fab`` 3.5.0,
+``apache-airflow-providers-keycloak`` 0.6.0 or ``apache-airflow-providers-amazon`` 9.23.0 or later.
+For example::
+
+    # instance serving production
+    base_url = https://lab.mycompany.com/prod
+
+    # instance serving development
+    base_url = https://lab.mycompany.com/dev
+
+Paths that share a prefix, such as ``/airflow`` and ``/airflow_dev``, are fine: the cookie path always
+ends with ``/``, so the cookie of one instance is not sent to the other.
+
+.. warning::
+
+    The ``base_url`` path of one instance must not be a parent path of another's, such as ``/prod`` and
+    ``/prod/dev``, or ``/`` and any other path. The browser sends the parent instance's cookie with every
+    request under its path, so the other instance reads the parent instance's token instead of its own and
+    cannot keep you logged in.
+
+Alternatively, serve each instance from its own host name, for example ``prod.lab.mycompany.com`` and
+``dev.lab.mycompany.com``.
+
 Helm Chart Configuration
 ------------------------