rabbitmq_policy
rabbitmq_policy manages one policy of a virtual host of a RabbitMQ server.
RabbitMQ is a message broker: a server that takes messages from programs and
hands them to other programs through queues. A virtual host is a separate
set of queues and exchanges inside one server. A policy gives settings,
such as the most messages a queue may hold, to every queue or exchange of a
virtual host whose name matches the policy's pattern. The module runs
RabbitMQ's own program rabbitmqctl as the account rabbitmq on the
node of the server; a node is a Linux server that MMX manages.
In a RabbitMQ cluster, policies belong to the whole cluster: let one node of
the cluster run the rabbitmq_policy node tasks.
Set up
The module installs nothing. RabbitMQ's package brings the programs that the
module runs, and a systemd_service task starts the server. The playbook of
the example project
rabbitmq-server-for-one-application
starts with the node tasks that do both; a node task is one entry of a
playbook's node_tasks, one action that a node performs. Each task has the
condition that picks its distribution, so the same playbook serves a fleet
with several distributions:
# mmx run configure
fleet_stages:
- id: configure
nodes: all
node_tasks:
# Debian and Ubuntu: RabbitMQ from the distribution's own packages.
# logrotate rotates the server's log files; on Debian the package only
# recommends it, and a server may install no recommended packages.
- when: {equals: ["{{ .node.package_manager }}", apt]}
apt_package: {packages: [{name: rabbitmq-server, version: newest_when_first_installed}, {name: logrotate, version: newest_when_first_installed}]}
# Rocky Linux and AlmaLinux package no RabbitMQ. The RabbitMQ project
# serves two package repositories for them: one with Erlang, the
# language that RabbitMQ is written in, and one with the server. Each
# repository signs its packages with its own key, which MMX fetches and
# checks against the SHA-256 here. The repositories hold Erlang for
# x86_64 nodes only.
- when: {equals: ["{{ .node.package_manager }}", dnf]}
dnf_repository:
name: rabbitmq-erlang
description: Erlang for RabbitMQ, from the RabbitMQ project
baseurl:
- https://yum1.rabbitmq.com/erlang/el/9/$basearch
- https://yum2.rabbitmq.com/erlang/el/9/$basearch
signing_key_url: https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key
signing_key_sha256: 84df2e5fd80d464c3eb9acd2f751b2f6a723438200915dd50fbf12f08698e4ec
- when: {equals: ["{{ .node.package_manager }}", dnf]}
dnf_repository:
name: rabbitmq-server
description: RabbitMQ server, from the RabbitMQ project
baseurl:
- https://yum2.rabbitmq.com/rabbitmq/el/9/noarch
- https://yum1.rabbitmq.com/rabbitmq/el/9/noarch
signing_key_url: https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key
signing_key_sha256: 17b3eeb98b7aabe659b0e2579715d1ae4e328b58a401434599495779c59ac73a
- when: {equals: ["{{ .node.package_manager }}", dnf]}
dnf_package: {packages: [{name: erlang, version: newest_when_first_installed}, {name: rabbitmq-server, version: newest_when_first_installed}, {name: logrotate, version: newest_when_first_installed}]}
# No package starts the server under MMX; this task does, and it keeps
# the server starting at boot.
- systemd_service:
name: rabbitmq-server
state: running
start_at_boot: true
The repositories of the RabbitMQ project always hold the newest RabbitMQ.
MMX fetches each repository's key on the controller machine, the machine
where you run mmx. On Debian and Ubuntu too, the systemd_service task is
the server's first start: MMX keeps a package from starting its service
while it installs.
Inputs
| Input | Meaning | When omitted |
|---|---|---|
name |
The policy's name, such as limit-queue-length. It must not be empty or start with a hyphen (-). |
Required. |
virtual_host |
The virtual host that holds the policy, such as shop. RabbitMQ's own default virtual host is named /. |
Required. |
state |
present or absent. absent removes the policy and accepts only name and virtual_host. |
present. |
pattern |
A regular expression. The policy applies to the queues or exchanges whose name it matches: ".*" matches every name, "^orders\\." the names that start with orders.. |
Required for present. |
apply_to |
What the policy applies to: queues, exchanges, all, classic_queues, quorum_queues, or streams. RabbitMQ before 3.12 takes only the first three. |
Required for present. |
definition |
A mapping of RabbitMQ's policy keys to their values, such as max-length: 100000. It needs at least one key. Write a whole number without a fraction. |
Required for present. |
priority |
A whole number. When several policies match one queue, RabbitMQ applies only the one with the highest priority. | Required for state: present. |
The keys of definition are RabbitMQ's own, and RabbitMQ decides which it
takes: the
RabbitMQ documentation lists
them. Common ones are max-length (the most messages in a queue),
message-ttl (how many milliseconds a message stays), expires,
overflow, and dead-letter-exchange.
A policy that differs in any part is written again as a whole: RabbitMQ has no command that changes one part of a policy.
Outputs
| Output | Meaning |
|---|---|
created |
true when the task created the policy. In a dryrun: true when a run would create it. |
A later node task reads the created output as .node_tasks.<id>.created.
What a dryrun reports
A dryrun asks the server the same questions as a run and changes nothing.
- A policy to create, change, or remove:
would_change, with the reason, such aswould create the policy limit-queue-length of the virtual host shop, orwould change the policy limit-queue-length of the virtual host shop: definition, priority, which names the inputs that differ. not_checkedwhile RabbitMQ's programs are not installed, while the server does not answer, and while the virtual host of a policy withstate: presentdoes not exist: an earlier node task of the same run may install the package, start the server, or create the virtual host.- A failure, as in a run, for an input that breaks a rule.
- A dryrun cannot know whether RabbitMQ accepts the definition, the
pattern, or the value of
apply_to: only the command that sets a policy checks them, and what it accepts depends on RabbitMQ's version. A dryrun reportswould_changefor a policy that RabbitMQ will refuse. The run then fails with RabbitMQ's message, and MMX does not try it again. A refused policy changes nothing on the server: the policy that was there before stays. The task's result still sayschanged, because MMX counts every changing command that ran and cannot see what a refused command did. - What the questions leave on the node: nothing while the server runs.
While it does not run, on a node with the packages of the RabbitMQ
project,
rabbitmq-diagnosticsstarts a process namedepmdas the accountrabbitmq, and that process stays.epmdis the small program that tells RabbitMQ's programs on which port the server listens for them; the server would start it too. On a server that has never run,rabbitmq-diagnosticsalso creates the file/var/lib/rabbitmq/.erlang.cookie, the key with which RabbitMQ's programs reach the server; the server's first start would create it.
Examples
Let no queue of the virtual host shop hold more than 100000 messages:
- rabbitmq_policy:
name: limit-queue-length
virtual_host: shop
pattern: ".*"
apply_to: queues
definition:
max-length: 100000
priority: 0
Give the order queues an hour for each message, and send a message that
was not taken in that time to the exchange expired-orders. The priority
makes orders-expire apply instead of limit-queue-length for the order
queues:
- rabbitmq_policy:
name: orders-expire
virtual_host: shop
pattern: "^orders\\."
apply_to: queues
priority: 10
definition:
message-ttl: 3600000
dead-letter-exchange: expired-orders
Remove the policy limit-queue-length of the virtual host shop:
- rabbitmq_policy:
name: limit-queue-length
virtual_host: shop
state: absent
Errors and what they mean
Every reason starts with rabbitmq_policy.
| The reason holds | What it means, and what to do |
|---|---|
rabbitmq_policy.pattern: is required for state: present (also apply_to, definition, priority) |
A task that sets a policy lacks one of its required parts. The task fails without another try, in a dryrun too. Add the input. |
rabbitmq_policy.definition: must ... |
definition is no mapping, or it is empty. Write at least one policy key with its value. |
rabbitmq_policy.state: absent accepts only name and virtual_host; remove INPUT |
A task that removes the policy also describes it. Remove the named input. |
the virtual host NAME does not exist; create it with a rabbitmq_virtual_host task in an earlier node task |
The server has no such virtual host. A run fails without another try. A task with state: absent is unchanged instead. Put a rabbitmq_virtual_host task before this task, or correct the name. |
RabbitMQ refuses the policy NAME of the virtual host NAME: Validation failed: ... |
RabbitMQ checked the policy and does not take it; the text behind Validation failed: is its own reason. are not recognised policy settings: this RabbitMQ does not know a key of definition. apply-to '...' unrecognised: this RabbitMQ is older than 3.12. is not a valid ...: a value has the wrong kind, such as a text for a number. pattern should be regular expression: RabbitMQ cannot read pattern. The task fails without another try. The policy that was there before stays, and the result still says changed: MMX counts every changing command that ran. Correct the input that RabbitMQ names. |
the program ... is not installed; install the package rabbitmq-server in an earlier node task |
The node has no RabbitMQ, or has it from another source than a package, so that /usr/lib/rabbitmq/bin/rabbitmqctl is missing. Put the tasks of Set up before this task. |
the RabbitMQ server on this node does not answer; start its service in an earlier node task (rabbitmq-diagnostics check_running said: ...) |
The server is stopped or still starting. MMX tries a run again, as every failed node task. Start the server with a systemd_service task. When it does not start, read its journal: journalctl -u rabbitmq-server. |
reading ..., setting the policy NAME of the virtual host NAME: ..., removing the policy NAME of the virtual host NAME: ... |
A command of rabbitmqctl failed. The text behind the colon is RabbitMQ's own message; act on it. MMX tries the task again. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The integration suite tests/integration/rabbitmq.py runs the module against
a real server on these distributions:
| Distribution | RabbitMQ | Comes from |
|---|---|---|
| Debian 12 | 3.10.8 | the distribution's package |
| Debian 13 | 4.0.5 | the distribution's package |
| Ubuntu 24.04 | 3.12.1 | the distribution's package |
| Ubuntu 26.04 | 4.0.5 | the distribution's package |
| Rocky Linux 9, AlmaLinux 10 | 4.3.6 | the RabbitMQ project's repositories, which serve the newest release |
What RabbitMQ accepts in a policy depends on its version. On the test nodes,
RabbitMQ 3.9 and 3.10 refused classic_queues, quorum_queues, and
streams for apply_to; RabbitMQ 3 took the keys ha-mode, ha-params,
and ha-sync-mode, and RabbitMQ 4 refused them.
Why it works this way
-
priorityis required forpresent. The right value depends on the task; settings with no safe guess are required. -
The module has no list of RabbitMQ's policy keys and versions. RabbitMQ checks a policy when it is set and says what is wrong. The module hands the policy over as written and reports RabbitMQ's own message, so it works with the keys of a RabbitMQ that is newer than the module.
-
The module compares the stored definition value by value. RabbitMQ gives a definition back as a text with its keys in another order than the task wrote them. Comparing the texts would report a change on every run.
-
A whole number is sent without a fraction. RabbitMQ refuses
1000.0for a key that takes a whole number. -
The module reads the list of virtual hosts first. RabbitMQ's list of policies fails for a virtual host that does not exist, and the module must tell that from other failures: an earlier node task may create the virtual host.
-
The module runs the real
rabbitmqctlprogram as the accountrabbitmq(runuser -u rabbitmq -- /usr/lib/rabbitmq/bin/rabbitmqctl), not the commandrabbitmqctl. The command of Debian and Ubuntu hands its arguments to a shell: on the test nodes a definition with a quote or two backslashes came out different, and a command inside an argument ran. -
It asks first whether the server runs (
rabbitmq-diagnostics check_running). RabbitMQ's programs end with the same exit code for a stopped server and for a refused policy, and a server that still starts already answers a ping. -
A name must not start with a hyphen. RabbitMQ's programs read such an argument as an option. A pattern may start with a hyphen.
This page is official_extra_modules/rabbitmq_policy/README.md in the MMX repository.