Skip to content

rabbitmq

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

rabbitmq

README.md

RabbitMQ

A Helm chart for RabbitMQ - A messaging broker that implements the Advanced Message Queuing Protocol (AMQP). RabbitMQ is a reliable, feature-rich message broker that supports multiple messaging patterns and is widely used for building distributed systems, microservices communication, and event-driven architectures.

Prerequisites

  • Kubernetes 1.24+
  • Helm 3.2.0+
  • PV provisioner support in the underlying infrastructure (if persistence is enabled)

Installing the Chart

To install the chart with the release name my-rabbitmq:

$ helm install my-rabbitmq oci://registry-1.docker.io/cloudpirates/rabbitmq

Or install directly from the local chart:

$ helm install my-rabbitmq ./charts/rabbitmq

The command deploys RabbitMQ on the Kubernetes cluster in the default configuration. The Configuration section lists the parameters that can be configured during installation.

Upgrading the Chart

For HA setups the erlang-cookie is used to join nodes to the cluster. If no erlang-cookie is set, a random one is generated with each chart update and restarted pods wont be able to rejoin the cluster with the new erlang-cookie.

For existing installations this can be fixed after an update by getting the current erlang-cookie from the ENV-Vars, inside the still running old pods and replacing the newly generated erlang-cookie in the k8s secret with the old one.

Uninstalling the Chart

To uninstall/delete the my-rabbitmq deployment:

$ helm uninstall my-rabbitmq

The command removes all the Kubernetes components associated with the chart and deletes the release.

Important: By default, PersistentVolumeClaims (PVCs) are NOT deleted when you uninstall the chart. This is intentional to prevent accidental data loss. If you reinstall the chart with different passwords or Erlang cookies, you may encounter authentication issues because the old data persists.

Cleaning up PersistentVolumeClaims

To manually delete the PVCs after uninstalling:

$ kubectl delete pvc -l app.kubernetes.io/instance=my-rabbitmq

Alternatively, you can enable automatic PVC deletion by configuring the persistentVolumeClaimRetentionPolicy before installation:

persistentVolumeClaimRetentionPolicy:
  enabled: true
  whenDeleted: Delete  # Automatically delete PVCs when StatefulSet is deleted
  whenScaled: Delete   # Automatically delete PVCs when scaling down

See the Persistent Volume Claim Retention Policy section for more details.

Security & Signature Verification

This Helm chart is cryptographically signed with Cosign to ensure authenticity and prevent tampering.

Public Key:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5U+rM2d3hDjgP5T3cLShuuQIU9vR
Z4/G+Nug6q5vRa+C3qUA1wXjbaJFAfcIrv5VjmYAYOj13shnPpp3Zh4fnQ==
-----END PUBLIC KEY-----

To verify the helm chart before installation, copy the public key to the file cosign.pub and run cosign:

cosign verify --key cosign.pub registry-1.docker.io/cloudpirates/rabbitmq:<version>

Configuration

The following table lists the configurable parameters of the RabbitMQ chart and their default values.

Global parameters

Parameter Description Default
global.imageRegistry Global Docker image registry ""
global.imagePullSecrets Global Docker registry secret names as an array []

Common parameters

Parameter Description Default
nameOverride String to partially override rabbitmq.fullname ""
fullnameOverride String to fully override rabbitmq.fullname ""
namespaceOverride String to override the namespace for all resources ""
commonLabels Labels to add to all deployed objects {}
commonAnnotations Annotations to add to all deployed objects {}
clusterDomain Kubernetes cluster domain cluster.local

RabbitMQ image parameters

Parameter Description Default
image.registry RabbitMQ image registry docker.io
image.repository RabbitMQ image repository rabbitmq
image.tag RabbitMQ image tag "4.2.0-management@sha256:23676732c0b7bb978c0837c150492222d5b23ff079fc2025b537f4ce5c013d98"
image.imagePullPolicy RabbitMQ image pull policy Always

Deployment configuration

Parameter Description Default
replicaCount Number of RabbitMQ replicas to deploy (clustering needs to be enabled to set more than 1 replicas) 1
revisionHistoryLimit Number of revisions to keep in history for rollback (set to 0 for unlimited) 10
podManagementPolicy StatefulSet pod management policy OrderedReady

