From 9bd566c52e6c26db3ded2b2fc256b43f29b44a29 Mon Sep 17 00:00:00 2001
From: Carlos Eduardo <ces.eduardo98@gmail.com>
Date: Thu, 19 Sep 2024 17:24:36 -0300
Subject: [PATCH] Add ensure shares admin docs

Added documentation on the newly introduced
``update_shares_status_on_ensure`` configuration option, as well
as how to run ensure shares and what to expect when it is running.

Change-Id: I9cd1260b97bde665066a136b74a0390a134d3d93
Signed-off-by: Carlos Eduardo <ces.eduardo98@gmail.com>
---
 doc/source/admin/index.rst                    |  1 +
 .../shared-file-systems-services-manage.rst   | 35 +++++++++++++++++++
 .../configuration/tables/manila-common.inc    |  2 ++
 3 files changed, 38 insertions(+)

diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index feb899ca01..1df9a62ca8 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -68,6 +68,7 @@ deployment.
    group_capabilities_and_extra_specs
    export_location_metadata
    shared-file-systems-share-backup-management.rst
+   shared-file-systems-services-manage.rst
 
 Supported share back ends
 -------------------------
diff --git a/doc/source/admin/shared-file-systems-services-manage.rst b/doc/source/admin/shared-file-systems-services-manage.rst
index b50f21fc65..c50ccfba96 100644
--- a/doc/source/admin/shared-file-systems-services-manage.rst
+++ b/doc/source/admin/shared-file-systems-services-manage.rst
@@ -15,3 +15,38 @@ share services are excluded from the scheduler cycle and new shares will not
 be placed on the disabled back end. However, shares from this service stay
 available. With 2024.2 release, admin can schedule share on disabled back end
 using ``only_host`` scheduler hint.
+
+
+Recalculating the shares' export location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Until the 2024.2 release, recalculating a share's export location required
+restarting the corresponding manila-share manager service. This action
+triggered the backend driver's "ensure shares" operation, which would execute
+a series of steps to update the export locations.
+
+Starting with the 2024.2 release, as an administrator, you can initiate export
+location recalculation without restarting the manila-share service. This can
+now be done directly through the "ensure shares" API.
+
+It is possible to start the ensure shares procedure even if a service is
+already running it.
+
+To start ensure shares on a given manila-share binary, run the
+:command:`openstack share service ensure shares` command:
+
+.. code-block:: console
+
+   $ openstack share service ensure shares <host>
+
+.. note::
+
+   When this command is issued, the ``manila-share`` manager will by default
+   change the status of the shares to ``ensuring``, unless the
+   :ref:`common configuration option <manila-common>` named
+   ``update_shares_status_on_ensure`` is changed to ``False``.
+
+.. note::
+
+   The service will have its ``ensuring`` field set to ``True`` while this
+   operation is still in progress.
diff --git a/doc/source/configuration/tables/manila-common.inc b/doc/source/configuration/tables/manila-common.inc
index 41d9e32bbf..aaf1a8a8bd 100644
--- a/doc/source/configuration/tables/manila-common.inc
+++ b/doc/source/configuration/tables/manila-common.inc
@@ -130,3 +130,5 @@
      - (List) Check the presence of a file based on a port to determine if an application is running on a port. Expects a "port:path" list of strings. Used by DisableByFilesPortsHealthcheck plugin.
    * - ``path`` = ``/healthcheck``
      - (String) DEPRECATED: The path to respond to healtcheck requests on.
+   * - ``update_shares_status_on_ensure`` = ``True``
+     - (Boolean) Defines whether Manila should update the status of the shares when ensuring shares or not.