Merge "Spec for changing the block device handling"

doc/source/specs/v1/approved/block-device-overview.rst

@@ -0,0 +1,173 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==================
+Block Device Setup
+==================
+
+During the creation of a disk image (e.g. for a VM), there is the need
+to create, setup, configure and afterwards detach some kind of storage
+where the newly installed OS can be copied to or directly installed
+in.
+
+Problem description
+===================
+
+Currently dib is somewhat limited when it comes to setting up the
+block device: only one partition that can be used for data. LVM,
+encryption, multi-device or installation in an already existing block
+device is not supported.
+
+In addition there are several places (main, lib, elements) where the
+current way of handling the block device is used (spread knowledge and
+implementation).
+
+Also it is not possible, to implement the handling as different
+elements: it is not possible to pass results of one element in the
+same phase to another element.  Passing results from one phase to dib
+main is limited.
+
+Use Cases
+---------
+
+Possible use cases are (Actor: End User)
+
+#. User wants to use an existing block device to install an system
+   image in (like hd, iSCSI, SAN lun, ...).
+#. User wants that the system will be installed in multiple
+   partitions.
+#. User wants that the partitioning is done in a specific way
+   (optimize for speed, optimize for size).
+#. User wants to use LVM to install the system in (multiple PV, VG and
+   LV).
+#. User wants to encrypt a partition or a LV where (parts) of the
+   system are installed in.
+#. User wants specific file systems on specific partitions or LVs.
+
+Please note that these are only examples and details are described and
+implemented by different sub-specs.
+
+Proposed change
+===============
+
+Because of the current way to execute elements, it is not possible to
+have different elements for each feature.  Instead the changes will be
+implemented in a python module 'block_device' placed in the
+'diskimage_builder' directory.
+
+The entry-point mechanism is used to create callable python programs.
+These python programs are directly called from within the dib-main.
+
+There is the need to implement some functions or classes that take
+care about common used new functionality: e.g. storing state between
+phases, calling python sub-modules and passing arguments around.
+These functionality is implemented as needed - therefore it is most
+likely that the first patch implements also big parts of these
+infrastructure tasks.
+
+Alternatives
+------------
+#. Rewrite DIB in the way that elements can interchange data, even if
+   they are called during one phase.
+   This would influence the way all existing elements are called - and
+   might lead to unpredictable results.
+#. In addition there is the need to introduce at least two additional
+   phases: because major parts of the block device handling are
+   currently done in main and these must be passed over to elements.
+#. Another way would be to implement everything in one element:
+   this has the disadvantage, that other elements are not allowed to
+   use the 'block_device' phase any longer and also passing around
+   configuration and results is still not possible (see [3]).
+
+API impact
+----------
+
+Is described in the sub-elements.
+
+Security impact
+---------------
+
+Is described in the sub-elements.
+
+Other end user impact
+---------------------
+
+Paradigm changes from execute script to configuration for block_device
+phase.
+
+Performance Impact
+------------------
+
+Is described in the sub-elements.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  ansreas (andreas@florath.net)
+
+Would be good, if other people would support this - and specify and
+implement modules.
+
+Work Items
+----------
+
+This is an overview over changes in the block device layer.  Each
+level or module needs it's own spec.
+
+A first step is to reimplement the existing functionality, this
+contains:
+#. Level 0: Local Loop module
+   Use loop device on local image file
+   (This is already implemented: [1])
+#. Level 1: partitioning module
+   (This is already implemented: [4])
+#. Level 2: Create File System
+   An initial module uses ext4 only
+#. Level 3: Mounting
+
+As a second step the following functionality can be added:
+* Level 1: LVM module
+* Level 2: Create File System
+  (swap)
+* Level 2: Create File System
+  (vfat, needed for UEFI)
+* Level 2: Create File System
+  (xfs)
+
+Of course any other functionality can also be added when needed and wanted.
+
+Dependencies
+============
+
+Is described in the sub-elements.
+
+Testing
+=======
+
+Is described in the sub-elements.
+
+Documentation Impact
+====================
+
+Is described in the sub-elements.
+
+References
+==========
+
+[1] Implementation of Level 0: Local Loop module
+    https://review.openstack.org/319591
+[2] 'Block Device Setup for Disk-Image-Builder'
+    https://etherpad.openstack.org/p/C80jjsAs4x
+[3] partitioning-parted
+    This was a first try to implement everything
+    as an element - it shows the limitation.
+    https://review.openstack.org/313938
+[4] Implementation of Level 1: partitioning module
+    https://review.openstack.org/322671