StatefulSet & Pod metadata

Parameter Description Default
statefulsetLabels Labels to attach to StatefulSet {}
podLabels Labels to attach to pods {}
podAnnotations Annotations to attach to pods {}
statefulsetAnnotations Annotations for StatefulSet {}

RabbitMQ Definitions

Parameter Description Default
definitions.enabled Enable loading of RabbitMQ definitions on startup. When true, definitions will be loaded at container boot. false
definitions.existingConfigMap Name of an existing ConfigMap containing RabbitMQ definitions (e.g., created via kubectl create configmap rmq-defs --from-file=defs.json). ""
definitions.existingConfigMapKey Key in the existing ConfigMap containing the RabbitMQ definitions JSON file. defs.json
defintions.existingSecret Name of an existing Secret containing RabbitMQ definitions. ""
definitions.existingSecretKey Key in the existing Secret containing the RabbitMQ definitions JSON file. defs.json
definitions.users Array of RabbitMQ users to create. []
definitions.vhosts Array of RabbitMQ virtual hosts to create. []
definitions.permissions Array of RabbitMQ permissions to set per vhost. []
definitions.queues Array of RabbitMQ queues to create. []
definitions.exchanges Array of RabbitMQ exchanges to create. []
definitions.bindings Array of RabbitMQ bindings to create. []
definitions.parameters Array of RabbitMQ parameters to create. []
definitions.global_parameters Array of RabbitMQ global parameters to create. []
definitions.topic_permissions Array of RabbitMQ topic permissions to create. []
definitions.policies Array of RabbitMQ policies to create. []

Automatic Configuration Reloading

The chart supports automatic reloading of definitions when the ConfigMap or Secret changes, without requiring a pod restart or Helm upgrade.

Parameter Description Default
definitions.autoReload.enabled Enable sidecar container to watch for ConfigMap/Secret changes false
definitions.autoReload.image.registry Container image registry for the config watcher sidecar docker.io
definitions.autoReload.image.repository Container image repository for the config watcher sidecar curlimages/curl
definitions.autoReload.image.tag Container image tag for the config watcher sidecar 8.11.1
definitions.autoReload.image.pullPolicy Container image pull policy for the config watcher sidecar IfNotPresent
definitions.autoReload.resources Resource limits and requests for the config watcher sidecar See values.yaml

How it works:

When enabled, a lightweight sidecar container runs alongside RabbitMQ and:

  1. Monitors the definitions file for changes (using checksum comparison)
  2. Automatically reloads definitions via RabbitMQ Management API when changes are detected
  3. Checks for changes every 10 seconds

Example:

definitions:
  enabled: true
  existingConfigMap: my-rabbitmq-definitions
  autoReload:
    enabled: true

After deployment, you can update your ConfigMap:

kubectl edit configmap my-rabbitmq-definitions -n <namespace>
# The sidecar will automatically detect and reload the new configuration

Service configuration

Parameter Description Default
service.type Kubernetes service type ClusterIP
service.amqpPort RabbitMQ AMQP service port 5672
service.managementPort RabbitMQ management UI port 15672
service.epmdPort RabbitMQ EPMD port 4369
service.distPort RabbitMQ distribution port 25672
service.annotations Kubernetes service annotations {}
service.annotationsHeadless Kubernetes service annotationsHeadless 25672
service.trafficDistribution Traffic distribution policy for the service ""
service.externalTrafficPolicy External Traffic Policy for the service Cluster
service.allocateLoadBalancerNodePorts Whether to allocate NodePorts for service type LoadBalancer true

RabbitMQ Authentication

Parameter Description Default
auth.enabled Enable RabbitMQ authentication true
auth.username RabbitMQ default username admin
auth.password RabbitMQ password (if empty, random password will be generated) ""
auth.erlangCookie Erlang cookie for clustering (if empty, random cookie will be generated) ""
auth.existingSecret Name of existing secret containing RabbitMQ credentials ""
auth.existingPasswordKey Key in existing secret containing RabbitMQ password "password"
auth.existingErlangCookieKey Key in existing secret containing Erlang cookie "erlang-cookie"

