Jump to: navigation, search

Difference between revisions of "Cinder/how-to-contribute-a-driver"

(Starter Guide For Submitting a Driver to Cinder)
 
m (Third Party CI Requirement Policy)
 
(55 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
= How To Contribute a driver to Cinder =
 
= How To Contribute a driver to Cinder =
  
== Before you write any code ==
+
=== Deadline for the Current Development Cycle ===
* The most important place to start is the How To Contribute Page:
+
For clarification, a patch is considered a new driver when it's introducing a new protocol into the driver. For example, if your driver supports iSCSI, but your patch proposes support for FibreChannel, that's a new driver patch.
https://wiki.openstack.org/wiki/How_To_Contribute#If_you.27re_a_developer
 
  
* Hopefully you already familiarized yourself with the Cinder wiki page
+
The deadline for new backend drivers, with working third party CI and no code review issues, is always posted on the [https://releases.openstack.org/index.html current release] schedule. (Take the link for the "Series" name, and a link to the release schedule will be at the top of the page.)
https://wiki.openstack.org/wiki/Cinder
 
  
== Helpful Hints ==
+
=== Third Party CI Requirement Policy ===
Cinder offers a reference implementation that should be used as a model.  The reference implementation driver file is cinder/volume/drivers/lvm.py, not to be mistaken for cinder/volume/driver.py which is the base class that all of the drivers inherit from.  You must implement all of the methods that exist as core features (check out the driver compat matrix from the cinder wiki).
+
See [https://wiki.openstack.org/wiki/Cinder/tested-3rdParty-drivers third party CI] wiki.
  
Note that there are a lot of options that show up there regarding iSCSI targets etc, but this gives you an idea of the expectations in terms of features that are implemented and some of the behaviors. I strongly recommend loading up devstack (you're going to need it to test your driver anyway) and play around with the default LVM.  It's really important that you get a feel for how Ciinder works and interacts with the other OpenStack projects before you get too far along.
+
For people working on getting their CI to handle Python 3, see [https://wiki.openstack.org/wiki/Cinder/3rdParty-drivers-py3-update Cinder Third Party CI update to Python 3.7]
  
We have a development channel on freenode: #openstack-cinder
+
=== Before you write any code ===
There are developers here round the clock, it's a great resource for you get started.  Log in, ask questions, don't stare at code in isolation for a week... if you're stuck on something just ask.  There' also no need to start off with "Can I ask a question"... you likely won't get a response.  Just type in your question, that way anybody monitoring the channel that might know the answer can step in and answer.
+
* Read the [https://wiki.openstack.org/wiki/How_To_Contribute#If_you.27re_a_developer How To Contribute Page].
  
== Before You Submit Code ==
+
* Read the [https://wiki.openstack.org/wiki/Cinder Cinder wiki page].
There's a number of things that you should get from the "how to contribute guide" but to reiterate as they're often missed:
 
* You need to submit a detailed blueprint in Launchpad introducing your driver and submitting it for approval
 
* Have a general idea of how Cinder works, what it's used for, why the other projects in OpenStack may or may not use it
 
* Fully understand the difference between ephemeral storage on the Nova side versus the persistent storage offered by Cinder
 
  
== Oh, and don't forget ==
+
* Understand how Cinder works, what it's used for, why the other projects in OpenStack may or may not use it. Fully understand the difference between ephemeral storage on the Nova side versus the persistent storage offered by Cinder
Unit tests for new code are required.  We're in the process of converting everything to use mock (rather than mox) for our unit tests. Be sure when writing unit tests and setting up fakes to use mock, examples of it's usage can be found in the existing tests like cinder/tests/test_volume.py.
 
  
There's an expectation that unit tests leave the system as they found it.  That means using things like the tempfile module if you have to write out some persistent data somewhere for your test.
+
* Cinder offers a reference implementation that should be used as a model.  The reference implementation driver file is [https://github.com/openstack/cinder/blob/master/cinder/volume/drivers/lvm.py cinder/volume/drivers/lvm.py], not to be mistaken for cinder/volume/driver.py which is the base class that all of the drivers inherit from. Note that there are a lot of options that show up there regarding iSCSI targets etc, but this gives you an idea of the expectations in terms of features that are implemented and some of the behaviors.  I strongly recommend loading up [http://devstack.org devstack] (you're going to need it to test your driver anyway) and play around with the default LVMIt's really important that you get a feel for how Cinder works and interacts with the other OpenStack projects before you get too far along.
  
There's an expectation that any backend device and every driver that is submitted can successfully run and pass the existing OpenStack Tempest testsEvery commit in OpenStack goes through an automated gate test, all we ask here is that since we won't have your backend device that you run this yourself an make sure you've covered all of the required features and that everything works as expected. We have a script to help you with that in the devstack tree: https://github.com/openstack-dev/devstack/tree/master/driver_certsThis is relatively new and needs some more flushing out as well as some documentation, but it's a start and it should progress and grow as time goes by.
+
* You don't need a [https://github.com/openstack/cinder-specs cinder spec] for most drivers. You always need to submit a [[Blueprints|blueprint]] in [https://launchpad.net/cinder Launchpad] introducing your driver, so that it can be targeted for a release.
 +
 
 +
* We have a development channel on freenode: #openstack-cinder. There are developers here round the clock, it's a great resource for you get startedLog in, ask questions, don't stare at code in isolation for a week... if you're stuck on something just ask.  There's also no need to start off with "Can I ask a question"... you likely won't get a response.  Just type in your question, that way anybody monitoring the channel that might know the answer can step in and answer.
 +
 
 +
=== Writing Code ===
 +
* You must implement all of the methods that exist as [https://docs.openstack.org/cinder/latest/contributor/drivers.html core features].
 +
 
 +
* Your driver should not make any state changes. (e.g. make Cinder database calls). The [https://github.com/openstack/cinder/blob/master/cinder/volume/manager.py volume manager] is responsible for making state changes after the driver is done talking to the storage backend. Your driver should try not to read from database if possible.
 +
 
 +
* Unit tests for new code are required.
 +
 
 +
* Make sure you're not duplicating a configuration option that already exists. To verify this, you'll need to need look at the [https://docs.openstack.org/cinder/latest/configuration/block-storage/samples/cinder.conf.html cinder/etc/cinder.conf.sample file].
 +
** Every effort should be made to reuse common config options before introducing driver-specific ones.
 +
** If options are added, you will need to run "tox -e genopts" to update the opts.py file that is used to generate our configuration references.
 +
 
 +
* Make sure to follow the [http://docs.openstack.org/developer/hacking/ OpenStack Style Guide]. Very likely you'll get nit pick reviews otherwise, which is not productive either way.
 +
 
 +
* Cinder's [https://github.com/openstack/cinder/blob/master/cinder/volume/manager.py manager layer] will log useful information like failures from the driver that are raised. However, you're more than welcome to add additional logging, but please follow our [http://specs.openstack.org/openstack/openstack-specs/specs/log-guidelines.html logging guideline]. Use [http://docs.openstack.org/developer/oslo.i18n/usage.html log markers] by importing [http://git.openstack.org/cgit/openstack/cinder/tree/cinder/i18n.py cinder.i18n] so that log translations can be made.
 +
 
 +
=== Submitting Driver For Review ===
 +
 
 +
When submitting your driver, please include a release note along with your patch. See the [http://docs.openstack.org/developer/reno/usage.html#creating-new-release-notes Reno Documentation] for details on how to generate new release notes.
 +
 
 +
The release note should be something along the lines of:
 +
 
 +
  ---
 +
features:
 +
  - Added backend driver for ''vendor'' storage.
 +
 
 +
* All new code should also be Python 3.7 compatible. Unit tests will be run with both python 2.7 and python 3.7, but additional runtime testing should be performed. Check the [https://governance.openstack.org/tc/reference/runtimes/ supported runtimes] for the current cycle.
 +
 
 +
* Do '''NOT''' bother the Cinder team for reviews. We are aware of your patch being posted.
 +
 
 +
* Make sure your commit message follows the [[GitCommitMessages|OpenStack project guidelines]].
 +
 
 +
* Make sure your driver has appropriate [[Cinder/tested-3rdParty-drivers|third party testing]] done. It is required that your CI posts the [https://wiki.openstack.org/wiki/Cinder/tested-3rdParty-drivers#What_tests_do_I_use.3F necessary tests pass]. Since your driver is not yet merged, follow [https://wiki.openstack.org/wiki/Cinder/tested-3rdParty-drivers#How_do_I_run_my_CI_to_test_all_cinder_patches_with_my_driver_not_yet_merged.3F instructions] to have you unmerged driver properly tested.
 +
 
 +
* Documentation is now kept in the openstack/cinder repo. At a minimum, please add a basic description of your driver and its configuration options under the [https://github.com/openstack/cinder/tree/master/doc/source/configuration/block-storage/drivers volume driver section of the Configuration reference].
 +
 
 +
*[http://docs.openstack.org/infra/manual/developers.html#development-workflow Post your review].
 +
 
 +
=== After Your Driver Is Added ===
 +
Congratulations! You're not done yet though. After your driver has been merged there are still some things that need to be done.
 +
 
 +
* Make sure there is documentation for your driver
 +
** Add a liaison name to https://wiki.openstack.org/wiki/Documentation/VendorDrivers after reading this [http://specs.openstack.org/openstack/docs-specs/specs/kilo/move-driver-docs.html spec]
 +
** Refer to  [http://docs.openstack.org/contributor-guide/ Documentation Contributor Guide] on how to contribute.
 +
* Continue to be available on IRC and attend the weekly meetings in case questions come up.
 +
* Subscribe to receive bugs for your driver! The Cinder team will be triaging bugs and will tag bugs with the name of your company that are related to your driver. To subscribe:
 +
** Go to https://bugs.launchpad.net/openstack/cinder/+bug
 +
** Click 'Subscribe to bug mail'
 +
** Click the radio button "are added and changed in any way"
 +
** Click checkbox 'Bugs must match this filter (...)"
 +
** Click tags
 +
** With "match all tags" selected type in the field the name of your company.
 +
 
 +
 
 +
[[Category: Cinder]]

Latest revision as of 12:58, 8 August 2019

How To Contribute a driver to Cinder

Deadline for the Current Development Cycle

For clarification, a patch is considered a new driver when it's introducing a new protocol into the driver. For example, if your driver supports iSCSI, but your patch proposes support for FibreChannel, that's a new driver patch.

The deadline for new backend drivers, with working third party CI and no code review issues, is always posted on the current release schedule. (Take the link for the "Series" name, and a link to the release schedule will be at the top of the page.)

Third Party CI Requirement Policy

See third party CI wiki.

For people working on getting their CI to handle Python 3, see Cinder Third Party CI update to Python 3.7

Before you write any code

  • Understand how Cinder works, what it's used for, why the other projects in OpenStack may or may not use it. Fully understand the difference between ephemeral storage on the Nova side versus the persistent storage offered by Cinder
  • Cinder offers a reference implementation that should be used as a model. The reference implementation driver file is cinder/volume/drivers/lvm.py, not to be mistaken for cinder/volume/driver.py which is the base class that all of the drivers inherit from. Note that there are a lot of options that show up there regarding iSCSI targets etc, but this gives you an idea of the expectations in terms of features that are implemented and some of the behaviors. I strongly recommend loading up devstack (you're going to need it to test your driver anyway) and play around with the default LVM. It's really important that you get a feel for how Cinder works and interacts with the other OpenStack projects before you get too far along.
  • You don't need a cinder spec for most drivers. You always need to submit a blueprint in Launchpad introducing your driver, so that it can be targeted for a release.
  • We have a development channel on freenode: #openstack-cinder. There are developers here round the clock, it's a great resource for you get started. Log in, ask questions, don't stare at code in isolation for a week... if you're stuck on something just ask. There's also no need to start off with "Can I ask a question"... you likely won't get a response. Just type in your question, that way anybody monitoring the channel that might know the answer can step in and answer.

Writing Code

  • You must implement all of the methods that exist as core features.
  • Your driver should not make any state changes. (e.g. make Cinder database calls). The volume manager is responsible for making state changes after the driver is done talking to the storage backend. Your driver should try not to read from database if possible.
  • Unit tests for new code are required.
  • Make sure you're not duplicating a configuration option that already exists. To verify this, you'll need to need look at the cinder/etc/cinder.conf.sample file.
    • Every effort should be made to reuse common config options before introducing driver-specific ones.
    • If options are added, you will need to run "tox -e genopts" to update the opts.py file that is used to generate our configuration references.
  • Make sure to follow the OpenStack Style Guide. Very likely you'll get nit pick reviews otherwise, which is not productive either way.
  • Cinder's manager layer will log useful information like failures from the driver that are raised. However, you're more than welcome to add additional logging, but please follow our logging guideline. Use log markers by importing cinder.i18n so that log translations can be made.

Submitting Driver For Review

When submitting your driver, please include a release note along with your patch. See the Reno Documentation for details on how to generate new release notes.

The release note should be something along the lines of:

---
features:
 - Added backend driver for vendor storage.
  • All new code should also be Python 3.7 compatible. Unit tests will be run with both python 2.7 and python 3.7, but additional runtime testing should be performed. Check the supported runtimes for the current cycle.
  • Do NOT bother the Cinder team for reviews. We are aware of your patch being posted.

After Your Driver Is Added

Congratulations! You're not done yet though. After your driver has been merged there are still some things that need to be done.

  • Make sure there is documentation for your driver
  • Continue to be available on IRC and attend the weekly meetings in case questions come up.
  • Subscribe to receive bugs for your driver! The Cinder team will be triaging bugs and will tag bugs with the name of your company that are related to your driver. To subscribe:
    • Go to https://bugs.launchpad.net/openstack/cinder/+bug
    • Click 'Subscribe to bug mail'
    • Click the radio button "are added and changed in any way"
    • Click checkbox 'Bugs must match this filter (...)"
    • Click tags
    • With "match all tags" selected type in the field the name of your company.