openstack-manuals/doc/doc-contrib-guide/source/vendor-drivers.rst

Proprietary driver docs

Important

This documentation only applies to the released documents prior to Pike since the content is now part of the project team repositories.

Many OpenStack projects include drivers to support specific hardware or software. Examples are:

• Cinder: block storage drivers
• Neutron: network plug-ins
• Nova: hypervisors
• Trove: different databases

The documentation team documents the following reference drivers in the Configuration Reference Guide:

• For cinder: volume drivers - document LVM and NFS, backup drivers - document swift
• For glance: document local storage, cinder, and swift as back ends
• For neutron: document ML2 plug-in with the mechanisms drivers Open vSwitch and Linux bridge
• For nova: document KVM (mostly), send Xen open source call for help
• For sahara: Apache Hadoop
• For trove: document all supported Open Source database engines like MySQL.

If a vendor wants to document their driver, they are invited - but not forced -to include their documentation in the Configuration Reference if they commit to maintain the documentation.

Important

Other documentation (including the Administrator Guide and Networking Guide) will not contain content for third-party drivers. In these books, where third party drivers exist, add the statement: “For other drivers, see Chapter X in the Configuration Reference Guide”.

Guidelines

The following are guidelines for drivers documented by the OpenStack community:

• The complete solution must be open source and use standard hardware
• The driver must be part of the respective OpenStack repository
• The driver is considered one of the reference drivers

For documentation of other drivers, the following guidelines apply:

• The Configuration Reference contains a small section for each driver, see below for details.
• Only drivers are covered that are contained in the official OpenStack project repository for drivers (for example in the main project repository or the official third-party repository).

If a vendor wants to add more than the minimal documentation, they need to commit to the following guidelines:

• Assign an editor that is responsible for the content.
• Review and, if necessary, update their driver for each release cycle.

Default section format for external drivers

For each external driver, the driver is briefly documented in a way that is version independent and includes the current configuration options.

Each section should follow this format:

• A short paragraph explaining the driver.

• A link with detailed instructions to the vendor site (if there is one).

• A default paragraph, for example:

  Set the following in your ``cinder.conf``, and use the following options
  to configure it.
  
  volume_driver = cinder.volume.drivers.smbfs.SmbfsDriver

• And finally, the autogenerated configuration options.

Driver vendors can send in patches for these, or create bugs.

Full documentation by vendors

If a vendor wants full documentation in the Configuration Reference, they have to add to the wiki page a contact editor that will take care of the vendor driver documentation. The Documentation team will assign bugs to the contact person, include the contact person in reviews for the vendor driver, and expects timely responses.

If vendor driver documentation becomes outdated and the contact person is not reacting to requests, the Documentation team will change the full documentation to a minimal version.

The documentation team will review vendor drivers and ensure that the various driver documents follow a consistent standard.