RabbitMQ Quickstart

This guide provides a comprehensive walkabout for deploying and managing RabbitMQ ReplicaSet Clusters using the KubeBlocks RabbitMQ Add-on, covering:

System prerequisites and add-on installation
Cluster creation and configuration
Operational management including start/stop procedures
Connection methods and cluster monitoring

Prerequisites

System Requirements

Before proceeding, verify your environment meets these requirements:

A functional Kubernetes cluster (v1.21+ recommended)
kubectl v1.21+ installed and configured with cluster access
Helm installed (installation guide)
KubeBlocks installed (installation guide)

Verify RabbitMQ Add-on

The RabbitMQ Add-on is included with KubeBlocks by default. Check its status:

helm list -n kb-system | grep rabbitmq

Example Output:

NAME                  NAMESPACE   REVISION    UPDATED                     STATUS      CHART
kb-addon-rabbitmq     kb-system   1           2025-05-21                  deployed    rabbitmq-1.0.0

If the add-on isn't enabled, choose an installation method:


# Add Helm repo
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts
# For users in Mainland China, if GitHub is inaccessible or slow, use this alternative repo:
#helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable

# Update helm repo
helm repo update
# Search available Add-on versions
helm search repo kubeblocks-addons/rabbitmq --versions
# Install your desired version (replace <VERSION> with your chosen version)
helm upgrade -i kb-addon-rabbitmq kubeblocks-addons/rabbitmq --version <VERSION> -n kb-system


# Add an index (kubeblocks is added by default)
kbcli addon index add kubeblocks https://github.com/apecloud/block-index.git
# Update the index
kbcli addon index update kubeblocks
# Update all indexes
kbcli addon index update --all

To search and install an addon:


# Search Add-on
kbcli addon search rabbitmq
# Install Add-on with your desired version (replace <VERSION> with your chosen version)
kbcli addon install rabbitmq --version <VERSION>

Example Output:

ADDON   VERSION         INDEX
rabbitmq   0.9.0           kubeblocks
rabbitmq   0.9.1           kubeblocks
rabbitmq   1.0.0           kubeblocks

To enable or disable an addon:


# Enable Add-on
kbcli addon enable rabbitmq
# Disable Add-on
kbcli addon disable rabbitmq

NOTE

Version Compatibility

Always verify that the RabbitMQ Add-on version matches your KubeBlocks major version to avoid compatibility issues.

Verify Supported RabbitMQ Versions

List available RabbitMQ versions:

kubectl get cmpv rabbitmq

Example Output

NAME       VERSIONS                                                         STATUS      AGE
rabbitmq   4.2.1,4.1.6,4.0.9,3.13.7,3.12.14,3.11.28,3.10.25,3.9.29,3.8.34   Available   21s

Check version compatibility for ComponentDefinitions

Step 1. Get the list of ComponentDefinition associated with a given ComponentVersion


kubectl get cmpv rabbitmq -ojson | jq -r '.metadata.annotations."componentversion.kubeblocks.io/compatible-definitions"' | tr ',' '\n'

Example Output

rabbitmq-1.0.2

Step 2. Get the list of ComponentDefinition associated with a given ComponentVersion


kubectl get cmpv rabbitmq -o json | jq -r '.spec.compatibilityRules[] | select(.compDefs | any(startswith("^rabbitmq"))) | .releases[]'

This returns versions compatible with ComponentDefinition named rabbitmq:

Example Output

4.2.1
4.1.6
4.0.9
3.13.7
3.12.14
3.11.28
3.10.25
3.9.29
3.8.34

Storage Configuration

RabbitMQ requires persistent storage. Verify available options:

kubectl get storageclass

Recommended storage characteristics:

Minimum 20Gi capacity
ReadWriteOnce access mode
Supports volume expansion
Appropriate performance for workload

Deploy a RabbitMQ Cluster

Deploy a basic RabbitMQ Cluster with default settings:

kubectl apply -f https://raw.githubusercontent.com/apecloud/kubeblocks-addons/refs/heads/main/examples/rabbitmq/cluster.yaml

This creates:

A RabbitMQ Cluster with 3 replicas.
Default resource allocations (0.5 CPU, 0.5Gi memory)
20Gi persistent storage


apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: rabbitmq-cluster
  namespace: demo
