RabbitMQ

Overview

RabbitMQ is a widely-used open-source message broker that queues, routes and delivers messages between services over AMQP 0-9-1. This template deploys a single-replica broker with the management plugin enabled, backed by a persistent volume so queues, messages and the user database survive a restart. The broker’s default user is not a template value. It comes from a dictionary secret you create before installing, so the credentials your producers and consumers connect with never pass through Helm and never land in the release. The broker is reachable from inside the GVC only; there is no public-access knob.

This template does not create a GVC. It deploys into a GVC you already have — every resource lands in the GVC you install into, so cpln workload exec, cpln logs and uninstalling all work against that GVC, and uninstalling can never delete it.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-rabbitmq`	RabbitMQ broker (stateful, 1 replica) on the official `rabbitmq:3-management` image: AMQP on `5672`, management UI on `15672`, Prometheus metrics on `15692`	—
Volume Set	`RELEASE_NAME-rabbitmq-vs`	Persistent storage at `/var/lib/rabbitmq` holding the message store, queue definitions, the user database and the Erlang cookie	—
Secret	`RELEASE_NAME-rabbitmq-config`	Opaque secret mounted as `/etc/rabbitmq/rabbitmq.conf`; carries only the AMQP listener port	—
Identity	`RELEASE_NAME-rabbitmq-identity`	Identity bound to the workload	—
Policy	`RELEASE_NAME-rabbitmq-policy`	Grants the identity `reveal` on exactly two secrets: the config secret and the credentials secret you created	—

The template creates no credential secret of its own, and the Erlang cookie is never a value either: the broker generates it on first boot onto the volume set.

Template version 1.2.0 is a breaking change for anyone on 1.1.1 or earlier: the default-user values, the firewall block and diskCapacity were removed, and an upgrade that still sets them is refused at render. Read Upgrading From Earlier Versions before you touch an existing release.

Prerequisites

One secret must exist before you install. It holds the RabbitMQ default user — the management-UI login and the AMQP credentials every producer and consumer puts in its connection string. Secrets are org-level, so no GVC flag is involved.

Create the credentials secret

A dictionary secret holding exactly two keys, username and password:

cpln secret create-dictionary --name SECRET_NAME \
  --entry username=rabbitmq \
  --entry password='YOUR-STRONG-PASSWORD'

Set credentialsSecretName to this name. Nothing else is required for a default install.

Read the credentials back when you need them

The -o yaml is required — a bare cpln secret reveal prints only a summary table:

cpln secret reveal SECRET_NAME -o yaml

Create the secret before installing. The template refuses to render when credentialsSecretName is blank, but a name pointing at a secret that does not exist installs “successfully” and then wedges silently: every resource is reported created, the workload never becomes ready, and cpln logs returns zero lines because no container ever starts. The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-rabbitmq --gvc GVC_NAME -o yaml

It is get-deployments — plain cpln workload get has no versions key. Once the secret exists the workload recovers on its own after several minutes, or immediately if you force a redeployment:

cpln workload force-redeployment RELEASE_NAME-rabbitmq --gvc GVC_NAME

Installation

Install with the credentials secret name as the only required value:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/rabbitmq \
  --version 1.2.0 --gvc GVC_NAME \
  --set credentialsSecretName=SECRET_NAME

To install using another method, follow the instructions for it:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Credentials

Names the prerequisite dictionary secret holding the username and password keys (see Prerequisites):

credentialsSecretName: my-rabbitmq-credentials

The default user is written into the RabbitMQ database on first boot only. Changing the secret afterwards does not change a running broker’s credentials — see Rotating the Default User.

Image

The tag is part of the value. 3-management is a floating tag, so a fresh install picks up the current 3.x management-enabled image:

image:
  repository: rabbitmq:3-management

Resources

CPU and memory limits for the broker, and the inbound request timeout applied to the workload:

memory: 250Mi
cpu: 200m

timeoutSeconds: 30 # inbound request timeout in seconds

Internal Access

Which workloads may reach the broker. External inbound is always closed; there is no public-access knob:

internalAccess:
  type: same-gvc # options: none, same-gvc (recommended), same-org

Value	Description
`none`	No workload may connect
`same-gvc`	Allow access from all workloads in the same GVC (recommended)
`same-org`	Allow access from all workloads in the same org

A change to internalAccess.type can take several minutes to take effect. Re-test with a real AMQP client connection — not a bare TCP port check — before concluding the change did not apply.

RabbitMQ Configuration

The AMQP listener port is rendered into /etc/rabbitmq/rabbitmq.conf; it is the only setting that file carries. The credentials are delivered separately, as the RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS environment variables resolved from your secret:

rabbitmq_conf:
  listeners_tcp_default: 5672 # AMQP listener port

env:
  RABBITMQ_CONFIG_FILE: /etc/rabbitmq/rabbitmq.conf

Storage

The persistent volume backing /var/lib/rabbitmq. Snapshots are kept for 7 days and a final snapshot is taken when the volume set is deleted:

volumeset:
  volume:
      initialCapacity: 10 # In Gigabytes. For high-throughput-ssd minimum is '1000'
      fileSystemType: ext4 # ext4 / xfs
      performanceClass: general-purpose-ssd # high-throughput-ssd / general-purpose-ssd

Connecting

The broker is reachable from inside the GVC only. The username and password come from your credentials secret (cpln secret reveal SECRET_NAME -o yaml).

What	Address	Notes
AMQP	`amqp://USERNAME:PASSWORD@RELEASE_NAME-rabbitmq.GVC_NAME.cpln.local:5672/`	Port follows `rabbitmq_conf.listeners_tcp_default`
Management UI and HTTP API	`http://RELEASE_NAME-rabbitmq.GVC_NAME.cpln.local:15672`	Same credentials; the HTTP API lives under `/api/`
Prometheus metrics	`http://RELEASE_NAME-rabbitmq.GVC_NAME.cpln.local:15692/metrics`	No credentials
Public endpoint	Not exposed	External inbound is always closed

