Revision as of 19:20, 1 July 2012

NOTE: this wiki page is acting as a stand-in for real Quantum developer documentation. Please contribute as you find mistakes or gaps.

Before you Jump into the Code

Before developing a plugin yourself, make sure you know how Quantum works by reading the Quantum Admin Guide and asking questions.

Then try to run it yourself using devstack . One example of how to run Quantum with devstack is here: QuantumDevstack

Join the netstack team on Launchpad and subscribe to the team email list.

Making a First Code Commit

The best way to get started with Quantum is probably to try and fix a minor bug or add a test case. For ideas, see: QuantumStarterBugs .

After making any changes to the code, be sure that unit tests still run cleanly.

When running from source, be sure you know how to run unit tests, as you'll need to do this before submitting any code:

./run_tests.sh -N

This will also perform checks for pep8 compliance. All pep8 issues must be fixed, or a patch will be rejected in review.

Finally, see these instructions on OpenStack Gerritt Workflow to understand how to submit code for review and inclusion within Quantum.

Developing a Quantum Plugin

If you are trying to enable the use of OpenStack with a new network switching technology, then you probably want to develop a Quantum plugin. You've come to the right place.

What is a Quantum Plugin?

Quantum exposes a logical API to define network connectivity between devices from other OpenStack services (e.g., vNICs from Nova VMs). The logical connectivity described using the API must be translated into actually configuration on virtual and/or physical switches. This is where a Quantum plugin comes in. The Quantum plugin is able to talk to one or more types of switches and dynamically reconfigures the switches based on API calls.

What Code Do I Need to Write

The Quantum code-base has a python API that corresponds to the set of API calls you must implement to be a Quantum plugin. Within the source code directory, look at quantum/quantum_plugin_base.py .

The code-base helps out by providing some useful sqlalchemy bindings to store logical API entities (networks, ports) if you choose to build your plugin around a SQL database.

A plugin usually consists of code to:

• Store information about the current logical network configuration (e.g., a SQL database)
• Determine and store information about the "mapping" of the logical model to the physical network (e.g., picking a VLAN to represent a logical network).
• Communicate with one or more types of switches to configure them according to implement that mapping. This may be in the form of an agent running on the hypervisor, or code that remotely logs into a switch and reconfigures it.

Also, if your switching technology requires nova-compute to create vNICs in a special way, you may need to create a special "vif-plugging" module to be used with your switch. See below for examples.

There should not be a need to modify the QuantumManager code in nova/network/quantum, as this code uses only the logical Quantum API.

Useful Next Steps

