RabbitMQ Cluster Operator: a CRD for running RabbitMQ on Kubernetes

What the operator actually owns

The RabbitMQ Cluster Kubernetes Operator is a Kubernetes operator to deploy and manage RabbitMQ clusters. The repository contains a custom controller and a custom resource definition, and the README says they are designed for the lifecycle of a RabbitMQ cluster, naming creation, upgrade and graceful shutdown.

That last item is the one that distinguishes an operator from a deployment tool. Creating a cluster is the easy half, and it is what a StatefulSet with a stable storage class and a service can do. Upgrading a cluster is the half that needs knowledge of the broker, because a RabbitMQ node has to be stopped, its queue data replicated to its peers, its version changed and its partition leader reassigned in an order that does not lose messages. Graceful shutdown is the same problem in reverse, and doing it wrong means an unclean queue and a message loss.

So the operator's job is to encode the broker's own rules about how nodes may be operated, in a controller that watches a custom resource and acts on what the user wrote in it. The `RabbitmqCluster` resource is the interface, and the operator is the thing that knows the sequence.

The project is written in Go, is licensed under MPL-2.0, the same licence as the RabbitMQ server, with the licence file at the root and a copyright line reading 2007 to 2025 Broadcom. The repository is not archived and the last push was on 2026-10-14, with releases v2.23.1 from 2026-10-13, v2.23.0 from 2026-09-09 and v2.22.5 from 2026-08-24.

Installing it is two kubectl commands

The quickstart assumes you already have a running Kubernetes cluster and a configured `kubectl`, and it is two commands.

The first installs the operator itself:

kubectl apply -f https://github.com/rabbitmq/cluster-operator/releases/latest/download/cluster-operator.yml

And the second deploys a RabbitMQ cluster:

kubectl apply -f https://raw.githubusercontent.com/rabbitmq/cluster-operator/main/docs/examples/hello-world/rabbitmq.yaml

The first URL points at the latest release download, so the operator you install is the newest published one, and the second points at the example in the main branch of the repository.

That split is worth noticing. The operator artefact is versioned and released, while the example manifest comes from the moving branch. So the example you copy is always the current one, which is convenient for a first deployment, and it means the example is not pinned to the operator version you installed. If you are reproducing a specific setup later, you need to take a copy of that manifest rather than fetching it again.

The repository has a `docs/examples` directory with a number of code examples, and the hello-world one is the entry point in the README.

The requirements, and the cert-manager dependency

The compatibility section lists three requirements, and one of them has a version attached to it.

The operator requires Kubernetes 1.31 or later. It requires the RabbitMQ DockerHub image from a supported release series. And for Cluster Operator versions 2.20 and later, cert-manager must be installed in the cluster.

The cert-manager requirement is the interesting one, because it arrived at a specific version and it changes what you have to install before anything else works. cert-manager is what issues and rotates the TLS certificates the broker's nodes use to authenticate to each other and to clients, and the operator's job of doing a rolling upgrade involves rotating those certificates. Requiring cert-manager rather than managing certificates itself is a reasonable division, since the ecosystem already has a project for it, but it is a hard dependency for anyone who was running a simple operator install before 2.20.

The supported versions section then says the operator deploys RabbitMQ 4.3.4 by default, and should work with any supported RabbitMQ version and any supported Kubernetes version. So the default is a specific broker version and the contract is broader than that default, which is the usual shape for an operator.

The Kubernetes 1.31 floor is worth noting for platform teams. It is not a very old release, so an organisation still on 1.29 or 1.30 cannot run the current operator, and the older operator lines that support those versions are the ones to look at.

Non-strict semver, and why the release notes matter

The versioning section is one paragraph and it is the most operationally important thing in the README after the requirements.

RabbitMQ Cluster Kubernetes Operator follows non-strict semver. The versioning guidelines document contains guidelines on how the project implements non-strict semver. The version number may or may not follow the semver rules, and the project highly recommends reading the release notes to understand the changes and their potential impact for any release.

That is a deliberate trade and it deserves a moment's thought. Strict semver says a major version change means breaking changes, which is a promise a Kubernetes operator cannot easily keep, because the operator's behaviour is expressed through a custom resource and through the broker it manages, and a change in either can surface as a behaviour difference without a signature change. A patch release that quietly changes an upgrade strategy is not safe under strict semver, so the project has stepped back from the promise rather than break it.

The consequence for you is concrete. You cannot decide whether to upgrade by looking at the version number, because a patch may carry a change in behaviour. You have to read the release notes, and the project tells you so explicitly.

The release process itself is described in the Releasing section. To release a new version, you create a versioned tag of the repository, and the release pipeline generates a new draft release alongside the release artefacts. So the artefacts in the pipeline and the tag are what you consume, and the notes are where the compatibility information lives.

The dependency list shows what the operator talks to

The `go.mod` is a good map of what a RabbitMQ operator has to touch, and it is a longer list than you might expect.