spec:
  # Specifies the behavior when a Cluster is deleted.
  # Valid options are: [DoNotTerminate, Delete, WipeOut] (`Halt` is deprecated since KB 0.9)
  # - `DoNotTerminate`: Prevents deletion of the Cluster. This policy ensures that all resources remain intact.
  # - `Delete`: Extends the `Halt` policy by also removing PVCs, leading to a thorough cleanup while removing all persistent data.
  # - `WipeOut`: An aggressive policy that deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, primarily in non-production environments to avoid irreversible data loss.
  terminationPolicy: Delete
  # Specifies the name of the ClusterDefinition to use when creating a Cluster.
  # Note: DO NOT UPDATE THIS FIELD
  # The value must be `rabbitmq` to create a RabbitMQ Cluster
  clusterDef: rabbitmq
  # Specifies the name of the ClusterTopology to be used when creating the
  # Cluster.
  # Valid options are: [clustermode]
  topology: clustermode
  componentSpecs:
    - name: rabbitmq
      # ServiceVersion specifies the version of the Service expected to be
      # provisioned by this Component.
      # Valid options are: [4.2.1,4.1.6,4.0.9,3.13.7,3.12.14,3.11.28,3.10.25,3.9.29,3.8.34]
      serviceVersion: 3.13.7
      # Update `replicas` to your need.
      # Recommended values are: [3,5,7]
      replicas: 3
      # Specifies the resources required by the Component.
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      # Specifies a list of PersistentVolumeClaim templates that define the storage
      # requirements for the Component.
      volumeClaimTemplates:
        # Refers to the name of a volumeMount defined in
        # `componentDefinition.spec.runtime.containers[*].volumeMounts
        - name: data
          spec:
            # The name of the StorageClass required by the claim.
            # If not specified, the StorageClass annotated with
            # `storageclass.kubernetes.io/is-default-class=true` will be used by default
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                # Set the storage size as needed
                storage: 20Gi

For more API fields and descriptions, refer to the API Reference.

TIP

More example manifests and setups for RabbitMQ can be found in the official KubeBlocks Add-ons RabbitMQ examples directory.

Create a Version-Specific RabbitMQ Cluster

To create a cluster with a specific version, configure spec.componentSpecs.serviceVersion (major.minor version) fields before applying it:


  componentSpecs:
    - name: rabbitmq
      serviceVersion: 4.0.9


  componentSpecs:
    - name: rabbitmq
      serviceVersion: 3.13.7    # Valid options: [3.13.7,3.13.2,3.12.14,3.11.28,3.10.25,3.9.29,3.8.14]

NOTE

RabbitMQ needs peer discovery role to create events and get endpoints. This is essential for discovering other RabbitMQ nodes and forming a cluster.

KubeBlocks will create SA with corresponding privilleges (Roles) on provisioning RabbitMQ Clusters.

Verify Cluster Status

When deploying a RabbitMQ Cluster with 3 replicas:

Confirm successful deployment by checking:

Cluster phase is Running
All pods are operational

Check status using either method:

kubectl get cluster rabbitmq-cluster -n demo -w
NAME               CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
rabbitmq-cluster   rabbitmq               Delete               Creating   27s
rabbitmq-cluster   rabbitmq               Delete               Running    64s

kubectl get pods -l app.kubernetes.io/instance=rabbitmq-cluster -n demo
NAME                          READY   STATUS    RESTARTS   AGE
rabbitmq-cluster-rabbitmq-0   2/2     Running   0          92s
rabbitmq-cluster-rabbitmq-1   2/2     Running   0          77s
rabbitmq-cluster-rabbitmq-2   2/2     Running   0          63s

With kbcli installed, you can view comprehensive cluster information:

kbcli cluster describe rabbitmq-cluster -n demo

Name: rabbitmq-cluster	 Created Time: May 18,2025 23:05 UTC+0800
NAMESPACE   CLUSTER-DEFINITION   TOPOLOGY      STATUS    TERMINATION-POLICY
demo        rabbitmq             clustermode   Running   Delete

Endpoints:
COMPONENT   INTERNAL                                                 EXTERNAL
rabbitmq    rabbitmq-cluster-rabbitmq.demo.svc.cluster.local:5672    <none>
            rabbitmq-cluster-rabbitmq.demo.svc.cluster.local:15672

Topology:
COMPONENT   SERVICE-VERSION   INSTANCE                      ROLE     STATUS    AZ       NODE    CREATED-TIME
rabbitmq    3.17.7            rabbitmq-cluster-rabbitmq-0   <none>   Running   zone-x   x.y.z   May 18,2025 23:05 UTC+0800
rabbitmq    3.17.7            rabbitmq-cluster-rabbitmq-1   <none>   Running   zone-x   x.y.z   May 18,2025 23:06 UTC+0800
rabbitmq    3.17.7            rabbitmq-cluster-rabbitmq-2   <none>   Running   zone-x   x.y.z   May 18,2025 23:06 UTC+0800

