jscheffl commented on code in PR #55633: URL: https://github.com/apache/airflow/pull/55633#discussion_r2346920032
########## airflow-ctl/docs/howto/index.rst: ########## @@ -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 aquire 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_diagram.svg + :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/diagrams/airflowctl_api_network_diagram.svg + :width: 60% + :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 neither do not provide it nor or set the environment variable ``AIRFLOW_CLI_TOKEN``, you can skip using this parameter. Review Comment: This is a bit double negative. Hard to read. Proposal to re-phrase: ```suggestion If you are setting the token via the environment variable ``AIRFLOW_CLI_TOKEN``, you can skip using this parameter. ``` ########## airflow-ctl/docs/howto/index.rst: ########## @@ -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 aquire 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_diagram.svg + :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/diagrams/airflowctl_api_network_diagram.svg + :width: 60% + :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 neither do not provide it nor or set the environment variable ``AIRFLOW_CLI_TOKEN``, you can skip using this parameter. + +**--username**: This parameter is optional. +If you do not provide ``--api-token`` or set the environment variable ``AIRFLOW_CLI_TOKEN``, you must provide this parameter along with ``--password``. + +**--password**: This parameter is optional. +If you do not provide ``--api-token`` or set the environment variable ``AIRFLOW_CLI_TOKEN``, you must provide this parameter along with ``--username``. Review Comment: I propose to phrase it simpler ```suggestion If you provide a username via ``--username`` this is the required password to authenticate. ``` ########## airflow-ctl/docs/howto/index.rst: ########## @@ -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 aquire 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_diagram.svg + :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/diagrams/airflowctl_api_network_diagram.svg + :width: 60% + :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 neither do not provide it nor or set the environment variable ``AIRFLOW_CLI_TOKEN``, you can skip using this parameter. + +**--username**: This parameter is optional. +If you do not provide ``--api-token`` or set the environment variable ``AIRFLOW_CLI_TOKEN``, you must provide this parameter along with ``--password``. Review Comment: Also hard to read, proposal: ```suggestion If you are not using ``--api-token`` or the environment variable ``AIRFLOW_CLI_TOKEN``, you must provide a username to authentication along with ``--password``. ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
