Revision as of 19:34, 18 December 2014

How To Contribute a driver to Cinder

Deadline for Kilo

Review the OpenStack dev mailing list post about his.

Third Party CI Requirement Policy

One thing that has been lacking for plugins over the past is any sort of formal CI testing. The OpenStack Project as a whole has had an extremely comprehensive CI implementation for some time now that runs against reference implementations and some of the more common optional configs that are out there. As a Community Cinder (and other projects as well) have agreed that if a vendor wishes to submit a driver for their particular storage device that said vendor should also be required to set up a third party CI system in their lab which runs tempest-dsvm-full against their device for every Cinder commit, and provides feedback in to Gerrit.

This is very much an evolving process and is subject to change, but currently here's where we stand as of Nov, 2014:

• All vendors with a driver in the Cinder code-base merged before Kilo opened are required to have 3'rd party CI testing prior to K-2 (Feb 5th 2015)
• Drivers merged in Kilo should target CI by the end of Kilo or risk removal in early L.
• Every commit made to Cinder should be ran against the vendors 3'rd party CI environment
• Currently the tests that should be run are 'tempest-dsvm-full'
• Your version should follow a naming template like: "tempest-dsvm-full-<DriverName>"
• Results/logs should be reported just as they are with the OpenStack Infra CI systems
• If a vendor has more than one driver, they need more than one CI system. In other words if you have 3 drivers, you'll be expected to test all 3 of those drivers.

There are a number of resources out there to help deploy your own CI environment. One of the best sources currently is a series of blog posting from Jay Pipes that can be found here: http://www.joinfu.com/2014/02/setting-up-an-openstack-external-testing-system-part-2/

As I mentioned this is an evolving process, there's a good deal more information that's needed here to help folks and we'll get that flushed out as we go along and start having some successes on this.

Before you write any code

• Read the How To Contribute Page.

• Read the Cinder wiki page.

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

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

• Use log markers by importing cinder.i18n

Submit Driver For Review

• Do NOT bother the Cinder core team for reviews. We are aware of your patch being posted.

• Make sure your commit message follows the OpenStack project guidelines.

• Make sure your driver has appropriate third party testing done.

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

• Continue to be available on IRC and attend the weekly meetings in case questions come up.

• Submit a patch to OpenStack-Manuals with your driver information
  • https://github.com/openstack/openstack-manuals
  • doc/config-reference/block-storage/drivers
  • https://wiki.openstack.org/wiki/Documentation/HowTo