RabbitMQ

Production-ready RabbitMQ message broker for Kubernetes. Supports single-node and multi-node cluster architectures, quorum queues (default), management UI with dedicated Ingress, Prometheus metrics, and TLS listeners.

Fix the Erlang cookie before scaling to a cluster

The Erlang cookie (auth.erlangCookie) is used for node-to-node authentication. If it changes between deployments, cluster nodes will refuse to connect to each other. Set an explicit value in auth.erlangCookie or use auth.existingSecret — never rely on auto-generation in cluster mode.

Key Features

Official Alpine image — default docker.io/library/rabbitmq:4.3.1-alpine with chart-managed plugins
Two architectures — single-node (one StatefulSet replica) or cluster (StatefulSet with peer discovery)
Quorum queues by default — queueDefaults.type: quorum for durable, replicated HA queues
Dedicated management ingress — management.ingress is separate from the AMQP service
Gateway API support — optional HTTPRoute for the management UI
External Secrets Operator — source username, password, and Erlang cookie from an external provider
Dual-stack Services — optional Service ipFamilyPolicy and ipFamilies controls
Partition handling — pause_minority strategy prevents split-brain in cluster mode
PDB support — optional PodDisruptionBudget to protect cluster quorum during node maintenance
TLS listeners — configurable AMQP/S and management TLS from an existing Secret
Prometheus metrics — built-in metrics plugin with optional ServiceMonitor
Low idle CPU defaults — disables Erlang scheduler busy-wait and uses lightweight TCP probes

Port Reference

Port	Protocol	Description
5672	TCP	AMQP (client connections)
5671	TCP	AMQPS (AMQP over TLS)
15672	HTTP	Management UI
15671	HTTPS	Management UI over TLS
15692	HTTP	Prometheus metrics endpoint
4369	TCP	EPMD (Erlang port mapper daemon)
25672	TCP	Erlang distribution (cluster traffic)

Runtime Efficiency

The chart defaults to the official Alpine RabbitMQ image and controls enabled plugins through the rendered enabled_plugins file. The base Alpine image already contains the management, Prometheus, and Kubernetes peer-discovery plugins, so management.enabled, metrics.enabled, architecture: cluster, and plugins.extra decide what is active without switching image variants.

By default, runtime.disableSchedulerBusyWait: true renders:

RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS: +sbwt none +sbwtdcpu none +sbwtdio none

This lowers idle CPU in containerized RabbitMQ deployments. Startup, liveness, and readiness probes use TCP checks against the active AMQP listener instead of repeatedly starting rabbitmq-diagnostics.

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install rabbitmq helmforge/rabbitmq -f values.yaml

OCI registry:

helm install rabbitmq oci://ghcr.io/helmforgedev/helm/rabbitmq -f values.yaml

Deployment Examples

# values.yaml — RabbitMQ single-node with management UI and persistence
architecture: single-node

auth:
  username: admin
  existingSecret: rabbitmq-credentials
  existingSecretPasswordKey: rabbitmq-password

queueDefaults:
  type: quorum # modern default — use classic only for legacy compatibility

singleNode:
  persistence:
    enabled: true
    size: 10Gi

management:
  enabled: true
  ingress:
    enabled: true
    ingressClassName: traefik
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
      - host: rabbitmq.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: rabbitmq-tls
        hosts:
          - rabbitmq.example.com

resources:
  requests:
    memory: 256Mi
    cpu: 100m
  limits:
    memory: 1Gi
    cpu: 500m

# values.yaml — 3-node RabbitMQ cluster with fixed Erlang cookie and PDB
architecture: cluster

auth:
  username: admin
  existingSecret: rabbitmq-credentials # must contain password AND erlang cookie
  existingSecretPasswordKey: rabbitmq-password
  existingSecretErlangCookieKey: rabbitmq-erlang-cookie

queueDefaults:
  type: quorum

cluster:
  replicaCount: 3
  partitionHandling: pause_minority
  gracefulShutdown:
    enabled: true
  persistence:
    enabled: true
    size: 10Gi

pdb:
  enabled: true
  minAvailable: 2 # always maintain quorum (majority of 3)

management:
  enabled: true
  ingress:
    enabled: true
    ingressClassName: traefik
    hosts:
      - host: rabbitmq.example.com
        paths:
          - path: /
            pathType: Prefix

resources:
  requests:
    memory: 512Mi
    cpu: 250m
  limits:
    memory: 2Gi
    cpu: '1'

# values.yaml — RabbitMQ with TLS for AMQP and management UI
architecture: single-node

