Deploy a RocketMQ Cluster on Kubernetes with the RocketMQ Operator – Step‑by‑Step Guide

Overview

Apache RocketMQ is a high‑performance, low‑latency distributed messaging engine originally developed by Alibaba and now an Apache top‑level project. In cloud‑native environments, operating a stateful RocketMQ cluster (scaling brokers, synchronizing metadata, managing NameServers) is complex.

Why use a Kubernetes Operator

Kubernetes Operators extend the API with custom resources (CRDs) and controllers, encoding domain‑specific knowledge for managing stateful applications. The RocketMQ Operator automates creation, configuration, scaling, and lifecycle management of RocketMQ NameServer and Broker instances.

Prerequisites

Access to a Kubernetes cluster (Docker Desktop with built‑in K8s, Minikube, or any K8s environment).

Git installed locally.

Installing the RocketMQ Operator

Option 1 – OperatorHub & OLM

Search for "RocketMQ Operator" on OperatorHub.io and select the Streaming & Messaging category.

Click Install to deploy the Operator Lifecycle Manager (OLM) and the RocketMQ Operator.

After installation the operator appears under Installed Operators in the OpenShift/Console UI.

Option 2 – Manual Installation

$ git clone https://github.com/apache/rocketmq-operator.git
$ cd rocketmq-operator
$ ./install-operator.sh

Verify the installation:

$ kubectl get pods | grep rocketmq-operator
rocketmq-operator-76b4b9f4db-x52mz   1/1   Running   0   3h25m

Deploying a RocketMQ Cluster

Apply the example custom resources that define a Broker and a NameServer.

apiVersion: rocketmq.apache.org/v1alpha1
kind: Broker
metadata:
  name: broker
spec:
  size: 1
  nameServers: ""
  replicationMode: ASYNC
  replicaPerGroup: 1
  brokerImage: apacherocketmq/rocketmq-broker:4.5.0-alpine
  imagePullPolicy: Always
  resources:
    requests:
      memory: "2048Mi"
      cpu: "250m"
    limits:
      memory: "12288Mi"
      cpu: "500m"
  allowRestart: true
  storageMode: EmptyDir
  hostPath: /data/rocketmq/broker
  scalePodName: broker-0-master-0
  volumeClaimTemplates:
  - metadata:
      name: broker-storage
    spec:
      accessModes:
      - ReadWriteOnce
      storageClassName: rocketmq-storage
      resources:
        requests:
          storage: 8Gi
---
apiVersion: rocketmq.apache.org/v1alpha1
kind: NameService
metadata:
  name: name-service
spec:
  size: 1
  nameServiceImage: apacherocketmq/rocketmq-nameserver:4.5.0-alpine
  imagePullPolicy: Always
  hostNetwork: true
  dnsPolicy: ClusterFirstWithHostNet
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1024Mi"
      cpu: "500m"
  storageMode: EmptyDir
  hostPath: /data/rocketmq/nameserver
  volumeClaimTemplates:
  - metadata:
      name: namesrv-storage
    spec:
      accessModes:
      - ReadWriteOnce
      storageClassName: rocketmq-storage
      resources:
        requests:
          storage: 1Gi

Apply the resources:

$ kubectl apply -f example/rocketmq_v1alpha1_rocketmq_cluster.yaml
broker.rocketmq.apache.org/broker created
nameservice.rocketmq.apache.org/name-service created

Check the pods to confirm the cluster is running (one NameServer and a master‑replica broker pair):

$ kubectl get pods -o wide
NAME                     READY   STATUS    RESTARTS   AGE   IP          NODE
broker-0-master-0        1/1     Running   0          27s   10.1.2.27   docker-desktop
broker-0-replica-1-0    1/1     Running   0          27s   10.1.2.28   docker-desktop
name-service-0           1/1     Running   0          27s   192.168.65.3 docker-desktop
rocketmq-operator-...   1/1     Running   0          3h25m 10.1.2.17   docker-desktop

Running a Producer and Consumer

Execute the provided example scripts inside the broker and name‑service pods:

$ kubectl exec -it broker-0-master-0 bash
# sh ./tools.sh org.apache.rocketmq.example.quickstart.Producer

$ kubectl exec -it name-service-0 bash
# sh ./tools.sh org.apache.rocketmq.example.quickstart.Consumer

The logs show successful send and receive of messages, confirming the cluster works.

Cleanup

$ kubectl delete -f example/rocketmq_v1alpha1_rocketmq_cluster.yaml
$ ./purge-operator.sh

These commands remove the custom resources and the operator.

Future Outlook

RocketMQ Operator v0.2.1 supports automatic creation of NameServer and Broker clusters, seamless scaling of NameServers (auto‑updating broker IP lists), broker scaling with metadata synchronization, and topic migration. Planned enhancements include gray‑release support, full lifecycle data management, disaster recovery, metric‑driven autoscaling, and broader lifecycle coverage.

References

RocketMQ Operator GitHub repository: https://github.com/apache/rocketmq-operator

OperatorHub: https://operatorhub.io/

Operator Framework: https://github.com/operator-framework

Apache RocketMQ website: https://rocketmq.apache.org/

Apache RocketMQ source code: https://github.com/apache/rocketmq