apecloud/kubeblocks-addon-rabbitmq

Deploy RabbitMQ on KubeBlocks

Overview

Deploy RabbitMQ clusters on Kubernetes using KubeBlocks. RabbitMQ is a lightweight message broker supporting AMQP, MQTT, and STOMP. Multiple replicas form a cluster with queue mirroring and quorum queues. Default ports: 5672 (AMQP), 15672 (Management UI), 15692 (Prometheus metrics).

Official docs: https://kubeblocks.io/docs/preview/kubeblocks-for-rabbitmq/01-overview Quickstart: https://kubeblocks.io/docs/preview/kubeblocks-for-rabbitmq/02-quickstart

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed (see install-kubeblocks)
• The RabbitMQ addon must be enabled:

# Check if rabbitmq addon is installed
helm list -n kb-system | grep rabbitmq

# Install if missing
helm install kb-addon-rabbitmq kubeblocks/rabbitmq --namespace kb-system --version 1.0.0

Topology

| Topology | Value | Component | Use Case | |---|---|---|---| | Cluster Mode | clustermode | rabbitmq | Single topology; multiple replicas form a cluster with queue mirroring/quorum queues |

Supported Versions

| Version | serviceVersion | |---|---| | RabbitMQ 3.8 | 3.8.34 | | RabbitMQ 3.9 | 3.9.29 | | RabbitMQ 3.10 | 3.10.25 | | RabbitMQ 3.11 | 3.11.28 | | RabbitMQ 3.12 | 3.12.14 | | RabbitMQ 3.13 | 3.13.7 | | RabbitMQ 4.0 | 4.0.9 | | RabbitMQ 4.1 | 4.1.6 | | RabbitMQ 4.2 | 4.2.1 |

List available versions: kubectl get cmpv rabbitmq

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster (dry-run, then apply)
- [ ] Step 4: Wait for cluster to be ready
- [ ] Step 5: Connect (Management UI or rabbitmqctl)

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep rabbitmq

If not found:

helm install kb-addon-rabbitmq kubeblocks/rabbitmq --namespace kb-system --version 1.0.0

Step 2: Create Namespace

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -

Step 3: Create Cluster

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: rabbitmq-cluster
  namespace: demo
spec:
  clusterDef: rabbitmq
  topology: clustermode
  terminationPolicy: Delete
  componentSpecs:
    - name: rabbitmq
      serviceVersion: "3.13.7"
      replicas: 3
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Dry-run before apply:

kubectl apply -f cluster.yaml --dry-run=server

If dry-run succeeds:

kubectl apply -f cluster.yaml

Step 4: Wait for Cluster Ready

kubectl -n demo get cluster rabbitmq-cluster -w

Success condition: STATUS shows Running. Typical duration: 1-2 minutes. Investigate after 10 min if stuck.

Check pods:

kubectl -n demo get pods -l app.kubernetes.io/instance=rabbitmq-cluster

Step 5: Connect

Management UI (port-forward)

Credentials are in Secret <clusterName>-<componentName>-account-root (e.g. rabbitmq-cluster-rabbitmq-account-root):

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

# Port-forward Management UI (port 15672)
kubectl port-forward svc/rabbitmq-cluster-rabbitmq -n demo 15672:15672

Access http://localhost:15672 and log in with the credentials.

rabbitmqctl (CLI)

kubectl -n demo exec -it rabbitmq-cluster-rabbitmq-0 -- rabbitmqctl cluster_status

Troubleshooting

Cluster stuck in Creating:

kubectl -n demo describe cluster rabbitmq-cluster
kubectl -n demo get events --sort-by='.lastTimestamp'

Pod not starting:

kubectl -n demo logs rabbitmq-cluster-rabbitmq-0

Cluster formation issues:

• Ensure odd number of replicas (3, 5, 7) for quorum
• Check peer discovery; KubeBlocks creates SA with required privileges

Day-2 Operations

| Operation | Skill | External Docs | |---|---|---| | Stop / Start / Restart | cluster-lifecycle | Docs | | Scale CPU / Memory | vertical-scaling | Docs | | Add / Remove replicas | horizontal-scaling | Docs | | Expand storage | volume-expansion | Docs | | Expose externally | expose-service | Docs |

Safety Patterns

Follow safety-patterns: dry-run before apply, confirm status after apply, pre-deletion checklist for delete.