The Kubernetes side is controller-runtime at v0.25.2 with the api, apimachinery, client-go, klog and utils at v0.37.1, which puts the operator on a current Kubernetes client.

The RabbitMQ side is the interesting part. The `amqp091-go` client at v1.15.0 is the AMQP protocol library, and `rabbitmq-stream-go-client` at v1.8.3 is the stream protocol client. Those two are what let the operator talk to the broker it manages rather than only to the Kubernetes API around it. There is also `michaelklishin/rabbit-hole/v3` at v3.6.0, which is the HTTP client for the RabbitMQ management API, and it is what an operator uses to check the state of a cluster, to see whether the nodes have converged and whether the queues are healthy.

Then there are the protocol clients for the things a broker can be managed through: `eclipse/paho.mqtt.golang` at v1.5.1 and `go-stomp` at v2.1.4. So the operator understands more than AMQP alone, which is a reasonable thing for a component that has to manage a broker through whatever interface the broker offers.

For certificates there is `cloudflare/cfssl` at v1.7.0, a certificate and key generation toolkit, and for configuration parsing `gopkg.in/ini.v1`, which matters for the broker's own configuration format. Testing uses Ginkgo v2.33.1 and Gomega v1.44.0, the same combination Kubernetes controller projects use, and the module declares Go 1.27.2.

The module path itself is `github.com/rabbitmq/cluster-operator/v2`, so the major version is in the path, which is what Go modules require, and it tells you the v2 line is a different import path from the v1 line rather than a drop-in replacement.

The container image, built for a locked-down runtime

The Dockerfile is worth reading because it shows the assumptions the project makes about where it will run.

The build stage uses the official Go image at a `GO_TAG` of 1.27, built for the build platform, and it caches the module download separately from the source copy so that dependency changes and code changes invalidate different layers. The build itself sets `GOOS` and `GOARCH` from the build arguments, disables cgo, and passes a `timetzdata` build tag.

There is a FIPS argument, with `FIPS_MODE=off` by default, exported as `GOFIPS140`. That is the Go toolchain's FIPS mode, and the same pattern appeared in the Open Enclave SDK build, so it is becoming a common thing for projects in regulated-adjacent environments to expose.

The final image is `FROM scratch`, with nothing in it but the manager binary, a passwd and group file, and the CA certificates. The passwd and group entries are written by hand in a small builder stage, with the user and group both at 1000 and a nologin shell, and the runtime switches to that user. The certificate authority bundle is copied in from the Alpine stage, because a `FROM scratch` image has no certificates and the operator needs to reach the Kubernetes API and the container registry over TLS.

That is a deliberately minimal image, and the trade is the usual one: a small attack surface and a small download, at the cost of a shell for debugging and a base image you have to trust for the certificate bundle.

Where the RabbitMQ Cluster Operator is the wrong choice

The first wrong case is a single RabbitMQ instance for a single team. A StatefulSet with a persistent volume claim, a service and a Helm chart gives you a broker that restarts with the pod. The operator's value, which is coordinated multi-node upgrades and orderly shutdown, is worth nothing when there is one node.

The second wrong case is a platform that cannot take a new dependency. From operator version 2.20 onwards cert-manager has to be installed in the cluster, and a platform team with a fixed set of approved cluster components has to go through that before they can install the operator at all.

The third is a team that wants predictable upgrades. Non-strict semver plus the instruction to read the release notes means that upgrading is a decision with reading attached, every time. For a broker that runs in production, that is the right default, but it is a cost.

The fourth is an environment still on Kubernetes 1.29 or 1.30. The operator requires 1.31 or later, and the older operator lines that support those versions are a separate maintenance decision.

The fifth is a deployment on a platform where the operator's assumptions do not hold. The image is `FROM scratch` with a hardcoded numeric user, the operator uses cert-manager for its certificates, and the whole design assumes a general-purpose Kubernetes cluster with the usual admission and scheduling machinery. An OpenShift environment is supported through the OpenShift Lifecycle Manager bundles in the `olm/` directory, and a platform with neither is outside what the project tests.

For a platform team running RabbitMQ as a shared service, though, the operator is the difference between a broker that is upgraded by hand during a maintenance window and one that is upgraded by editing a resource and watching it converge.

Editorial conclusion

RabbitMQ Cluster Operator suits a Kubernetes platform team that runs RabbitMQ for more than one team and wants the broker's lifecycle, upgrades and shutdown ordering handled declaratively rather than by hand. It does not suit a single-application deployment where a StatefulSet and a Helm chart would be less machinery, and it does not suit a team that wants predictable version semantics, because the project follows non-strict semver and says the version number may or may not follow the semver rules. Before deploying it, read the release notes rather than trusting the version number, and plan for cert-manager, which the operator has required since version 2.20.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. Project website
3. rabbitmq/cluster-operator on GitHub
4. README
5. Releases