From 8a6a938f0b576ed9b58f5231183a4c61f77e3842 Mon Sep 17 00:00:00 2001 From: Dmitriy Chubinidze Date: Fri, 5 Sep 2025 10:34:15 +0000 Subject: [PATCH] [doc] Add Ansible logging and ARA integration guide Add documentation covering default Ansible logging behavior in OpenStack-Ansible, including the log file path and how to override it. And introduce instructions for enabling and configuring ARA integration. Change-Id: I43ff79f0b7ccc96ce84852e0dec71c87d9fe81ae Signed-off-by: Dmitriy Chubinidze --- doc/source/admin/ansible-logging.rst | 59 ++++++++++++++++++++++++++++ doc/source/admin/index.rst | 1 + 2 files changed, 60 insertions(+) create mode 100644 doc/source/admin/ansible-logging.rst diff --git a/doc/source/admin/ansible-logging.rst b/doc/source/admin/ansible-logging.rst new file mode 100644 index 0000000000..bdfb13de9b --- /dev/null +++ b/doc/source/admin/ansible-logging.rst @@ -0,0 +1,59 @@ +Ansible Logging Guide +===================== + +OpenStack-Ansible provides flexible options for collecting and analyzing +Ansible execution logs. Operators can use the default logging configuration, +or integrate with `ARA Records Ansible `_ for advanced reporting. + +Default Log File +---------------- + +By default, OpenStack-Ansible stores all playbook logs in: + +.. code-block:: shell-session + + /openstack/log/ansible-logging/ansible.log + +This location is defined by the ``ANSIBLE_LOG_PATH`` environment variable. + +To change the path, override it in the deployment configuration file: + +.. code-block:: shell-session + + /etc/openstack_deploy/user.rc + +ARA Integration +--------------- + +For richer reporting, OpenStack-Ansible can be integrated with **ARA (Ansible Run Analysis)**. + +During the bootstrap process, set the following variable: + +.. code-block:: shell-session + + export SETUP_ARA=true + ./bootstrap-ansible.sh + +This installs the ARA client and configures it as an Ansible callback. + +The client requires an ARA server to store data. The server is not included in +OpenStack-Ansible and must be deployed by the operator. The recommended method +is to use the ``recordsansible.ara`` collection. + +On the deployment host, configure the client with: + +.. code-block:: shell-session + + export ARA_API_CLIENT=http + export ARA_API_SERVER=https://ara.example.com + export ARA_API_INSECURE=False + export ARA_API_USERNAME=ara + export ARA_API_PASSWORD= + +If you prefer not to run an ARA server, you can still generate local reports: + +.. code-block:: bash + + export ARA_REPORT_TYPE=html + +Each playbook run will then produce an HTML report stored on the deploy host. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 7e7caed55d..ec513bf4f3 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -30,6 +30,7 @@ the major upgrades procedures. maintenance-tasks.rst scale-environment.rst backup-restore.rst + ansible-logging.rst troubleshooting.rst upgrades/compatibility-matrix.rst upgrades/compatibility-matrix-legacy.rst