To reach the management UI from a browser, or to verify the broker is serving, tunnel to it from your machine:

cpln port-forward RELEASE_NAME-rabbitmq 15672:15672 --gvc GVC_NAME

Then open http://localhost:15672 and log in with the secret’s username and password, or check the HTTP API from another terminal:

curl -u USERNAME:PASSWORD http://localhost:15672/api/overview

A 200 with a JSON body means the broker is up and your credentials are the ones it was bootstrapped with; any other password is rejected with 401.

Operations

Backing Up

RabbitMQ separates definitions (users, vhosts, queues, exchanges, bindings, policies) from messages, and the two are backed up differently. Definitions can be exported from a running broker at any time. rabbitmqctl export_definitions - writes the JSON to standard output, so pipe it straight to a local file:

cpln workload exec RELEASE_NAME-rabbitmq --gvc GVC_NAME --quiet -- rabbitmqctl export_definitions - > definitions.json

The export contains every user’s password hash, so store the file as carefully as the credentials secret itself. Messages cannot be exported from a running node — RabbitMQ requires the node to be stopped before its message store is copied, and the template does not offer a scheduled message backup. The volume set keeps 7 days of snapshots and takes a final snapshot when it is deleted; a snapshot of a running broker captures the disk at that moment, but restoring one into a new release has not been verified for this template.

Restoring a Backup

Definitions are restored by importing the file into a broker. rabbitmqctl import_definitions - reads standard input, so pass the file in with --stdin:

cpln workload exec RELEASE_NAME-rabbitmq --gvc GVC_NAME --stdin -- rabbitmqctl import_definitions - < definitions.json

Importing recreates the topology — users, vhosts, permissions, policies, queues, exchanges and bindings — on the target broker. It does not restore messages, and it does not replace the default user the broker was bootstrapped with. This procedure follows the chart’s configuration and RabbitMQ’s own definitions documentation; it has not been exercised against a live install of this template, so rehearse it on a throwaway release before relying on it.

Rotating the Default User

