Jump to: navigation, search

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

m (Third Party CI Requirement Policy)
(Third Party CI Requirement Policy: moving this to the third-party ci requirement section)
Line 10: Line 10:
=== Third Party CI Requirement Policy ===
=== Third Party CI Requirement Policy ===
See [https://wiki.openstack.org/wiki/Cinder/tested-3rdParty-drivers third party CI] wiki.
See [https://wiki.openstack.org/wiki/Cinder/tested-3rdParty-drivers third party CI] wiki.
In addition, please configure your CI to trigger on the string:
"run-<CI NAME>"
So if your CI account name is "Super Cool Storage CI", the CI should be able to be retriggered by leaving the comment:
run-Super Cool Storage CI
CI's do not need to kick off tests until Jenkin's has given a +1, though it is up to the maintainer if you want to trigger immediately on all patchsets.
For the openstack-ci configuration, change the following to switch to only trigger on a Jenkin's +1:
In layout.yaml:
Delete the line:
      - event: patchset-created
And then add:
      - event: comment-added
            - verified: 1
              username: Jenkins
All tempest "volume" tests should run. An example tempest test run would be using the command:
tox -e all -- volume
tools/pretty_tox.sh volume
=== Before you write any code ===
=== Before you write any code ===

Revision as of 23:27, 10 May 2016

How To Contribute a driver to Cinder

Deadline for Mitaka

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, will be January 19th, 2016 at 7:59 UTC.

Review the OpenStack dev mailing list post about his for more information.

Third Party CI Requirement Policy

See third party CI wiki.

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. 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.
  • 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. To generate this file:
    • Install tox
    • Run tox -egenconfig
  • 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:

 - Added backend driver for vendor storage.

All new code should also be Python 3.4 compatible. Add all unit tests to the test-py3.txt file at the root of the cinder repo until we are able to remove the test whitelist.

  • 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.