From 8d44eaf08242cd09f13ed0abc01c41aa51fdf70a Mon Sep 17 00:00:00 2001
From: "Erlon R. Cruz" <erlon@canonical.com>
Date: Thu, 27 Apr 2023 10:07:20 -0300
Subject: [PATCH] Add documentation for TGT to LIO migration

Change-Id: I4eacc16879ee0bf789175e7ac2d4462645adce5b
---
 doc/source/project/issues-and-procedures.rst  |  1 +
 .../cinder-lvm-tgt-to-lio-migration.rst       | 79 +++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 doc/source/project/procedures/cinder-lvm-tgt-to-lio-migration.rst

diff --git a/doc/source/project/issues-and-procedures.rst b/doc/source/project/issues-and-procedures.rst
index 8e15456e..ee920655 100644
--- a/doc/source/project/issues-and-procedures.rst
+++ b/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
diff --git a/doc/source/project/procedures/cinder-lvm-tgt-to-lio-migration.rst b/doc/source/project/procedures/cinder-lvm-tgt-to-lio-migration.rst
new file mode 100644
index 00000000..35abdd63
--- /dev/null
+++ b/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
+