blueprint refactor-readme-to-manual
Removes most of the content from the README to avoid it becoming outdated and stale given that our currently maintained docs are now on http://docs.openstack.org . In some cases, including keystone config, extension writing, etc. this means text from the README is being transferred directly from the README to an external doc so we make sure we don't lose anything. Change-Id: Ie08db4bd4854bb45e6777b1e0abe37f51d3e5c5c
This commit is contained in:
Dan Wendlandt
parent
47767d4f52
commit
a03948f348
229
README
229
README
@ -9,231 +9,16 @@
|
|||||||
site for downloading the latest code, asking for help, and filing bugs.
|
site for downloading the latest code, asking for help, and filing bugs.
|
||||||
|
|
||||||
The latest and most in-depth documentation on how to use Quantum is
|
The latest and most in-depth documentation on how to use Quantum is
|
||||||
available at: http://docs.openstack.org/incubation . This includes
|
available at: http://docs.openstack.org . This includes:
|
||||||
both an "Administrator Guide" and the official "API Reference".
|
|
||||||
|
Quantum Administrator Guide
|
||||||
|
http://docs.openstack.org/incubation/openstack-network/admin/content/
|
||||||
|
|
||||||
|
Quantum API Reference:
|
||||||
|
http://docs.openstack.org/incubation/openstack-network/developer/quantum-api-1.0/content/
|
||||||
|
|
||||||
The start of some developer documentation is available at:
|
The start of some developer documentation is available at:
|
||||||
http://wiki.openstack.org/QuantumDevelopment
|
http://wiki.openstack.org/QuantumDevelopment
|
||||||
|
|
||||||
For help using or hacking on Quantum, you can send mail to
|
For help using or hacking on Quantum, you can send mail to
|
||||||
netstack@lists.launchpad.net .
|
netstack@lists.launchpad.net .
|
||||||
|
|
||||||
############ For Users Installing and Running Quantum #########
|
|
||||||
|
|
||||||
# -- Dependencies
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
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>
|
|
||||||
|
|
||||||
|
|
||||||
# -- 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 ~/.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 the options in
|
|
||||||
the "plugins" directory, or one provided by a third-party.
|
|
||||||
|
|
||||||
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.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.
|
|
||||||
|
|
||||||
# -- 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 CLI command looks like this:
|
|
||||||
|
|
||||||
$ quantum -v create_net t1 network1
|
|
||||||
Created a new Virtual Network with ID:e754e7c0-a8eb-40e5-861a-b182d30c3441
|
|
||||||
|
|
||||||
# -- Keystone Authentication and Authorization
|
|
||||||
|
|
||||||
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 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
|
|
||||||
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 (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.
|
|
||||||
|
|
||||||
|
|
||||||
###### 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 the "plugins" directory.
|
|
||||||
|
|
||||||
There are a few requirements to writing your own plugin:
|
|
||||||
|
|
||||||
1) Your plugin should implement all methods defined in the
|
|
||||||
QuantumPluginBase class defined in
|
|
||||||
server/lib/quantum/quantum_plugin_base.py
|
|
||||||
|
|
||||||
2) Copy your Quantum plug-in over to the "plugins" directory
|
|
||||||
|
|
||||||
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 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
|
|
||||||
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
|
|
||||||
'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
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user