Kenneth Giusti bc0033a9c0 Add documentation explaining how to use the AMQP 1.0 driver

Change-Id: I076ccff2b34be3ecf07cdcd0bb9753997c1e3218
Closes-Bug: #1367910

2014-09-12 12:01:35 -04:00

6.1 KiB

Raw Blame History

AMQP 1.0 Protocol Support

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.

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.

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.

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.

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.

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

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