From: Dan Wendlandt Date: Mon, 23 Jan 2012 05:07:37 +0000 (-0800) Subject: bug 920299: remove duplicate + outdate README X-Git-Url: https://review.fuel-infra.org/gitweb?a=commitdiff_plain;h=543bf67833ae52b117a0c014d7691d1d10b34fda;p=openstack-build%2Fneutron-build.git bug 920299: remove duplicate + outdate README Change-Id: I2122e69f7394420c912ab700da5bc91dd77f84af --- diff --git a/quantum/README b/quantum/README deleted file mode 100644 index cecb5f484..000000000 --- a/quantum/README +++ /dev/null @@ -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 - -# -- 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