This is an automated email from the ASF dual-hosted git repository.
bugraoz 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 ec758b7abf1 docs(airflowctl): add authentication details (#55633)
ec758b7abf1 is described below
commit ec758b7abf189d5027e830d91effa85e17659249
Author: Bugra Ozturk <[email protected]>
AuthorDate: Tue Sep 16 20:46:44 2025 +0200
docs(airflowctl): add authentication details (#55633)
* docs(airflowctl): add authentication details and parameter descriptions
for airflowctl auth login
* Update airflow-ctl/docs/howto/index.rst
Co-authored-by: Jens Scheffler <[email protected]>
* Update airflow-ctl/docs/howto/index.rst
Co-authored-by: Jens Scheffler <[email protected]>
* Update airflow-ctl/docs/howto/index.rst
Co-authored-by: Jens Scheffler <[email protected]>
* docs(airflowctl): fix typo in authentication section of index.rst
* docs(airflowctl): update network diagram and add diagram generation script
---------
Co-authored-by: Jens Scheffler <[email protected]>
---
.pre-commit-config.yaml | 3 +-
airflow-ctl/docs/howto/index.rst | 48 ++++++++++--
...flowctl_api_network_architecture_diagram.md5sum | 1 +
...airflowctl_api_network_architecture_diagram.png | Bin 0 -> 63371 bytes
.../airflowctl_api_network_architecture_diagram.py | 86 +++++++++++++++++++++
5 files changed, 129 insertions(+), 9 deletions(-)
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c4f70b86917..fe3512ed0b2 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -519,7 +519,8 @@ repos:
files: >
(?x)
^airflow-core/docs/.*/diagram_[^/]*\.py$|
- ^docs/images/.*\.py$
+ ^docs/images/.*\.py$|
+ ^airflow-ctl/docs/images/diagrams/.*\.py$
pass_filenames: true
- id: generate-volumes-for-sources
name: Generate volumes for docker compose
diff --git a/airflow-ctl/docs/howto/index.rst b/airflow-ctl/docs/howto/index.rst
index b9634cf2a20..12946aed449 100644
--- a/airflow-ctl/docs/howto/index.rst
+++ b/airflow-ctl/docs/howto/index.rst
@@ -28,13 +28,24 @@ configuring an airflowctl environment.
How to use airflowctl
-----------------------
+---------------------
**Important Note**
''''''''''''''''''
airflowctl needs the Airflow API running to be able to work. Please, see the
login section below before use.
Otherwise, you may get errors.
+Datetime Usage
+''''''''''''''
+For datetime parameters, date should be timezone aware and in ISO format.
+For example: ``2025-10-10T10:00:00+00:00``
+Let's take example of triggering a DAG run with a logical date, run after and
a note.
+
+.. code-block:: bash
+
+ airflowctl dagrun trigger --dag-id="example_bash_operator"
--logical-date="2025-09-06T00:00:00+00:00"
--run-after="2025-09-06T00:00:00+00:00" --note="Triggered from airflowctl"
+
+
Login
'''''
airflowctl needs to be able to connect to the Airflow API. You should pass API
URL as a parameter to the command
@@ -66,15 +77,36 @@ In both cases token is securely stored in the keyring
backend. Only configuratio
is the API URL and the environment name. The token is stored in the keyring
backend and is not persisted in the
configuration file. The keyring backend is used to securely store the token
and is not accessible to the user.
-Datetime Usage
-''''''''''''''
-For datetime parameters, date should be timezone aware and in ISO format.
-For example: ``2025-10-10T10:00:00+00:00``
-Let's take example of triggering a DAG run with a logical date, run after and
a note.
+What is authentication for ``airflowctl``?
+``````````````````````````````````````````
+For ``airflowctl`` to be able to communicate with the Airflow API, it needs to
authenticate itself and acquire token.
+This is done using either a token or a username and password.
+The token can be acquired from the Airflow API or generated using a username
and password.
-.. code-block:: bash
+.. image:: ../images/diagrams/airflowctl_api_network_architecture_diagram.png
+ :target:
https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.png
+ :width: 100%
+ :alt: airflowctl Auth Login Help
- airflowctl dagrun trigger --dag-id="example_bash_operator"
--logical-date="2025-09-06T00:00:00+00:00"
--run-after="2025-09-06T00:00:00+00:00" --note="Triggered from airflowctl"
+Parameter Details for airflowctl auth login
+```````````````````````````````````````````
+
+**--api-url**: This parameter is required. (e.g. ``http://localhost:8080``)
+The default value is ``http://localhost:8080``. Full URL of the Airflow API.
Without any ``/api/*`` suffixes.
+If you are running the ``airflowctl`` in ``breeze`` container, it is optional.
+
+**--api-token**: This parameter is optional.
+If you are setting the token via the environment variable
``AIRFLOW_CLI_TOKEN``, you can skip using this parameter.
+
+**--username**: This parameter is optional.
+If you are not using ``--api-token`` or the environment variable
``AIRFLOW_CLI_TOKEN``, you must provide a username to authentication along with
``--password``.
+
+**--password**: This parameter is optional.
+If you provide a username via ``--username`` this is the required password to
authenticate.
+
+**--env**: This parameter is optional.
+The name of the environment to create or update. The default value is
``production``.
+This parameter is useful when you want to manage multiple Airflow environments.
More Usage and Help Pictures
''''''''''''''''''''''''''''
diff --git
a/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.md5sum
b/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.md5sum
new file mode 100644
index 00000000000..d3ecab853e6
--- /dev/null
+++
b/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.md5sum
@@ -0,0 +1 @@
+ea755b0b93dd0524e7ed0ef42b83a888
diff --git
a/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.png
b/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.png
new file mode 100644
index 00000000000..b79bafcc618
Binary files /dev/null and
b/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.png
differ
diff --git
a/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.py
b/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.py
new file mode 100644
index 00000000000..0894fb955df
--- /dev/null
+++
b/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.py
@@ -0,0 +1,86 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+from __future__ import annotations
+
+from pathlib import Path
+
+from diagrams import Cluster, Diagram, Edge
+from diagrams.onprem.client import User
+from diagrams.onprem.compute import Server
+from rich.console import Console
+
+MY_DIR = Path(__file__).parent
+MY_FILENAME = Path(__file__).with_suffix("").name
+
+console = Console(width=400, color_system="standard")
+
+graph_attr = {
+ "concentrate": "false",
+ "splines": "splines",
+}
+
+edge_attr = {
+ "minlen": "1",
+}
+
+
+def generate_airflowctl_api_network_diagram():
+ image_file = (MY_DIR / MY_FILENAME).with_suffix(".png")
+
+ console.print(f"[bright_blue]Generating network diagram {image_file}")
+ with Diagram(
+ name="airflowctl<->API Network Diagram",
+ show=False,
+ direction="LR",
+ filename=MY_FILENAME,
+ edge_attr=edge_attr,
+ graph_attr=graph_attr,
+ ):
+ # Machine network with client
+ with Cluster("Machine Network", graph_attr={"margin": "30", "width":
"10"}):
+ client = User("Client\n(The machine/host has the airflowctl
installed)")
+
+ # Airflow deployment network with API server
+ with Cluster("Apache Airflow Deployment Network",
graph_attr={"margin": "30"}):
+ api_server = Server("Apache Airflow API Server\n(e.g. DNS:
https://airflow.internal.api.com)")
+
+ # Edges representing the flows
+ (
+ client
+ >> Edge(
+ color="blue",
+ style="solid",
+ label="Login Request\n(if not manually used in --api-token or
env var. Authentication done with username/password)",
+ )
+ >> api_server
+ )
+
+ (
+ api_server
+ >> Edge(
+ color="darkgreen",
+ style="solid",
+ label="Returns Token",
+ )
+ >> client
+ )
+
+ console.print(f"[green]Generated network diagram {image_file}")
+
+
+if __name__ == "__main__":
+ generate_airflowctl_api_network_diagram()
