diff --git a/doc/source/drivers-all-about.rst b/doc/source/drivers-all-about.rst new file mode 100644 index 00000000000..8e94876d7eb --- /dev/null +++ b/doc/source/drivers-all-about.rst @@ -0,0 +1,120 @@ +======================== +All About Cinder Drivers +======================== + +.. toctree:: + :hidden: + + reference/support-matrix + drivers + + +General Considerations +~~~~~~~~~~~~~~~~~~~~~~ + +Cinder allows you to integrate various storage solutions into your +OpenStack cloud. It does this by providing a stable interface for +hardware providers to write *drivers* that allow you to take advantage +of the various features that their solutions offer. + +"Supported" drivers +------------------- + +In order to make it easier for you to assess the stability and quality +of a particular vendor's driver, The Cinder team has introduced the concept +of a **supported** driver. These are drivers that: + +* have an identifiable *driver maintainer* +* are included in the Cinder source code repository +* use the upstream Cinder bug tracking mechanism +* support the Cinder :ref:`required_driver_functions` +* maintain a third-party Continuous Integration system that runs the + OpenStack Tempest test suite against their storage devices + + * this must be done for every Cinder commit, and the results must be + reported to the OpenStack Gerrit code review interface + * for details, see `Driver Testing `_ + +In summary, there are two important aspects to a driver being considered +as **supported**: + +* the code meets the Cinder driver specifications (so you know it + should integrate properly with Cinder) +* the driver code is continually tested against changes to Cinder (so + you know that the code actually does integrate properly with Cinder) + +The second point is particularly important because changes to Cinder +can impact the drivers in two ways: + +* A Cinder change may introduce a bug that only affects a particular + driver or drivers (this could be because many drivers implement + functionality well beyond the Required Driver Functions). With a + properly running and reporting third-party CI system, such a bug can + be detected at the code review stage. + +* A Cinder change may exercise a new code path that exposes a driver + bug that had previously gone undetected. A properly running third-party + CI system will detect this and alert the driver maintainer that there + is a problem. + +Driver Compliance +----------------- + +The current policy for CI compliance is: + +* CIs must report on every patch, whether the code change is in their own + driver code or not + +* The CI comments must be properly formatted to show up in the CI summary in + Gerrit + +Non-compliant drivers will be tagged as unsupported if: + +* No CI success reporting occurs within a two week span +* The CI is found to not be testing the expected driver (CI runs using the + default LVM driver, etc.) +* Other issues are found but failed to be addressed in a timely manner + +CI results are reviewed on a regular basis and if found non-compliant, a +driver patch is submitted flagging it as 'unsupported'. This can occur +at any time during the development cycle. A driver can be returned to +'supported' status as soon as the CI problem is corrected. + +We do a final compliance check around the third milestone of each release. +If a driver is marked as 'unsupported', vendors have until the time of +the first Release Candidate tag (two weeks after the third milestone) +to become compliant, in which case the patch flagging the driver as +'unsupported' can be reverted. Otherwise, the driver will be considered +'unsupported' in the release. + +The CI results are currently posted here: +http://cinderstats.ivehearditbothways.com/cireport.txt + +"Unsupported" drivers +--------------------- + +A driver is marked as 'unsupported' when it is out of compliance. + +Such a driver will log a warning message to be logged in the cinder-volume +log stating that it is unsupported and deprecated for removal. + +In order to use an unsupported driver, an operator must set the configuration +option ``enable_unsupported_driver=True`` in the driver's configuration +section of ``cinder.conf`` or the Cinder service will fail to load. + +If the issue is not corrected before the next release, the driver will be +removed from the Cinder code repository per the standard OpenStack +deprecation policy. + +Current Cinder Drivers +~~~~~~~~~~~~~~~~~~~~~~ + +The Cinder team maintains a page of the current drivers and what exactly +they support in the :ref:`Driver Support Matrix `. + +You may find more details about the current drivers on the +:doc:`Available Drivers ` page. + +Additionally, the configuration reference for each driver provides +even more information. See :doc:`Volume drivers +`. diff --git a/doc/source/index.rst b/doc/source/index.rst index f371a32af7c..e11b1aa71ae 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -109,8 +109,17 @@ Contents: :maxdepth: 1 configuration/index - reference/support-matrix - drivers + +.. toctree:: + :maxdepth: 2 + :titlesonly: + :includehidden: + + drivers-all-about + +.. toctree:: + :maxdepth: 1 + cli/index Additional resources diff --git a/doc/source/reference/support-matrix.rst b/doc/source/reference/support-matrix.rst index 0caba131c20..e1be7c02725 100644 --- a/doc/source/reference/support-matrix.rst +++ b/doc/source/reference/support-matrix.rst @@ -29,6 +29,8 @@ at the time of release. maintained. The old matrix will be left for reference but this matrix should be treated as the correct state of Cinder. +.. _required_driver_functions: + Required Driver Functions ~~~~~~~~~~~~~~~~~~~~~~~~~