RabbitMQ configuration

Parameter Description Default
config.memoryHighWatermark.enabled Enable configuring Memory high watermark on RabbitMQ false
config.memoryHighWatermark.type Memory high watermark type. Either absolute or relative "relative"
config.memoryHighWatermark.value Memory high watermark value. For relative: use number (e.g., 0.4 for 40%). For absolute: use string to avoid scientific notation (e.g., "8GB", "8590000000") 0.4
config.extraConfiguration Additional RabbitMQ configuration ""
config.advancedConfiguration Advanced RabbitMQ configuration ""

PeerDiscoveryK8sPlugin configuration

Parameter Description Default
peerDiscoveryK8sPlugin.enabled Enable K8s peer discovery plugin for a RabbitMQ HA-cluster false
peerDiscoveryK8sPlugin.useLongname Uses the FQDN as connection string (RABBITMQ_USE_LONGNAME) true
peerDiscoveryK8sPlugin.addressType Peer discovery plugin address type hostname

ManagementPlugin configuration

Parameter Description Default
managementPlugin.enabled Enable RabbitMQ management plugin true

Init Container configuration

Parameter Description Default
initContainer.image.registry Init container image registry docker.io
initContainer.image.repository Init container image repository busybox
initContainer.image.tag Init container image tag "1.37.0@sha256:b3255e7dfbcd10cb367af0d409747d511aeb66dfac98cf30e97e87e4207dd76f"
initContainer.image.pullPolicy Init container image pull policy IfNotPresent
initContainer.resources Resource limits and requests for init containers {}

Plugin configuration

Parameter Description Default
installPlugins Additional 3rd party RabbitMQ plugins to download and enable []

Metrics configuration

Parameter Description Default
metrics.enabled Enable RabbitMQ metrics (via prometheus plugin) false
metrics.port RabbitMQ metrics port 15692
metrics.serviceMonitor.enabled Create ServiceMonitor for Prometheus monitoring false
metrics.serviceMonitor.namespace Namespace for ServiceMonitor ""
metrics.serviceMonitor.labels Labels for ServiceMonitor {}
metrics.serviceMonitor.annotations Annotations for ServiceMonitor {}
metrics.serviceMonitor.interval Scrape interval 30s
metrics.serviceMonitor.scrapeTimeout Scrape timeout 10s
metrics.serviceMonitor.path Select detail of metrics (/metrics, /metrics/detailed or /metrics/per-object) /metrics
metrics.serviceMonitor.namespaceSelector Namespace selector for ServiceMonitor {}
additionalPlugins Additional RabbitMQ plugins to enable (Prometheus Metrics, PeerDiscoveryK8s and Management plugins are automatically added) []

Persistence

Parameter Description Default
persistence.enabled Enable persistent storage true
persistence.existingClaim Name of existing PVC to use (if empty, a new PVC will be created automatically) ""
persistence.storageClass Storage class to use for persistent volume ""
persistence.mountPath Set the mountPath for the data Volume /var/lib/rabbitmq
persistence.accessModes Persistent Volume access modes ["ReadWriteOnce"]
persistence.size Size of persistent volume 8Gi
persistence.labels Labels for persistent volume claims {}
persistence.annotations Annotations for persistent volume claims {}

Ingress configuration

Parameter Description Default
ingress.enabled Enable ingress for RabbitMQ management false
ingress.className Ingress class name ""
ingress.annotations Ingress annotations {}
ingress.hosts Ingress hosts configuration [{"host": "rabbitmq.local", "paths": [{"path": "/", "pathType": "Prefix"}]}]
ingress.tls Ingress TLS configuration []

Resources

Parameter Description Default
resources Resource limits and requests for RabbitMQ pods {}

Node Selection

Parameter Description Default
nodeSelector Node labels for pod assignment {}
tolerations Toleration labels for pod assignment []
affinity Affinity settings for pod assignment {}
topologySpreadConstraints Topology spread constraints for pod assignment []

Security Context