• Read the Quantum Overview in the Admin guide to get an understanding of the basic components: http://docs.openstack.org/incubation/openstack-network/admin/content/Overview-d1e369.html
• Browse the Quantum API guide to understand the API that each plugin must implement: http://docs.openstack.org/incubation/openstack-network/developer/quantum-api-1.0/content/
• Get the Quantum code (http://launchpad.net/quantum) and run it according to the admin guide.
• Check out the existing plugins in the quantum/plugins directory to get an idea of what a plugin looks like in practice
• See an example of nova-compute vif-plugging. In the nova codebase, see nova/virt/libvirt/vif.py. The Quantum codebase also include a vif-plug driver that can be used to give nova 802.1qbh capabilities: quantum/plugins/cisco/nova/vif_direct.py
• Join the netstack team on launchpad (http://launchapd.net/~netstack/) and subscribe to the mailing list. You can send more detailed questions about the Quantum code and your plugin development to the team list.

Adding a Plugin to the Public Quantum Repository

Quantum plugins may be open source or proprietary. Some of the open source plugins are maintained in the main Quantum repository (http://www.github.com/openstack/quantum), while others are maintained in their own separate repository. As a project, we encourage plugins to be kept in the main repository for several reasons (a more cohesive developer community, better code sharing across plugins, and more uniform testing of plugins). However, we must also make sure that any plugins in the main repository remain well maintained. As a result, any plugin that is in the main repo must have at least one active member of the quantum core developer team willing to maintain it. This may be achieved by having an existing core dev agree to maintain a plugin, or by having one of the developers of the plugin become a member of the core developer team.

Note: being a core developer includes community duties beyond just the maintenance of a particular plugin. This includes participating in team meetings, a minimum of 2-3 hours a week of code reviews, and an expectation that the developer will also help with other development tasks that are generally helpful to the community.

Plugin FAQ

• Q: Can I run multiple plugins at the same time?
• A: No, only a single plugin can be run at a time, for a given Quantum API. That is because a "plugin" is really chunk of code that called to "implement" a particular API call. Just because there is one plugin, however, does not mean that you can only talk to one type of switch. One "plugin" can have multiple "drivers" that talk to different types of switches. For example, the Cisco plugin talks to multiple types of switches. There is no formal driver interface, but we encourage people to write the code that talks to a switch in a general way such that other plugins will be able to leverage it. A "driver" will usually be code that is able to talk to a particular switch model or family of switches. "drivers" usually will have methods for standard provisioning operations, like putting a port on a particular VLAN as the result of an attachment. One could even create a "meta-plugin" that calls code from two different existing plugins, if the writer of the meta-plugin knows how two plugins can operate correctly in concert. A key design goal for writing plugin code is that code should be written as a library (particularly "driver" code), so that multiple plugins can re-use code.

API Extensions

API Extensions allow a plugin to add extend the Quantum API in order to expose more information. This information could be required to implement advanced functionality that is specific to a particular plugin, or to expose a capability before it has been incorporated into an official Quantum API.

We strongly believe that the right way to "propose" new functionality for an official API is to first expose it as an extension. Code is a very concrete definition, and writing the code and an implementation of that code often exposes important details that might not have come up if the discussion of an API was merely abstract.

• Creating Extensions:
  • Extension files should be placed in the extensions folder located at: quantum/extensions .
  • The extension file should have a class with the same name as the filename. This class should implement the contract required by the extension framework. See ExtensionDescriptor class in quantum/common/extensions.py for details.
  • To stop a file in the extensions folder from being loaded as an extension, the filename should start with an "_". For an example of an extension file look at Foxinsocks class in quantum/tests/unit/extensions/foxinsocks.py. The unit tests in server/lib/tests/unit/test_extensions.py document all the ways in which you can use extensions
• Associating plugins with extensions:
  • A Plugin can advertise all the extensions it supports through the 'supported_extension_aliases' attribute. Eg:

      class SomePlugin:
        ...
        supported_extension_aliases = ['extension1_alias',
                                     'extension2_alias',
                                     'extension3_alias']
      Any extension not in this list will not be loaded for the plugin

• Extension Interfaces for plugins (optional). The extension can mandate an interface that plugins have to support with the 'get_plugin_interface' method in the extension. For an example see the FoxInSocksPluginInterface in foxinsocks.py. The QuantumEchoPlugin lists foxinsox in its supported_extension_aliases and implements the method from FoxInSocksPluginInterface.

There are three types of extensions in Quantum:

• Resources introduce a new "entity" to the API. In Quantum, current entities are are "networks" and "ports".
• Action extensions tend to be "verbs" that act on a resource. For example, in Nova, there is a "server" resources, and a "rebuild" action on that server resource: http://docs.openstack.org/cactus/openstack-compute/developer/openstack-compute-api-1.1/content/Rebuild_Server-d1e3538.html#d2278e1430 . Core Quantum API doesn't really use "actions" as part of the core API, but extensions certainly could.
• Request extensions allow one to add new values to existing requests objects. For example, if you were doing a POST to create a server, but wanted to add a new 'widgetType' attribute for the server object.

Looking at Foxinsox, along with the tests that use it can be helpful here:

• quantum/tests/unit/extensions/foxinsocks.py
• quantum/tests/unit/test_extensions.py

You can also look at other extensions in quantum/extensions, or even nova extensions in nova/api/openstack/compute/contrib/ (these are documented here: http://nova.openstack.org/api_ext/index.html)

Usually the best thing to do is find another extension that does something similar to what you are doing, then use it as a template.

Building Quantum Packages

See QuantumPackaging for information about distros that package Quantum, and how you can modify that packaging.