bug 920299: remove duplicate + outdate README
Change-Id: I2122e69f7394420c912ab700da5bc91dd77f84af
This commit is contained in:
Dan Wendlandt
239
quantum/README
239
quantum/README
@@ -1,239 +0,0 @@
|
||||
# -- Welcome!
|
||||
|
||||
You have come across a cloud computing network fabric controller. It has
|
||||
identified itself as "Quantum." It aims to tame your (cloud) networking!
|
||||
|
||||
# -- Basics:
|
||||
|
||||
1) Quantum REST API: Quantum supports a REST-ful programmatic interface to
|
||||
manage your cloud networking fabric.
|
||||
|
||||
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:
|
||||
|
||||
a) Allows for ANY open-source project or commercial vendor to write a
|
||||
Quantum plug-in.
|
||||
|
||||
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
|
||||
|
||||
# -- 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.
|
||||
|
||||
# -- Dependencies
|
||||
|
||||
The following 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)
|
||||
|
||||
2) Install pip:
|
||||
$ easy_install pip==dev
|
||||
3) Install packages with pip:
|
||||
$ pip install <package name>
|
||||
|
||||
# -- Running from the source code
|
||||
|
||||
bin/quantum-server #Server
|
||||
bin/quantum #CLI
|
||||
python run_tests.py #Tests
|
||||
|
||||
# -- Installing from the source code
|
||||
|
||||
You have 3 options:
|
||||
a) sudo python setup.py install
|
||||
# Installs to /usr/lib, /usr/bin, /etc, etc
|
||||
|
||||
b) python setup.py install --user
|
||||
# Install into $HOME/.local/...
|
||||
|
||||
c) python setup.py install --venv
|
||||
# Creates and installs into a virtual-env at ~/.venv
|
||||
|
||||
# -- Configuring Quantum plug-in
|
||||
|
||||
1) Identify your desired plug-in. Choose a plugin from one of he options in
|
||||
the quantum/plugins directory.
|
||||
|
||||
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)
|
||||
|
||||
3) Read the plugin specific README, this is usually found in the same
|
||||
directory as your Quantum plug-in, and follow configuration instructions.
|
||||
|
||||
# -- Launching the Quantum Service
|
||||
|
||||
# If you're running from the source
|
||||
bin/quantum-server
|
||||
|
||||
# If you installed Quantum
|
||||
quantum-server
|
||||
|
||||
# -- Making requests against the Quantum Service
|
||||
|
||||
Quantum comes with a programmatic CLI that is driven by the Quantum Web
|
||||
Service. You can use the CLI by issuing the following command:
|
||||
|
||||
# If you're running from the source
|
||||
bin/quantum
|
||||
|
||||
# If you installed Quantum
|
||||
quantum
|
||||
|
||||
This will show help all of the available commands.
|
||||
|
||||
An example session looks like this:
|
||||
|
||||
$ export TENANT=t1
|
||||
$ quantum -v create_net $TENANT network1
|
||||
Created a new Virtual Network with ID:e754e7c0-a8eb-40e5-861a-b182d30c3441
|
||||
|
||||
# -- Authentication and Authorization
|
||||
|
||||
Requests to Quantum API are authenticated with the Keystone identity service
|
||||
using a token-based authentication protocol.
|
||||
|
||||
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 = authN authZ extensions quantumapiapp
|
||||
|
||||
The final step concerns configuring access to Keystone. The following attributes
|
||||
must be specified in the [filter:authN] section of quantum.conf:
|
||||
|
||||
auth_host IP address or host name of the server where Keystone is running
|
||||
auth_port Port where the Keystone Admin API is listening
|
||||
auth_protocol Protocol used for communicating with Keystone (http/https)
|
||||
auth_version Keystone API version (default: 2.0)
|
||||
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.
|
||||
If both are specified, auth_admin_token has priority.
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
Either username and password, or an authentication token for an administrative
|
||||
user can be specified in the configuration file:
|
||||
|
||||
- Credentials:
|
||||
|
||||
auth_admin_user = admin
|
||||
auth_admin_password = secrete
|
||||
|
||||
- Admin token:
|
||||
|
||||
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 administrative API.
|
||||
|
||||
|
||||
# -- 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.
|
||||
|
||||
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
|
||||
|
||||
2) Copy your Quantum plug-in over to the quantum/quantum/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"
|
||||
|
||||
4) Launch the Quantum Service, and your plug-in is configured and ready to
|
||||
manage a Cloud Networking Fabric.
|
||||
|
||||
# -- 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,
|
||||
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
|
||||
|
||||
2) Associating plugins with extensions:
|
||||
a) A Plugin can advertize 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
|
||||
|
||||
b) 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.
|
||||
|
||||
# -- Building packages
|
||||
|
||||
rpms:
|
||||
python setup.py build rpm
|
||||
|
||||
debs:
|
||||
python setup.py build deb
|
||||
Reference in New Issue
Block a user