You have come across a cloud computing network fabric controller. It has
identified itself as "Quantum." It aims to tame your (cloud) networking!
-# -- Basics:
+# -- External Resources:
-1) Quantum REST API: Quantum supports a REST-ful programmatic interface to
- manage your cloud networking fabric.
+ The homepage for Quantum is: http://launchpad.net/quantum . Use this
+ site for downloading the latest code, asking for help, and filing bugs.
-2) Quantum Plugins: Quantum sports a plug-able architecture that allows
- Quantum's REST API to be backed by various entities that can create a
- cloud-class virtual networking fabric. The advantages of this plug-able
- architecture is two-folds:
+ The latest and most in-depth documentation on how to use Quantum is
+ available at: http://docs.openstack.org/incubation . This includes
+ both an "Administrator Guide" and the official "API Reference".
- a) Allows for ANY open-source project or commercial vendor to write a
- Quantum plug-in.
+ The start of some developer documentation is available at:
+ http://wiki.openstack.org/QuantumDevelopment
- b) Allows Quantum users to not be tied down to a single Quantum
- implementation and enables them to switch out a plug-in by simple editing a
- config file - plugins.ini
+ For help using or hacking on Quantum, you can send mail to
+ netstack@lists.launchpad.net .
-# -- Layout
-
- The Quantum project includes 3 core packages:
-
- quantum-common (General utils for Quantum and its plugins)
- quantum-server (The actual Quantum service itself)
- quantum-client (The Quantum CLI and API Python library)
-
- As well as some plugins.
+############ For Users Installing and Running Quantum #########
# -- Dependencies
- The following python packages are required to run quantum. These can be
+ When running from source, view the tools/pip-requires file to see the
+ python packages are required to run quantum. These can be
installed using pip:
- eventlet>=0.9.12
- nose
- Paste
- PasteDeploy
- pep8==0.5.0
- python-gflags
- routes
- simplejson
- webob
- webtest
-
1) Install easy_install (there is probably a distribution specific package for
this)
3) Install packages with pip:
$ pip install <package name>
-# -- Running from the source code
-
- bin/quantum-server #Server
- bin/quantum #CLI
- sh run_tests.sh #Tests
# -- Installing from the source code
c) python setup.py install --venv
# Creates and installs into a virtual-env at ~/.quantum-venv
+
+# -- Configuration Files
+
+ Quantum has two primary configuration files: plugins.ini and quantum.conf .
+ Both are located in the same directory, which is server/etc when running
+ from source, and /etc when fully installed.
+
+
# -- Configuring Quantum plug-in
-1) Identify your desired plug-in. Choose a plugin from one of he options in
- the quantum/plugins directory.
+1) Identify your desired plug-in. Choose a plugin from one of the options in
+ the "plugins" directory, or one provided by a third-party.
-2) Update plug-in configuration by editing the quantum/plugins.ini file and
- modify "provider" property to point to the location of the Quantum plug-in.
- It should specify the class path to the plugin and the class name (i.e. for
- a plugin class MyPlugin in quantum/plugins/myplugin/myplugin.py the
- provider would be: quantum.plugins.myplugin.myplugin.MyPlugin)
+2) Edit the plugins.ini file to point to the location of the Quantum plug-in
+ library. It should specify the class path to the plugin and the
+ class name (i.e. for a plugin class FooPlugin in
+ plugins/foo-plugin/lib/quantum/plugins/foo/foo_plugin.py the
+ provider would be: quantum.plugins.foo_plugin.FooPlugin)
3) Read the plugin specific README, this is usually found in the same
directory as your Quantum plug-in, and follow configuration instructions.
This will show help all of the available commands.
- An example session looks like this:
+ An example CLI command looks like this:
- $ export TENANT=t1
- $ quantum -v create_net $TENANT network1
+ $ quantum -v create_net t1 network1
Created a new Virtual Network with ID:e754e7c0-a8eb-40e5-861a-b182d30c3441
-# -- Authentication and Authorization
+# -- Keystone Authentication and Authorization
-Requests to Quantum API are authenticated with the Keystone identity service
-using a token-based authentication protocol.
+Requests to the Quantum API can be authenticated with the Keystone
+identity service using a token-based authentication protocol. Keystone
+integration is disabled by default.
1) Enabling Authentication and Authorization
The Keystone identity service is a requirement. It must be installed, although
admin API and service API should be running
Authentication and Authorization middleware should be enabled in the Quantum
-pipeline. To this aim, uncomment the following line in /etc/quantum.conf:
+pipeline. To this aim, uncomment the following line in quantum.conf:
pipeline = authN authZ extensions quantumapiapp
auth_admin_user Keystone user with administrative rights
auth_admin_password Password for the user specified with auth_admin_user
-NOTE: aut_admin_token and auth_admin_user/password are exclusive.
+NOTE: aut_admin_token and auth_admin_user/password are exclusive.
If both are specified, auth_admin_token has priority.
-2) Authenticating and Authorizing request for Quantum API
+2) Authenticating and Authorizing request for Quantum API
A user should first authenticate with Keystone, supplying user credentials;
the Keystone service will return an authentication token, together with
-informations concerning token expirations and endpoint where that token can
-be used.
+information concerning token expirations and endpoint where that token can
+be used.
The authentication token must be included in every request for the Quantum
API, in the 'X_AUTH_TOKEN' header. Quantum will look for the authentication
In order to validate authentication tokens, Quantum uses Keystone's
administrative API. It therefore requires credentials for an administrative
-user, which can be specified in Quantum's configuration file
-(etc/quantum.conf)
+user, which can be specified in Quantum's configuration file (quantum.conf)
Either username and password, or an authentication token for an administrative
-user can be specified in the configuration file:
+user can be specified in the configuration file:
- Credentials:
As of the current release, any user for a tenant is allowed to perform
every operation on the networks owned by the tenant itself, except for
plugging interfaces. In order to perform such operation, the user must have
-the Quantum:NetworkAdmin roles. Roles can be configured in Keystone using
+the Quantum:NetworkAdmin roles. Roles can be configured in Keystone using
the administrative API.
+###### For Developers #########
+
+# -- Code Layout
+
+ The Quantum project includes 3 core packages:
+
+ quantum-common (General utils for Quantum and its plugins)
+ quantum-server (The actual Quantum service itself)
+ quantum-client (The Quantum CLI and API Python library)
+
+ As well as some plugins.
+
# -- Writing your own Quantum plug-in
If you wish the write your own Quantum plugin, please refer to some concrete as
-well as sample plugins available in:
-
-../quantum/quantum/plugins/.. directory.
+well as sample plugins available in the "plugins" directory.
There are a few requirements to writing your own plugin:
1) Your plugin should implement all methods defined in the
- quantum/quantum_plugin_base.QuantumPluginBase class
+ QuantumPluginBase class defined in
+ server/lib/quantum/quantum_plugin_base.py
-2) Copy your Quantum plug-in over to the quantum/quantum/plugins/.. directory
+2) Copy your Quantum plug-in over to the "plugins" directory
-3) The next step is to edit the plugins.ini file in the same directory
- as QuantumPluginBase class and specify the location of your custom plugin
- as the "provider"
+3) The next step is to edit plugins.ini and specify the
+ location of your custom plugin as the "provider"
4) Launch the Quantum Service, and your plug-in is configured and ready to
manage a Cloud Networking Fabric.
+
+# -- Running the tests from source code
+
+ sh run_tests.sh
+
+
# -- Extensions
1) Creating Extensions:
- a) Extension files should be placed under ./extensions folder.
- b) 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
- c) To stop a file in ./extensions folder from being loaded as an extension,
+ a) Extension files should be placed in the extensions folder located at
+ server/lib/quantum/extensions .
+ b) 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 common/lib/quantum/common/extensions.py
+ for details
+ c) 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
- ./tests/unit/extensions/foxinsocks.py
- The unit tests in ./tests/unit/test_extensions.py document all the ways in
- which you can use extensions
+ For an example of an extension file look at Foxinsocks class in
+ server/lib/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
2) Associating plugins with extensions:
- a) A Plugin can advertize all the extensions it supports through the
+ a) A Plugin can advertize all the extensions it supports through the
'supported_extension_aliases' attribute. Eg:
-
+
class SomePlugin:
...
- supported_extension_aliases = ['extension1_alias',
+ supported_extension_aliases = ['extension1_alias',
'extension2_alias',
'extension3_alias']
Any extension not in this list will not be loaded for the plugin
'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
+ The QuantumEchoPlugin lists foxinsox in its supported_extension_aliases
and implements the method from FoxInSocksPluginInterface.
# -- Building packages
Code Review / openstack-build / neutron-build.git / commitdiff