Parameter Description Default
podSecurityContext.fsGroup Group ID for the volumes of the pod 999
podSecurityContext.seccompProfile Seccomp profile for the pod {type: RuntimeDefault}
containerSecurityContext.allowPrivilegeEscalation Enable container privilege escalation false
containerSecurityContext.runAsNonRoot Configure the container to run as a non-root user true
containerSecurityContext.runAsUser User ID for the RabbitMQ container 999
containerSecurityContext.runAsGroup Group ID for the RabbitMQ container 999
containerSecurityContext.readOnlyRootFilesystem Mount container root filesystem as read-only true
containerSecurityContext.capabilities.drop Linux capabilities to be dropped ["ALL"]
priorityClassName Priority class for the rabbitmq instance ""

Liveness and readiness probes

Parameter Description Default
livenessProbe.enabled Enable livenessProbe on RabbitMQ containers true
livenessProbe.initialDelaySeconds Initial delay seconds for livenessProbe 120
livenessProbe.periodSeconds Period seconds for livenessProbe 30
livenessProbe.timeoutSeconds Timeout seconds for livenessProbe 20
livenessProbe.failureThreshold Failure threshold for livenessProbe 3
livenessProbe.successThreshold Success threshold for livenessProbe 1
readinessProbe.enabled Enable readinessProbe on RabbitMQ containers true
readinessProbe.initialDelaySeconds Initial delay seconds for readinessProbe 10
readinessProbe.periodSeconds Period seconds for readinessProbe 30
readinessProbe.timeoutSeconds Timeout seconds for readinessProbe 20
readinessProbe.failureThreshold Failure threshold for readinessProbe 3
readinessProbe.successThreshold Success threshold for readinessProbe 1

Additional Configuration

Parameter Description Default
extraEnvVars Additional environment variables to set []
extraVolumes Additional volumes to add to the pod []
extraVolumeMounts Additional volume mounts to add to the RabbitMQ container []
extraObjects A list of additional Kubernetes objects to deploy alongside the release []
podManagementPolicy A list of additional Kubernetes objects to deploy alongside the release OrderedReady
podManagementPolicy A list of additional Kubernetes objects to deploy alongside the release OrderedReady
podManagementPolicy A list of additional Kubernetes objects to deploy alongside the release OrderedReady
podManagementPolicy A list of additional Kubernetes objects to deploy alongside the release OrderedReady
podManagementPolicy A list of additional Kubernetes objects to deploy alongside the release OrderedReady
podManagementPolicy A list of additional Kubernetes objects to deploy alongside the release OrderedReady

Persistent Volume Claim Retention Policy

Parameter Description Default
persistentVolumeClaimRetentionPolicy.enabled Enable Persistent volume retention policy false
persistentVolumeClaimRetentionPolicy.whenDeleted Volume retention behavior when replica is deleted Retain
persistentVolumeClaimRetentionPolicy.whenScaled Volume retention behavior when replica count is reduced Retain

ServiceAccount

Parameter Description Default
serviceAccount.create Enable creation of ServiceAccount true
serviceAccount.name Name of serviceAccount ""
serviceAccount.automountServiceAccountToken Automount service account token inside the RabbitMQ pods false
serviceAccount.annotations Annotations for service account {}

RBAC parameters

Parameter Description Default
rbac.create Whether RBAC rules should be created true
rbac.rules Custom RBAC rules []

Pod Disruption Budget configuration

Parameter Description Default
pdb.create Enable/disable a Pod Disruption Budget creation false
pdb.minAvailable Minimum number/percentage of pods that should remain scheduled ""
pdb.maxUnavailable Maximum number/percentage of pods that may be made unavailable ""

Extra Objects

You can use the extraObjects array to deploy additional Kubernetes resources (such as NetworkPolicies, ConfigMaps, etc.) alongside the release. This is useful for customizing your deployment with extra manifests that are not covered by the default chart options.

Helm templating is supported in any field, but all template expressions must be quoted. For example, to use the release namespace, write namespace: "{{ .Release.Namespace }}".

Example: Deploy a NetworkPolicy with templating

extraObjects:
  - apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: allow-dns
      namespace: "{{ .Release.Namespace }}"
    spec:
      podSelector: {}
      policyTypes:
        - Egress
      egress:
        - to:
            - namespaceSelector:
                matchLabels:
                  kubernetes.io/metadata.name: kube-system
              podSelector:
                matchLabels:
                  k8s-app: kube-dns
        - ports:
            - port: 53
              protocol: UDP
            - port: 53
              protocol: TCP