Resources Allocation:
COMPONENT   INSTANCE-TEMPLATE   CPU(REQUEST/LIMIT)   MEMORY(REQUEST/LIMIT)   STORAGE-SIZE   STORAGE-CLASS
rabbitmq                        500m / 500m          512Mi / 512Mi           data:20Gi      <none>

Images:
COMPONENT   COMPONENT-DEFINITION     IMAGE
rabbitmq    rabbitmq-1.0.0           docker.io/library/rabbitmq:3.13.7-management

Data Protection:
BACKUP-REPO   AUTO-BACKUP   BACKUP-SCHEDULE   BACKUP-METHOD   BACKUP-RETENTION   RECOVERABLE-TIME

Show cluster events: kbcli cluster list-events -n demo rabbitmq-cluster

Access RabbitMQ Management Console

Retrieve credentials The user and password can be found in the cluster secrets named after <clusterName>-<cmpName>-account-<accountName>. In this case, the secret name is rabbitmq-cluster-rabbitmq-account-root.


# get user name
NAME=$(kubectl get secrets -n demo rabbitmq-cluster-rabbitmq-account-root -o jsonpath='{.data.username}' | base64 -d)
# get password
PASSWD=$(kubectl get secrets -n demo rabbitmq-cluster-rabbitmq-account-root -o jsonpath='{.data.password}' | base64 -d)

Port-forward Service

kubectl port-forward svc/rabbitmq-cluster-rabbitmq -ndemo 15672:15672

Access Management Console

Then log in to the RabbitMQ Management console at http://<endpoint>:<port>/ with the user and password.

Stop the RabbitMQ Cluster

Stopping a cluster temporarily suspends operations while preserving all data and configuration:

Key Effects:

Compute resources (Pods) are released
Persistent storage (PVCs) remains intact
Service definitions are maintained
Cluster configuration is preserved
Operational costs are reduced

kubectl apply -f https://raw.githubusercontent.com/apecloud/kubeblocks-addons/refs/heads/main/examples/rabbitmq/stop.yaml


apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: rabbitmq-stop
  namespace: demo
spec:
  clusterName: rabbitmq-cluster
  type: Stop

Alternatively, stop by setting spec.componentSpecs.stop to true:


kubectl patch cluster rabbitmq-cluster -n demo --type='json' -p='[
{
  "op": "add",
  "path": "/spec/componentSpecs/0/stop",
  "value": true
}
]'


spec:
  componentSpecs:
    - name: rabbitmq
      stop: true  # Set to stop component
      replicas: 3

Start the RabbitMQ Cluster

Restarting a stopped cluster resumes operations with all data and configuration intact.

Key Effects:

Compute resources (Pods) are recreated
Services become available again
Cluster returns to previous state

kubectl apply -f https://raw.githubusercontent.com/apecloud/kubeblocks-addons/refs/heads/main/examples/rabbitmq/start.yaml


apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: rabbitmq-start
  namespace: demo
spec:
  clusterName: rabbitmq-cluster
  type: Start

Restart by setting spec.componentSpecs.stop to false:


kubectl patch cluster rabbitmq-cluster -n demo --type='json' -p='[
{
  "op": "remove",
  "path": "/spec/componentSpecs/0/stop"
}
]'

Delete RabbitMQ Cluster

Choose carefully based on your data retention needs:

Policy	Resources Removed	Data Removed	Recommended For
DoNotTerminate	None	None	Critical production clusters
Delete	All resources	PVCs deleted	Non-critical environments
WipeOut	All resources	Everything*	Test environments only

*Includes snapshots and backups in external storage

Pre-Deletion Checklist:

Verify no applications are using the cluster
Ensure required backups exist
Confirm proper terminationPolicy is set
Check for dependent resources

For test environments, use this complete cleanup:


kubectl patch cluster rabbitmq-cluster -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge" -n demo
kubectl delete cluster rabbitmq-cluster -n demo

RabbitMQ Quickstart | KubeBlocks

RabbitMQ Quickstart

Prerequisites

System Requirements

Verify RabbitMQ Add-on

Verify Supported RabbitMQ Versions

Storage Configuration

Deploy a RabbitMQ Cluster

Create a Version-Specific RabbitMQ Cluster

Verify Cluster Status

Access RabbitMQ Management Console

Stop the RabbitMQ Cluster

Start the RabbitMQ Cluster

Delete RabbitMQ Cluster