community.rabbitmq.rabbitmq – Retrieve messages from an AMQP/AMQPS RabbitMQ queue.

Note

This plugin is part of the community.rabbitmq collection (version 1.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.rabbitmq.

To use it in a playbook, specify: community.rabbitmq.rabbitmq.

Synopsis

  • This lookup uses a basic get to retrieve all, or a limited number count, messages from a RabbitMQ queue.

Requirements

The below requirements are needed on the local controller node that executes this lookup.

Parameters

Parameter Choices/Defaults Configuration Comments
count
string
How many messages to collect from the queue.
If not set, defaults to retrieving all the messages from the queue.
queue
string / required
The queue to get messages from.
url
string / required
An URI connection string to connect to the AMQP/AMQPS RabbitMQ server.
For more information refer to the URI spec https://www.rabbitmq.com/uri-spec.html.

Notes

Note

  • This lookup implements BlockingChannel.basic_get to get messages from a RabbitMQ server.
  • After retrieving a message from the server, receipt of the message is acknowledged and the message on the server is deleted.
  • Pika is a pure-Python implementation of the AMQP 0-9-1 protocol that tries to stay fairly independent of the underlying network support library.
  • More information about pika can be found at https://pika.readthedocs.io/en/stable/.
  • This plugin is tested against RabbitMQ. Other AMQP 0.9.1 protocol based servers may work but not tested/guaranteed.
  • Assigning the return messages to a variable under vars may result in unexpected results as the lookup is evaluated every time the variable is referenced.
  • Currently this plugin only handles text based messages from a queue. Unexpected results may occur when retrieving binary data.

Examples

- name: Get all messages off a queue
  debug:
    msg: "{{ lookup('community.rabbitmq.rabbitmq', url='amqp://guest:[email protected]:5672/%2F', queue='hello') }}"


# If you are intending on using the returned messages as a variable in more than
# one task (eg. debug, template), it is recommended to set_fact.

- name: Get 2 messages off a queue and set a fact for re-use
  set_fact:
    messages: "{{ lookup('community.rabbitmq.rabbiotmq', url='amqp://guest:[email protected]:5672/%2F', queue='hello', count=2) }}"

- name: Dump out contents of the messages
  debug:
    var: messages

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_list
list / elements=string
success
A list of dictionaries with keys and value from the queue.

content_type
string
success
The content_type on the message in the queue.

delivery_mode
string
success
The delivery_mode on the message in the queue.

delivery_tag
string
success
The delivery_tag on the message in the queue.

exchange
string
success
The exchange the message came from.

headers
dictionary
success
The headers for the message returned from the queue.

json
dictionary
success
If application/json is specified in content_type, json will be loaded into variables.

message_count
string
success
The message_count for the message on the queue.

msg
string
success
The content of the message.

redelivered
boolean
success
The redelivered flag. True if the message has been delivered before.

routing_key
string
success
The routing_key on the message in the queue.



Authors

  • John Imison <@Im0>

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/rabbitmq/rabbitmq_lookup.html