From 7ed38ff31caf2bfb99da3c8f6716b6485fc1a45b Mon Sep 17 00:00:00 2001 From: Dmitriy Chubinidze Date: Thu, 14 Aug 2025 21:21:00 +0000 Subject: [PATCH] [doc] Document existing Ansible tags Add a section to the docs describing the Ansible tags are already existing to make it easier for anyone running playbooks to know which tags to target. Change-Id: I59d4cdb949a0a09a37603b865cd964bf8a286080 Signed-off-by: Dmitriy Chubinidze --- doc/source/admin/scale-environment.rst | 1 + .../scale-environment/use-ansible-tags.rst | 171 ++++++++++++++++++ doc/source/contributors/code-rules.rst | 7 +- 3 files changed, 177 insertions(+), 2 deletions(-) create mode 100644 doc/source/admin/scale-environment/use-ansible-tags.rst diff --git a/doc/source/admin/scale-environment.rst b/doc/source/admin/scale-environment.rst index 3ff8e7c6ad..b734f0dd5e 100644 --- a/doc/source/admin/scale-environment.rst +++ b/doc/source/admin/scale-environment.rst @@ -11,6 +11,7 @@ using OpenStack-Ansible. scale-environment/scaling-maria-rabbit scale-environment/add-new-infrastructure-host scale-environment/add-compute-host + scale-environment/use-ansible-tags scale-environment/remove-compute-host scale-environment/recover-compute-host-failure scale-environment/replacing-failed-hardware diff --git a/doc/source/admin/scale-environment/use-ansible-tags.rst b/doc/source/admin/scale-environment/use-ansible-tags.rst new file mode 100644 index 0000000000..3ecccfc59b --- /dev/null +++ b/doc/source/admin/scale-environment/use-ansible-tags.rst @@ -0,0 +1,171 @@ +.. _ansible-tags: + +================== +Using Ansible tags +================== + +In Ansible, a tag is a label you can assign to tasks, allowing you to run +only the tasks you need instead of the whole playbook. This is especially +handy in large playbooks — for example, if you have 20–30 tasks but just +need to restart a service or make some changes in configuration, you can tag +those tasks and run them individually. + +The following tags are available in OpenStack Ansible: + +- ``common-mq`` +- ``common-service`` +- ``common-db`` +- ``pki`` +- ``post-install`` +- ``haproxy-service-config`` +- ``ceph`` +- ``uwsgi`` +- ``systemd-service`` +- ``-install`` +- ``-config`` + +common-mq +--------- + +Handles tasks for setting up and configuring RabbitMQ. Use this tag when +you need to reconfigure virtual hosts, users, or their privileges without +affecting the rest of the deployment. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.nova --tags common-mq + +common-service +-------------- + +Manages service configuration inside Keystone, such as service +catalog entries, service user existence, and user privileges. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.nova --tags common-service,post-install + +common-db +--------- + +Creates and configures databases, including user creation, +and permission assignments. Run this tag if database credential or permissions +need to be refreshed or corrected. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.neutron --tags common-db + +pki +--- + +Manages certificates and public key infrastructure. +Use it when renewing, replacing, or troubleshooting SSL/TLS certificates. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.setup_infrastructure -e pki_regen_cert=true --tags pki + +post-install +------------ + +Runs tasks after the main installation and configuration are complete. +This tag is used for final adjustments, applying changes in configuration +files, and validation checks. Run this tag when you’ve made changes that +require only applying updated configuration. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.cinder --tags post-install + +haproxy-service-config +---------------------- + +Configures HAProxy for routing traffic between services. +Use this tag if HAProxy settings change or a new service backend is added. + +Example: + +.. code-block:: shell-session + + # openstack-ansible haproxy-install.yml --tags haproxy-service-config + +ceph +---- + +Deploys and configures Ceph clients and related components. Use this tag +for tasks such as adding new monitors or upgrading Ceph clients to a +different version, as well as other Ceph-related configuration updates. + +Example: + +.. code-block:: shell-session + + # openstack-ansible ceph-install.yml --tags ceph + +uwsgi +----- + +Sets up and configures uWSGI processes. +Useful when adjusting process counts, sockets, or performance tuning. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.setup_openstack --tags uwsgi + +systemd-service +--------------- + +Manages systemd unit components, ensuring they are configured as expected +and allowing overrides to be applied. Use this tag when you need to adjust +unit files or restart services in a controlled way. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.designate --tags systemd-service + +-install +----------------- + +Installs a specific OpenStack service (replace ```` with the +service name). +A tag including the word ``install`` handles only software installation +tasks — it deploys the necessary packages and binaries on the target host. +Use this tag when you only need to install or reinstall service software without +changing its configuration or running it. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.designate --tags designate-install + +-config +---------------- + +Configures a specific OpenStack service (replace with the service +name). This tag applies configuration files, directories, and service-specific +settings. It usually covers a broad set of tasks beyond post-install, and may +include systemd-service, pki, common-mq or common-db service tags. +Run this tag when applying updated configurations to a service that is +already installed. + +Example: + +.. code-block:: shell-session + + # openstack-ansible openstack.osa.cinder --tags cinder-config diff --git a/doc/source/contributors/code-rules.rst b/doc/source/contributors/code-rules.rst index 0b55532606..4b1a739ab7 100644 --- a/doc/source/contributors/code-rules.rst +++ b/doc/source/contributors/code-rules.rst @@ -236,6 +236,11 @@ and command modules such as the Ansible ``shell`` or ``command``. Tags and tags conventions ------------------------- +.. note:: + + If you want to learn more about how to use Ansible tags effectively, + check out the :dev_docs:`Operations Guide `. + Tags are assigned based on the relevance of each individual item. Higher level includes (for example in the ``tasks/main.yml``) need high level tags. For example, ``*-config`` or ``*-install``. @@ -254,8 +259,6 @@ The following convention is used: ``--tags -config`` is only possible if the target already ran the tags ``-install``. -* A tag including the word ``upgrade`` handles all the upgrade tasks. - Variable files conventions --------------------------