auth:
  username: admin
  existingSecret: rabbitmq-credentials

tls:
  enabled: true
  existingSecret: rabbitmq-tls-secret # must contain ca.crt, tls.crt, tls.key
  caFilename: ca.crt
  certFilename: tls.crt
  keyFilename: tls.key
  verify: verify_peer
  failIfNoPeerCert: false

management:
  enabled: true
  ingress:
    enabled: true
    ingressClassName: traefik
    useTlsPort: true # route ingress to management HTTPS port (15671)
    hosts:
      - host: rabbitmq.example.com
        paths:
          - path: /
            pathType: Prefix

singleNode:
  persistence:
    enabled: true
    size: 10Gi

# values.yaml — RabbitMQ with Prometheus metrics and ServiceMonitor
architecture: single-node

auth:
  username: admin
  existingSecret: rabbitmq-credentials

singleNode:
  persistence:
    enabled: true
    size: 10Gi

metrics:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s
    labels:
      release: prometheus # match your Prometheus Operator selector label

management:
  enabled: true

# values.yaml — RabbitMQ credentials managed by External Secrets Operator
auth:
  username: admin
  existingSecret: rabbitmq-credentials
  existingSecretUsernameKey: rabbitmq-username
  existingSecretPasswordKey: rabbitmq-password
  existingSecretErlangCookieKey: rabbitmq-erlang-cookie

externalSecrets:
  enabled: true
  apiVersion: external-secrets.io/v1
  refreshInterval: '0'
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  data:
    - secretKey: rabbitmq-username
      remoteRef:
        key: rabbitmq/admin
        property: username
    - secretKey: rabbitmq-password
      remoteRef:
        key: rabbitmq/admin
        property: password
    - secretKey: rabbitmq-erlang-cookie
      remoteRef:
        key: rabbitmq/cluster
        property: erlangCookie

# values.yaml — expose the RabbitMQ management UI through Gateway API
management:
  enabled: true
  gateway:
    enabled: true
    hostnames:
      - rabbitmq.example.com
    parentRefs:
      - name: public-gateway
        namespace: gateway-system

Configuration Reference

Core

Parameter	Type	Default	Description
`architecture`	string	`single-node`	Deployment mode: `single-node` (Deployment) or `cluster` (StatefulSet).
`nameOverride`	string	`""`	Override the chart name.
`fullnameOverride`	string	`""`	Override the full release name.
`commonLabels`	object	`{}`	Extra labels added to all resources.
`clusterDomain`	string	`cluster.local`	Kubernetes cluster domain.

Image

Parameter	Type	Default	Description
`image.repository`	string	`docker.io/library/rabbitmq`	Official RabbitMQ image repository.
`image.tag`	string	`"4.3.1-alpine"`	Official Alpine RabbitMQ image tag.
`image.pullPolicy`	string	`IfNotPresent`	Image pull policy.
`imagePullSecrets`	array	`[]`	Pull secrets for private registries.

Authentication

Parameter	Type	Default	Description
`auth.username`	string	`user`	RabbitMQ admin username.
`auth.password`	string	`""`	Admin password. Auto-generated if empty.
`auth.erlangCookie`	string	`""`	Erlang cookie for node-to-node auth. Auto-generated if empty.
`auth.vhost`	string	`/`	Default virtual host created by RabbitMQ.
`auth.existingSecret`	string	`""`	Existing secret with username, password, and Erlang cookie.
`auth.existingSecretUsernameKey`	string	`rabbitmq-username`	Key for username in `existingSecret`.
`auth.existingSecretPasswordKey`	string	`rabbitmq-password`	Key for password in `existingSecret`.
`auth.existingSecretErlangCookieKey`	string	`rabbitmq-erlang-cookie`	Key for Erlang cookie in `existingSecret`.

Queue Defaults

Parameter	Type	Default	Description
`queueDefaults.type`	string	`quorum`	Default queue type: `quorum` (HA, replicated) or `classic` (legacy, non-HA).

Quorum queues are the modern default

Quorum queues use the Raft consensus algorithm for durable, replicated message storage. They replace classic mirrored queues and are the recommended choice for new deployments. Classic queues are still supported for compatibility with legacy applications but are not HA.

Single-Node Mode

Parameter	Type	Default	Description
`singleNode.persistence.enabled`	boolean	`true`	Enable PVC for message storage.
`singleNode.persistence.size`	string	`8Gi`	PVC size.
`singleNode.persistence.storageClass`	string	`""`	StorageClass for the PVC.
`singleNode.persistence.accessMode`	string	`ReadWriteOnce`	PVC access mode.

