From 985212c0abcefd82972d003b064b028874ee0497 Mon Sep 17 00:00:00 2001
From: MCamp859 <maryx.camp@intel.com>
Date: Sun, 24 May 2020 16:58:49 -0400
Subject: [PATCH] Add Cinder config guide for image conversion file system

Guide describes how to create, modify, and delete optional
file system used for image conversion.

Closes-Bug: 1879632

Change-Id: I59be43dbf3aed814273824df99125bedbb9bafbf
Signed-off-by: MCamp859 <maryx.camp@intel.com>
---
 doc/source/configuration/index.rst            |   2 +
 .../configuration/openstack_cinder_config.rst | 116 ++++++++++++++++++
 2 files changed, 118 insertions(+)
 create mode 100644 doc/source/configuration/openstack_cinder_config.rst

diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index ce44796a6..64506c63d 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -35,6 +35,8 @@ OpenStack Configuration
 .. toctree::
    :maxdepth: 1
 
+   openstack_cinder_config
    openstack_ironic_config
    openstack_swift_config
 
+
diff --git a/doc/source/configuration/openstack_cinder_config.rst b/doc/source/configuration/openstack_cinder_config.rst
new file mode 100644
index 000000000..0087a4d0c
--- /dev/null
+++ b/doc/source/configuration/openstack_cinder_config.rst
@@ -0,0 +1,116 @@
+==========================================
+OpenStack Cinder File System Configuration
+==========================================
+
+This guide describes an optional file system that can be used by Cinder to
+convert qcow2 images to raw format.
+
+.. contents::
+   :local:
+   :depth: 1
+
+--------
+Overview
+--------
+
+By default, qcow2 image conversion is done using the docker_lv file system.
+To avoid filling up the docker_lv file system, you can create a new file system
+that is dedicated to image conversion using the steps in this guide.
+
+-------------------
+Add new file system
+-------------------
+
+Use the ``host-fs-add`` CLI command to add a file system dedicated to qcow2
+image conversion.
+
+The syntax is:
+
+::
+
+    system host-fs-add <hostname or id> <fs name=size>
+
+Where:
+
+*   ``hostname or id`` is the location where the file system will be added.
+*   ``fs name`` is the file system name.
+*   ``size`` is an integer indicating the file system size in Gigabytes.
+
+When the command completes, a new partition named ``/opt/conversion`` is
+created and mounted.
+
+You must add the file system on both controller nodes. You can do this from
+controller-0 using the following example commands:
+
+::
+
+    system host-fs-add controller-0 image-conversion=20
+    system host-fs-add controller-1 image-conversion=20
+
+
+..  Note::
+
+    #.  The requested size of the ``image-conversion`` file system should be
+        big enough to accommodate any image that is uploaded to glance. If the
+        requested size is too large, the command will fail.
+
+    #.  The recommended size for the file system is at least 2 times as
+        large as the largest converted image from qcow2 to raw.
+
+    #.  The conversion file system can be added before or after stx-openstack is
+        applied.
+
+    #.  The conversion file system must be added on both controllers. If not,
+        stx-openstack will not use the new file system.
+
+    #.  If the conversion file system is added after stx-openstack is applied,
+        changes to stx-openstack will only take effect once the application is
+        re-applied.
+
+The ``image-conversion`` file system can be added only on controller nodes.
+
+Alarms for ``image-conversion`` will be raised for the following scenarios:
+
+*   If the conversion file system is not added on both controllers.
+*   If the size of the file system is not the same on both controllers.
+
+----------------------
+Resize the file system
+----------------------
+
+Change the size of the ``image-conversion`` file system at runtime using the
+following CLI command:
+
+::
+
+    system host-fs-modify <hostname or id> <fs name=size>
+
+For example:
+
+::
+
+    system host-fs-modify controller-0 image-conversion=30
+
+----------------------
+Remove the file system
+----------------------
+
+Use the ``host-fs-delete`` CLI command to remove an ``image-conversion`` file
+system dedicated to qcow2 image conversion.
+
+The syntax is:
+
+::
+
+    system host-fs-delete <hostname or id> <fs name>
+
+When ``image-conversion`` is removed, the ``/opt/conversion`` partition is also
+removed.
+
+..  Note::
+
+        You cannot delete an image-conversion file system when
+        stx-openstack is in the applying, applied, or removing state.
+
+You cannot add or remove any other file systems using these commands.
+