Add documentation for TGT to LIO migration

Change-Id: I4eacc16879ee0bf789175e7ac2d4462645adce5b

doc/source/project/issues-and-procedures.rst

@@ -45,6 +45,7 @@ list of documented special charm procedures:
    procedures/percona-series-upgrade-to-focal
    procedures/placement-charm
    procedures/cinder-lvm-migration
+   procedures/cinder-lvm-tgt-to-lio-migration
    procedures/charmhub-migration
    procedures/ovn-migration
    procedures/ovn-upgrade-2203

doc/source/project/procedures/cinder-lvm-tgt-to-lio-migration.rst

@@ -0,0 +1,79 @@
+================================================
+Target helper migration: TGT to LIO (cinder-lvm)
+================================================
+
+Starting with the Wallaby release, the 'lioadm' library (python3-rtslib-fb)
+is the default target helper installed with the cinder-common package. New
+charm deployments will use the new helper by default without manual user
+intervention.
+Deployments upgrading from Victoria will automatically continue to use the
+legacy version, 'tgtadm', but it is recommended that users migrate to the new
+helper.
+
+The steps to transition to the new helper are the following:
+
+1 - Upgrade cinder and cinder-lvm charms to the latest version from the
+Victoria channel.
+
+
+2 - Once everything is up and running, upgrade cinder and cinder-lvm charms to
+the latest version from the system in Wallaby channel.
+
+
+3 - Execute the OpenStack upgrade transitioning from Victoria to Wallaby:
+
+.. code-block:: none
+
+    juju config cinder openstack-origin=cloud:focal-wallaby
+
+
+4 - Create a new cinder-lvm application, as in the example below, with the same
+configuration as the previous cinder-lvm, but adding the new target_helper
+config, and an alternative target_port.
+
+.. important::
+
+    The new application must have a different name than the previous one, as
+    you need a way to differentiate new and old backends. The alias option can
+    also be used to differentiate the backends, but it is not mandatory. A
+    different target_port is also recommended, to avoid conflicts with the
+    previous backend.
+
+.. code-block:: yaml
+
+    applications:
+      cinder-lvm-lio:
+        charm: cinder-lvm
+        channel: wallaby/stable
+        options:
+          alias: stsstack-lio
+          block-device: /var/lib/lvm_pool0.img|20G
+          volume-group: cinder-volumes-stsstack
+          config-flags: target_helper=lioadm,target_port=3261
+    relations:
+      - [ cinder, cinder-lvm-lio ]
+
+Install the new application:
+
+.. code-block:: none
+
+    juju export-bundle > current-juju.yaml
+    juju deploy ./current-juju.yaml --overlay ./cinder-lvm-lio.yaml
+
+
+5 - Disable old tgtadm backends and services:
+
+.. code-block:: none
+
+    cinder service-disable juju-348a1c-focal-ussuri-lvm-3-0@LVM-stsstack \
+    cinder-volume
+
+
+6 - Optionally, migrate volumes to the new backend and remove the old
+backend/application.
+
+.. code-block:: none
+
+    openstack volume migrate --host \
+    juju-8f5d46-focal-ussuri-lvm-graylog-0@LVM-stsstack-lio v1
+