Skip to content

Commit

Permalink
Bug #875995: Quantum README fixes
Browse files Browse the repository at this point in the history 
Fix the most obvious issues with the Quantum README and add pointers to
external documentation resources.

In a future commit, we plan to remove most of the content in the README
and leave it just as references to external documentation.  However,
this change requires us to be able to support multiple version of our
external documentation (not yet possible) and have a good location for
developer documentation.

Change-Id: I57d7f99f070d17564b7a5fdcef8ae8ad2a6575a6
  • Loading branch information
Dan Wendlandt committed Nov 9, 2011
1 parent 687f3d2 commit 8a584f4
Showing 1 changed file with 81 additions and 81 deletions.
162 changes: 81 additions & 81 deletions README
View file
Expand Up @@ -3,49 +3,29 @@
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)

Expand All @@ -54,11 +34,6 @@ 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

Expand All @@ -72,16 +47,24 @@ this)
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.
Expand All @@ -107,24 +90,24 @@ this)

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
not necessarily on the same machine where Quantum is running; both Keystone's
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

Expand All @@ -139,26 +122,25 @@ auth_admin_token Keystone token for administrative access
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
token in this header, and validate it with the Keystone service.

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:

Expand All @@ -172,52 +154,70 @@ auth_admin_token = 9a82c95a-99e9-4c3a-b5ee-199f6ba7ff04
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
Expand All @@ -227,7 +227,7 @@ There are a few requirements to writing your own 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
Expand Down

0 comments on commit 8a584f4

Please sign in to comment.