kubeblocks-addon-rabbitmq

name	kubeblocks-addon-rabbitmq
metadata	{"version":"0.1.0"}
description	Legacy compatibility shim for RabbitMQ provisioning on KubeBlocks. The primary create-time entry is kubeblocks-engine-rabbitmq. Keep this skill callable for older references, but do not recommend it as the main path for cold-start agents.

Deploy RabbitMQ on KubeBlocks

Legacy compatibility shim. Primary entry: kubeblocks-engine-rabbitmq. Keep the preserved workflow below for detailed reference, but do not recommend this skill as the main path for cold-start agents.

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.