All objects in extraObjects will be rendered and deployed with the release. You can use any valid Kubernetes manifest, and reference Helm values or built-in objects as needed (just remember to quote template expressions).

Examples

Basic Deployment

Deploy RabbitMQ with default configuration:

helm install my-rabbitmq ./charts/rabbitmq

Production Setup with Persistence

# values-production.yaml
persistence:
  enabled: true
  storageClass: "fast-ssd"
  size: 50Gi

resources:
  requests:
    memory: "2Gi"
    cpu: "500m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

auth:
  enabled: true
  username: "admin"
  password: "your-secure-admin-password"

config:
  memoryHighWatermark:
    enabled: true
    type: "relative"
    value: 0.5

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: rabbitmq.yourdomain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: rabbitmq-tls
      hosts:
        - rabbitmq.yourdomain.com

Deploy with production values:

helm install my-rabbitmq ./charts/rabbitmq -f values-production.yaml

High Availability Cluster Setup

# values-cluster.yaml
replicaCount: 3

auth:
  erlangCookie: "somerandomstring" # chart updates will fail in ha cluster setups without this or existingErlangCookieKey
peerDiscoveryK8sPlugin:
  enabled: true
  useLongname: true
  addressType: hostname

resources:
  requests:
    memory: "4Gi"
    cpu: "1000m"
  limits:
    memory: "8Gi"
    cpu: "4000m"

persistence:
  enabled: true
  storageClass: "fast-ssd"
  size: 100Gi

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: app.kubernetes.io/name
                operator: In
                values:
                  - rabbitmq
          topologyKey: kubernetes.io/hostname

Using Existing Secret for Authentication

# values-external-secret.yaml
auth:
  enabled: true
  existingSecret: "rabbitmq-credentials"
  existingPasswordKey: "password"
  existingErlangCookieKey: "erlang-cookie"

Create the secret first:

kubectl create secret generic rabbitmq-credentials \
  --from-literal=password=your-rabbitmq-password \
  --from-literal=erlang-cookie=your-erlang-cookie

Enable Metrics and Monitoring

# values-monitoring.yaml
metrics:
  enabled: true
  serviceMonitor:
    enabled: true
    labels:
      prometheus: kube-prometheus
    interval: 15s
    scrapeTimeout: 10s

additionalPlugins:
  - rabbitmq_shovel
  - rabbitmq_federation

Access RabbitMQ

Via kubectl port-forward

kubectl port-forward service/my-rabbitmq 15672:15672

Access Management UI

Open http://localhost:15672 in your browser and login with:

  • Username: admin (or configured username)
  • Password: Get from secret or configured value

Connect using AMQP

kubectl port-forward service/my-rabbitmq 5672:5672

Default Credentials

  • Admin User: admin
  • Admin Password: Auto-generated (check secret) or configured value
  • Management UI Port: 15672
  • AMQP Port: 5672

Get the auto-generated password:

kubectl get secret my-rabbitmq -o jsonpath="{.data.password}" | base64 --decode

Troubleshooting

Common Issues

  1. Pod fails to start with permission errors

    • Ensure your storage class supports the required access modes
    • Check if security contexts are compatible with your cluster policies
    • Verify the RabbitMQ data directory permissions

  2. Cannot connect to RabbitMQ

    • Verify the service is running: kubectl get svc
    • Check if authentication is properly configured
    • Ensure firewall rules allow access to ports 5672 (AMQP) and 15672 (Management UI)
    • Check RabbitMQ logs: kubectl logs <pod-name>

  3. Clustering issues

    • Verify all nodes can reach each other
    • Check Erlang cookie consistency across cluster nodes
    • Ensure proper DNS resolution for pod hostnames
    • Review peer discovery plugin configuration

  4. Memory-related issues

    • Check configured memory high watermark settings
    • Monitor resource usage with kubectl top pod
    • Adjust memory limits and RabbitMQ memory configuration
    • Consider increasing resources

Getting Support

For issues related to this Helm chart, please check: