Merge "Add ensure shares admin docs"

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
 -------------------------

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.

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.