Cluster Mode

Set a fixed Erlang cookie before creating a cluster

Never use auto-generated Erlang cookies in cluster mode. If a pod is replaced and the cookie changes, the new node will be rejected by the existing cluster members. Store the cookie in a Kubernetes Secret and reference it via auth.existingSecret.

Parameter	Type	Default	Description
`cluster.replicaCount`	integer	`3`	Number of RabbitMQ cluster nodes.
`cluster.podManagementPolicy`	string	`OrderedReady`	StatefulSet pod management policy.
`cluster.partitionHandling`	string	`pause_minority`	Network partition strategy. `pause_minority` prevents split-brain.
`cluster.ordinalStart`	integer	`0`	Starting ordinal for peer discovery.
`cluster.seedNode`	string	`""`	Explicit seed node hostname for cluster formation.
`cluster.gracefulShutdown.enabled`	boolean	`true`	Execute graceful shutdown before pod termination.
`cluster.persistence.enabled`	boolean	`true`	Enable PVCs for each cluster node.
`cluster.persistence.size`	string	`8Gi`	PVC size per node.
`cluster.persistence.storageClass`	string	`""`	StorageClass for cluster PVCs.

Management UI

Parameter	Type	Default	Description
`management.enabled`	boolean	`true`	Enable the management plugin and UI (port 15672/15671).
`management.ingress.enabled`	boolean	`false`	Enable Ingress for the management UI.
`management.ingress.ingressClassName`	string	`traefik`	Ingress class for the management UI.
`management.ingress.annotations`	object	`{}`	Annotations for the management Ingress.
`management.ingress.hosts`	array	`[]`	Ingress host and path rules.
`management.ingress.tls`	array	`[]`	TLS configuration for the management Ingress.
`management.ingress.useTlsPort`	boolean	`false`	Route ingress to the TLS management port (15671).

TLS

Parameter	Type	Default	Description
`tls.enabled`	boolean	`false`	Enable TLS listeners for AMQP and management.
`tls.existingSecret`	string	`""`	Existing secret with CA, certificate, and private key.
`tls.caFilename`	string	`ca.crt`	CA certificate filename inside the secret.
`tls.certFilename`	string	`tls.crt`	Certificate filename inside the secret.
`tls.keyFilename`	string	`tls.key`	Private key filename inside the secret.
`tls.verify`	string	`verify_none`	TLS peer verification mode.
`tls.failIfNoPeerCert`	boolean	`false`	Reject connections without a valid peer certificate.
`tls.disableNonTLSListeners`	boolean	`false`	Disable plaintext AMQP listeners when TLS is enabled.

Plugins

Parameter	Type	Default	Description
`plugins.extra`	array	`[]`	Additional RabbitMQ plugins to enable beyond chart defaults.

Custom Configuration

Parameter	Type	Default	Description
`config.extra`	string	`""`	Extra `rabbitmq.conf` entries appended to the generated config.
`config.advancedConfig`	string	`""`	Raw `advanced.config` Erlang term content.

Runtime

Parameter	Type	Default	Description
`runtime.disableSchedulerBusyWait`	boolean	`true`	Add Erlang VM flags that reduce scheduler busy-wait idle CPU.
`runtime.additionalErlArgs`	string	`""`	Additional Erlang VM arguments appended to chart-managed defaults.

Probes

Parameter	Type	Default	Description
`startupProbe.enabled`	boolean	`true`	Enable TCP startup probe.
`startupProbe.initialDelaySeconds`	integer	`10`	Startup probe initial delay.
`startupProbe.timeoutSeconds`	integer	`3`	Startup probe timeout.
`startupProbe.periodSeconds`	integer	`10`	Startup probe period.
`startupProbe.failureThreshold`	integer	`30`	Startup probe failure threshold.
`livenessProbe.enabled`	boolean	`true`	Enable TCP liveness probe.
`livenessProbe.initialDelaySeconds`	integer	`30`	Liveness probe initial delay.
`livenessProbe.timeoutSeconds`	integer	`3`	Liveness probe timeout.
`livenessProbe.periodSeconds`	integer	`30`	Liveness probe period.
`livenessProbe.failureThreshold`	integer	`6`	Liveness probe failure threshold.
`readinessProbe.enabled`	boolean	`true`	Enable TCP readiness probe.
`readinessProbe.initialDelaySeconds`	integer	`20`	Readiness probe initial delay.
`readinessProbe.timeoutSeconds`	integer	`3`	Readiness probe timeout.
`readinessProbe.periodSeconds`	integer	`10`	Readiness probe period.
`readinessProbe.failureThreshold`	integer	`6`	Readiness probe failure threshold.

