e55a83e832
Move the public API out of oslo.messaging to oslo_messaging. Retain the ability to import from the old namespace package for backwards compatibility for this release cycle. bp/drop-namespace-packages Co-authored-by: Mehdi Abaakouk <mehdi.abaakouk@enovance.com> Change-Id: Ia562010c152a214f1c0fed767c82022c7c2c52e7
194 lines
6.1 KiB
ReStructuredText
194 lines
6.1 KiB
ReStructuredText
-------------------------
|
|
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)
|