The default user is created on first boot only, so changing the credentials secret does nothing to a running broker. Rotate the password inside the broker:

cpln workload exec RELEASE_NAME-rabbitmq --gvc GVC_NAME -- rabbitmqctl change_password USERNAME 'NEW-STRONG-PASSWORD'

Then update the dictionary secret to match, so the value your team reads back with cpln secret reveal is the one that works. The broker never re-reads the secret, so updating it alone changes nothing. The alternative is to uninstall and reinstall, which deletes the volume set and every message on it.

Upgrading From Earlier Versions

Template version 1.1.1 and earlier took the RabbitMQ default user as plain Helm values, with a working default username and password published in the public template repository, and wrote them in plaintext into the mounted rabbitmq.conf secret. Version 1.2.0 moves them to the prerequisite secret and cleans up three other values:

	1.1.1 and earlier	1.2.0
Default user	`rabbitmq_conf.default_user` and `rabbitmq_conf.default_pass` values	`credentialsSecretName` → a dictionary secret you create
How it reaches the broker	Written into the mounted `rabbitmq.conf`	`RABBITMQ_DEFAULT_USER` and `RABBITMQ_DEFAULT_PASS` environment variables, resolved from the secret
Internal firewall	`firewall.internal_inboundAllowType`	`internalAccess.type`
Volume size	`diskCapacity` — read by nothing, so setting it had no effect	`volumeset.volume.initialCapacity`
Request timeout	`timeoutSeconds` — read by nothing; the workload used a fixed 5 seconds	`timeoutSeconds`, now applied as set

The firewall block was replaced for clarity only: external inbound was closed before and remains closed. The security fix in this release is the credential move.

Treat a pre-1.2.0 broker’s credentials as compromised, not merely outdated. Upgrading moves them out of Helm values but changes neither the values nor the broker: the default user is written into the RabbitMQ database on first boot only, so an existing broker keeps whatever user it was bootstrapped with. After upgrading, rotate it in place as described in Rotating the Default User, or uninstall and reinstall — which deletes the volume set and every message on it.

Carrying old values forward stops the upgrade. These conditions are rejected at render time, so the upgrade fails and the existing release is left untouched and running:

Value you set	Result
`rabbitmq_conf.default_user`	`was REMOVED in rabbitmq 1.2.0 … create a dictionary secret holding the keys username and password, and set credentialsSecretName to its name`
`rabbitmq_conf.default_pass`	the same message
`credentialsSecretName` empty	`credentialsSecretName is required — it names the dictionary secret holding the username and password keys`
any `firewall.*` key	`The firewall block was REPLACED in rabbitmq 1.2.0 by internalAccess. Set internalAccess.type to none, same-gvc or same-org`
`diskCapacity`	`was REMOVED in rabbitmq 1.2.0 — it was never read by any template and setting it had no effect on disk size. Use volumeset.volume.initialCapacity instead`
`internalAccess.type` unset	`internalAccess.type is required — set it to none, same-gvc or same-org`
`internalAccess.type` not one of the three	`internalAccess.type must be one of: none, same-gvc, same-org`

To upgrade, create the credentials secret first (Prerequisites), then run the upgrade with credentialsSecretName set and the removed keys dropped from your values. The volume set — and with it every queue, message and user — is kept across the upgrade.

Scaling and Availability

This template runs one broker node with one replica; there is no clustering or replicas knob. Any upgrade or reschedule restarts the broker — including the first upgrade after an install, even when no value changed — so every connected client sees a short outage. Give your producers and consumers a reconnect policy. Queues, messages and the user database live on the volume set and survive a restart; uninstalling the release deletes them.

Troubleshooting

Workload never becomes ready and cpln logs returns nothing

Symptom: the install reports every resource created, the workload stays not ready, and cpln logs prints zero lines.Cause: the credentials secret named by credentialsSecretName does not exist, so the container never starts.Fix: read the deployment message — it is the only place the missing secret is named:

cpln workload get-deployments RELEASE_NAME-rabbitmq --gvc GVC_NAME -o yaml

Look for

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