PodDisruptionBudget

Parameter	Type	Default	Description
`pdb.enabled`	boolean	`false`	Create a PodDisruptionBudget.
`pdb.minAvailable`	integer	`1`	Minimum available pods during disruptions. Set to `2` for 3-node HA.
`pdb.maxUnavailable`	string	`""`	Maximum unavailable pods (alternative to `minAvailable`).

Metrics

Parameter	Type	Default	Description
`metrics.enabled`	boolean	`false`	Enable the Prometheus metrics plugin (port 15692).
`metrics.serviceMonitor.enabled`	boolean	`false`	Create a Prometheus Operator ServiceMonitor.
`metrics.serviceMonitor.interval`	string	`30s`	Metrics scrape interval.
`metrics.serviceMonitor.labels`	object	`{}`	Extra labels for the ServiceMonitor.

Service

Parameter	Type	Default	Description
`service.type`	string	`ClusterIP`	Service type.
`service.amqpPort`	integer	`5672`	AMQP listener port.
`service.amqpsPort`	integer	`5671`	AMQPS listener port (TLS).
`service.managementPort`	integer	`15672`	Management UI HTTP port.
`service.managementTlsPort`	integer	`15671`	Management UI HTTPS port.
`service.epmdPort`	integer	`4369`	Erlang port mapper daemon port.
`service.distPort`	integer	`25672`	Erlang distribution port (cluster inter-node traffic).
`service.metricsPort`	integer	`15692`	Prometheus metrics port.
`service.annotations`	object	`{}`	Annotations for the Service.
`service.extraPorts`	array	`[]`	Extra ports added to the Service.
`service.ipFamilyPolicy`	string	`""`	Service IP family policy. Empty uses the cluster default.
`service.ipFamilies`	array	`[]`	Ordered Service IP families such as `IPv4` and `IPv6`.

Gateway API

The chart can expose the management UI with Gateway API by rendering an HTTPRoute that targets the management Service port. Use this when your cluster standardizes north-south HTTP traffic through Gateway API.

Parameter	Type	Default	Description
`management.gateway.enabled`	boolean	`false`	Render a Gateway API HTTPRoute for management UI.
`management.gateway.hostnames`	array	`[]`	HTTPRoute hostnames. Empty matches all hostnames.
`management.gateway.parentRefs`	array	`[]`	Parent Gateway references used by the HTTPRoute.

External Secrets Operator

Use External Secrets for RabbitMQ credentials when passwords and Erlang cookies are owned by a secret manager.

Parameter	Type	Default	Description
`externalSecrets.enabled`	boolean	`false`	Render an ExternalSecret for RabbitMQ credentials.
`externalSecrets.apiVersion`	string	`external-secrets.io/v1`	ExternalSecret API version.
`externalSecrets.refreshInterval`	string	`"0"`	Refresh interval. `"0"` syncs once.
`externalSecrets.secretStoreRef`	object	`{}`	SecretStore or ClusterSecretStore reference.
`externalSecrets.target.creationPolicy`	string	`Owner`	Target Secret creation policy.
`externalSecrets.data`	array	`[]`	Mappings for username, password, and Erlang cookie keys.

Resources and Security

Parameter	Type	Default	Description
`resources`	object	`{}`	CPU and memory requests and limits.
`podSecurityContext`	object	`{}`	Pod-level security context.
`securityContext`	object	`{}`	Container-level security context.

Scheduling

Parameter	Type	Default	Description
`nodeSelector`	object	`{}`	Node selector for scheduling.
`tolerations`	array	`[]`	Tolerations for scheduling.
`affinity`	object	`{}`	Affinity rules.
`topologySpreadConstraints`	array	`[]`	Topology spread constraints.
`priorityClassName`	string	`""`	PriorityClass for the pod.
`terminationGracePeriodSeconds`	integer	`120`	Grace period. Allows in-progress message deliveries to complete.
`podLabels`	object	`{}`	Extra labels for the pod.
`podAnnotations`	object	`{}`	Extra annotations for the pod.

Extra

Parameter	Type	Default	Description
`extraEnv`	array	`[]`	Extra environment variables for the container.
`extraVolumes`	array	`[]`	Extra volumes to attach to the pod.
`extraVolumeMounts`	array	`[]`	Extra volume mounts for the container.
`extraManifests`	array	`[]`	Extra Kubernetes manifests deployed alongside the chart.