RabbitMQ Environment Documentation Template: the One-Sheet

The one-sheet exists so that the first incident on a cluster is not also the first time anyone has looked at it. For the long-form version of what a healthy production cluster looks like, use the production readiness checklist; this page is only the record of what your cluster actually is.

The format is adapted from a one-page environment document that a customer kept in their own wiki, headed with its purpose: to level-set when working with AceMQ Support. It answered most of the questions we would otherwise ask over the first few tickets, which is why we generalised it. When we take over support of a cluster we did not build, onboarding starts with a health check that establishes the same facts: version, topology, queue types, known faults and patch position.

Run these on a node, as the RabbitMQ user, and paste the output into your working copy; most of the sheet is then a transcription exercise. Every command below is in the RabbitMQ CLI documentation.

rabbitmq-diagnostics server_version
rabbitmq-diagnostics erlang_version
rabbitmq-diagnostics status
rabbitmq-diagnostics environment
rabbitmq-diagnostics cluster_status
rabbitmq-diagnostics listeners
rabbitmq-diagnostics check_certificate_expiration
rabbitmq-diagnostics list_deprecated_features
rabbitmq-plugins list
rabbitmqctl list_feature_flags
rabbitmqctl list_vhosts name description tags default_queue_type
rabbitmqctl list_policies
rabbitmqctl list_operator_policies
rabbitmqctl list_queues name type messages
rabbitmqctl export_definitions /path/to/definitions.json

The definitions export contains users and permissions, so store it as a secret, and read the environment output before pasting it, because the effective configuration can include credentials. On large estates list_queues can be slow; run it with a limited column set, as above.

Record who owns the cluster and what breaks when it stops, because that decides how fast anyone has to move.

Record exact versions from the running nodes, not from the install ticket, and compare them with the support matrix.

Record where the nodes sit and which metadata store the cluster uses, because partition behaviour depends on it.

Record anything that differs from the defaults, and say which defaults you rely on.

Record the shape of authentication and certificates, never the secrets themselves.

Record library versions, because they decide behaviour on reconnect, heartbeat and prefetch.

Record the shape of normal traffic, so an abnormal queue is obvious.

Record monitoring, backups and the change window, because these decide how an incident is handled.

Record versions per node, because mixed versions mean an upgrade is in progress or has stalled. Compare the result with the current compatibility matrix: RabbitMQ 4.4.0 runs on Erlang 27.0 to 29.x, 4.3.6 runs on 27.0 to 28.x, and Erlang 26 has reached end of life.

For the metadata store, the answer depends on the series. Khepri became the default store for new clusters in RabbitMQ 4.2.0, an existing cluster upgraded to 4.2 keeps Mnesia until Khepri is explicitly enabled, and from 4.3.0 Mnesia and the partition handling strategies were removed. If the sheet says 4.3 or later, leave the partition handling row empty. If it says 4.2 or earlier on Mnesia, record the cluster_partition_handling value, because it decides what happens to data during a split.

For feature flags, record that the flags were checked and when. Enable all stable flags after every completed upgrade, and treat a flag that cannot be enabled as a finding to record under known issues.

Record where each setting lives, because the same value can be set in three places and the one that wins decides what the node does. The RabbitMQ configuration documentation describes four files and one variable layer:

• rabbitmq.conf is the main configuration file, in a simple key-value format. Record its path and every line that differs from the defaults.
• advanced.config uses Erlang terms for the settings rabbitmq.conf cannot express, and is merged with it. Record whether the file exists and why.
• rabbitmq-env.conf sets environment variables for the node, such as the node name, without the RABBITMQ_ prefix. An environment variable set in the shell overrides the same variable in this file.
• rabbitmq.config is the legacy format from before 3.7.0. It is deprecated but still supported, so an old estate may still carry one; record it and plan its replacement.

Changes to rabbitmq.conf and advanced.config take effect after a node restart, so also record when each node was last restarted, and verify the running values with rabbitmq-diagnostics environment afterwards. For a Docker container, the official image documentation recommends supplying custom configuration as a rabbitmq.conf file mounted at /etc/rabbitmq/rabbitmq.conf, and plugins through a Dockerfile step or a mounted enabled_plugins file. Record the image tag, the path of the mounted configuration file and where the Erlang cookie is supplied, not its value.

A one-sheet that is eighteen months old is worse than none, because people trust it. We recommend a date at the top, a review after every upgrade and every change to topology, and keeping the sheet next to the runbook rather than in a wiki nobody opens.

Create the sheet from this template and keep it where it has a change history, such as version control or a document with tracked edits, so you can see who modified a field and when. Name one owner, limit who can overwrite it, and publish it to everyone on call so they can access it during an incident. After each change, verify the fields against the live nodes, using the RabbitMQ management UI or the commands above to connect to a node and read what it reports, and specify the date you verified them.

Do not write passwords, tokens, the Erlang cookie value or the definitions file into the sheet itself. Record where they are held. If you would rather have an engineer produce the first version with you, ask for it as part of a health check or an onboarding; the scope and terms are agreed in the engagement, not here.