under status.versions[].message. Create the secret with that exact name (Prerequisites); the workload recovers on its own after several minutes, or force a redeployment to skip the wait.

I changed the secret but the old password still works

Symptom: the credentials secret was updated (or the release was redeployed with a new secret), yet the broker still accepts the old username and password and rejects the new ones with 401.Cause: RabbitMQ writes the default user into its database on first boot only; the user database lives on the volume set and is never overwritten from the secret.Fix: rotate inside the broker with rabbitmqctl change_password (Rotating the Default User), or uninstall and reinstall to start from an empty volume set.

Upgrade fails at render with 'was REMOVED in rabbitmq 1.2.0'

Symptom: cpln helm upgrade exits before touching any resource, printing one of the messages in Upgrading From Earlier Versions.Cause: your values still carry a key from 1.1.1 or earlier — rabbitmq_conf.default_user, rabbitmq_conf.default_pass, any firewall.* key or diskCapacity — or credentialsSecretName / internalAccess.type is missing.Fix: remove the old keys, create the credentials secret, set credentialsSecretName and internalAccess.type, and run the upgrade again. The running release is unaffected until the render succeeds.

Clients in the GVC cannot connect

Symptom: a producer or consumer in the same GVC fails to open an AMQP connection, or a workload in another GVC of the same org is refused.Cause: internalAccess.type is none, or it is same-gvc while the client runs in a different GVC; a recent change to the value may also still be taking effect.Fix: set internalAccess.type to same-gvc or same-org as needed, wait several minutes, and test with a real AMQP client rather than a bare TCP port check. Confirm the client uses the fully qualified host RELEASE_NAME-rabbitmq.GVC_NAME.cpln.local and the port in rabbitmq_conf.listeners_tcp_default.

Symptom: http://localhost:15672 over a port-forward loads, but the login is refused, or the HTTP API returns 401.Cause: the username and password are not the ones the broker was bootstrapped with. The management UI uses the same default user as AMQP.Fix: read the values back with cpln secret reveal SECRET_NAME -o yaml. If the secret was changed after the first boot, the broker still holds the original credentials — see the previous entry.

Important Notes

Create the credentials secret before you install; without it the workload wedges with no log output, and only status.versions[].message names the missing secret.
The default user is written on first boot only — rotate with rabbitmqctl change_password, not by editing the secret.
The broker is GVC-internal only. Use cpln port-forward for the management UI; there is no public endpoint.
Single node, single replica: every upgrade or reschedule is a short outage, so give clients a reconnect policy.
Definitions can be exported at any time; messages cannot be backed up from a running node, and uninstalling the release deletes the volume set and every message on it.
On 1.1.1 or earlier, treat the broker’s credentials as compromised and rotate them after upgrading to 1.2.0.

External References

RabbitMQ Documentation

Official RabbitMQ documentation

Configuration Reference

How rabbitmq.conf and the environment variables are read

Management Plugin

The management UI and HTTP API

Definitions Export and Import

Backing up and restoring users, vhosts, queues, exchanges and bindings

RabbitMQ Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Credentials

Image

Resources

Internal Access

RabbitMQ Configuration

Storage

Connecting

Operations

Backing Up

Restoring a Backup

Rotating the Default User

Upgrading From Earlier Versions

Scaling and Availability

Troubleshooting

Important Notes

External References

RabbitMQ Documentation

Configuration Reference

Management Plugin

Definitions Export and Import

RabbitMQ Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Credentials

​Image

​Resources

​Internal Access

​RabbitMQ Configuration

​Storage

​Connecting

​Operations

​Backing Up

​Restoring a Backup

​Rotating the Default User

​Upgrading From Earlier Versions

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

RabbitMQ Documentation

Configuration Reference

Management Plugin

Definitions Export and Import

RabbitMQ Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Credentials

Image

Resources

Internal Access

RabbitMQ Configuration

Storage

Connecting

Operations

Backing Up

Restoring a Backup

Rotating the Default User

Upgrading From Earlier Versions

Scaling and Availability

Troubleshooting

Important Notes

External References