From bc0033a9c06de59cd9343781ee05a92ea34e29e4 Mon Sep 17 00:00:00 2001 From: Kenneth Giusti Date: Thu, 11 Sep 2014 13:46:27 -0400 Subject: [PATCH] Add documentation explaining how to use the AMQP 1.0 driver Change-Id: I076ccff2b34be3ecf07cdcd0bb9753997c1e3218 Closes-Bug: #1367910 --- doc/source/AMQP1.0.rst | 193 +++++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 2 files changed, 194 insertions(+) create mode 100644 doc/source/AMQP1.0.rst diff --git a/doc/source/AMQP1.0.rst b/doc/source/AMQP1.0.rst new file mode 100644 index 000000000..5dab29bfe --- /dev/null +++ b/doc/source/AMQP1.0.rst @@ -0,0 +1,193 @@ +------------------------- +AMQP 1.0 Protocol Support +------------------------- + +.. currentmodule:: oslo.messaging + +============ +Introduction +============ + +This release of oslo.messaging includes an experimental driver that +provides support for version 1.0 of the Advanced Message Queuing +Protocol (AMQP 1.0, ISO/IEC 19464). + +The current implementation of this driver is considered +*experimental*. It is not recommended that this driver be used in +production systems. Rather, this driver is being provided as a +*technical preview*, in hopes that it will encourage further testing +by the AMQP 1.0 community. + +More detail regarding the driver's implementation is available from the `specification`_. + +.. _specification: https://git.openstack.org/cgit/openstack/oslo-specs/tree/specs/juno/amqp10-driver-implementation.rst + +============= +Prerequisites +============= + +This driver uses the Apache QPID `Proton`_ AMQP 1.0 protocol engine. +This engine consists of a platform specific library and a python +binding. The driver does not directly interface with the engine API, +as the API is a very low-level interface to the AMQP protocol. +Instead, the driver uses the pure python `Pyngus`_ client API, which +is layered on top of the protocol engine. + +.. _Proton: http://qpid.apache.org/proton/index.html +.. _Pyngus: https://github.com/kgiusti/pyngus + +In order to run the driver the Proton Python bindings, Proton +library, Proton header files, and Pyngus must be installed. + +Pyngus is available via `Pypi`__. + +.. __: https://pypi.python.org/pypi/pyngus + +While the Proton Python bindings are available via `Pypi`__, it +includes a C extension that requires the Proton library and header +files be pre-installed in order for the binding to install properly. +If the target platform's distribution provides a pre-packaged version +of the Proton Python binding (see packages_ below), it is recommended +to use these pre-built packages instead of pulling them from Pypi. + +.. __: https://pypi.python.org/pypi/python-qpid-proton + +The driver also requires a *broker* that supports version 1.0 of the +AMQP protocol. + +The driver has only been tested using `qpidd`_ in a `patched +devstack`_ environment. The version of qpidd **must** be at least +0.26. qpidd also uses the Proton engine for its AMQP 1.0 support, so +the Proton library must be installed on the system hosting the qpidd +daemon. + +.. _qpidd: http://qpid.apache.org/components/cpp-broker/index.html +.. _patched devstack: https://review.openstack.org/#/c/109118/ + +At present, RabbitMQ does not work with this driver. This driver +makes use of the *dynamic* flag on the link Source to automatically +provision a node at the peer. RabbitMQ's AMQP 1.0 implementation has +yet to implement this feature. + +See the `specification`_ for additional information regarding testing +done on the driver. + +============= +Configuration +============= + +driver +------ + +It is recommended to start with the default configuration options +supported by the driver. The remaining configuration steps described +below assume that none of the driver's options have been manually +overridden. + + **Note Well:** The driver currently does **not** support the generic + *amqp* options used by the existing drivers, such as + *amqp_durable_queues* or *amqp_auto_delete*. Support for these are + TBD. + +qpidd +----- + +First, verify that the Proton library has been installed and is +imported by the qpidd broker. This can checked by running:: + + $ qpidd --help + +and looking for the AMQP 1.0 options in the help text. If no AMQP 1.0 +options are listed, verify that the Proton libraries are installed and +that the version of qpidd is greater than or equal to 0.26. + +Second, configure the address patterns used by the driver. This is +done by adding the following to /etc/qpid/qpidd.conf:: + + queue-patterns=exclusive + queue-patterns=unicast + topic-patterns=broadcast + +These patterns, *exclusive*, *unicast*, and *broadcast* are the +default values used by the driver. These can be overridden via the +driver configuration options if desired. If manually overridden, +update the qpidd.conf values to match. + +services +-------- + +The new driver is selected by specifying **amqp** as the transport +name. For example:: + + from oslo import messaging + from olso.config import cfg + + amqp_transport = messaging.get_transport(cfg.CONF, + "amqp://me:passwd@host:5672") + + +The new driver can be loaded and used by existing applications by +specifying *amqp* as the RPC backend in the service's configuration +file. For example, in nova.conf:: + + rpc_backend = amqp + +.. _packages: + +====================== +Platforms and Packages +====================== + +Pyngus is available via Pypi. + +Pre-built packages for the Proton library and qpidd are available for +some popular distributions: + +RHEL and Fedora +--------------- + +Packages exist in EPEL for RHEL/Centos 7, and Fedora 19+. +Unfortunately, RHEL/Centos 6 base packages include a very old version +of qpidd that does not support AMQP 1.0. EPEL's policy does not allow +a newer version of qpidd for RHEL/Centos 6. + +The following packages must be installed on the system running the +qpidd daemon: + +- qpid-cpp-server (version 0.26+) +- qpid-proton-c + +The following packages must be installed on the systems running the +services that use the new driver: + +- Proton libraries: qpid-proton-c-devel +- Proton python bindings: python-qpid-proton +- pyngus (via Pypi) + +Debian and Ubuntu +----------------- + +Packages for the Proton library, headers, and Python bindings are +available in the Debian/Testing repository. Proton packages are not +yet available in the Ubuntu repository. The version of qpidd on both +platforms is too old and does not support AMQP 1.0. + +Until the proper package version arrive the latest packages can be +pulled from the `Apache Qpid PPA`_ on Launchpad:: + + sudo add-apt-repository ppa:qpid/released + +.. _Apache Qpid PPA: https://launchpad.net/~qpid/+archive/ubuntu/released + +The following packages must be installed on the system running the +qpidd daemon: + +- qpidd (version 0.26+) +- libqpid-proton2 + +The following packages must be installed on the systems running the +services that use the new driver: + +- Proton libraries: libqpid-proton2-dev +- Proton python bindings: python-qpid-proton +- pyngus (via Pypi) diff --git a/doc/source/index.rst b/doc/source/index.rst index d8646fcfb..3fa2a414c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -20,6 +20,7 @@ Contents exceptions opts conffixture + AMQP1.0 contributing Release Notes