Install KubeMQ with Helm

Prerequisites

Before you begin, ensure you have the following installed and configured:

• Kubernetes cluster (v1.20 or later) — any distribution (EKS, GKE, AKS, k3s, minikube)
• kubectl — configured to access your cluster
• Helm v3 — download from helm.sh
• KubeMQ license key — required for the cluster to start

How it works

KubeMQ ships four Helm charts. The standard install path is a 3-step sequence:

1. kubemq-crds — CRD schema only. Registers the KubemqCluster (and KubemqConnector) resource types with Kubernetes. No workloads, no operator.
2. kubemq-controller — The operator Deployment. Watches for KubemqCluster resources and reconciles StatefulSets, Services, and configuration.
3. kubemq-cluster — Renders one KubemqCluster custom resource. This chart is a thin passthrough: nearly every Helm value you set becomes the identically-named field on the CR's spec, and the operator installed in step 2 does the actual reconciling.

A fourth chart, the umbrella kubemq chart, bundles CRDs + operator + one KubemqCluster CR into a single release — a one-shot alternative to running the three charts above in sequence. It requires only key (your license) to render.

All components are installed into the kubemq namespace.

Add the KubeMQ Helm repository

Register the KubeMQ Helm chart repository and update your local chart index.

helm repo add kubemq-charts https://kubemq-io.github.io/charts
helm repo update

Verify the repository was added successfully:

helm search repo kubemq-charts

You should see charts for kubemq-crds, kubemq-controller, kubemq-cluster, and the umbrella kubemq chart.

Install KubeMQ

KubeMQ installation on Kubernetes requires three Helm charts installed in order: CRDs, the controller (operator), and the cluster itself.

helm install --create-namespace -n kubemq kubemq-crds kubemq-charts/kubemq-crds

helm install --wait -n kubemq kubemq-controller kubemq-charts/kubemq-controller

helm install --wait -n kubemq kubemq-cluster kubemq-charts/kubemq-cluster \
  --set key=YOUR_LICENSE_KEY

Supplying the license from a Secret

Passing --set key=YOUR_LICENSE_KEY stores the raw license as a Helm value (recoverable via helm get values) and on the KubemqCluster object. To keep the token out of cluster state — the recommended path for GitOps, where manifests live in git — put the license in a Kubernetes Secret and reference it instead.

kubectl create secret generic kmq-license -n kubemq --from-literal=key=YOUR_LICENSE_KEY

Then install (or apply a CR) with keySecretRef in place of key:

helm install --wait -n kubemq kubemq-cluster kubemq-charts/kubemq-cluster \
  --set keySecretRef=kmq-license

The operator resolves the key from the Secret at reconcile time; the raw token never appears in the KubemqCluster object or the Helm release values.

Verify installation

Confirm that all KubeMQ pods are running and ready.

kubectl get pods -n kubemq

Expected output:

NAME                                  READY   STATUS    RESTARTS   AGE
kubemq-controller-xxxxxxxxx-xxxxx     1/1     Running   0          2m
kubemq-cluster-0                      1/1     Running   0          1m
kubemq-cluster-1                      1/1     Running   0          1m
kubemq-cluster-2                      1/1     Running   0          1m

Check the services exposed by KubeMQ:

kubectl get svc -n kubemq

To access the KubeMQ dashboard, port-forward the API service:

kubectl port-forward -n kubemq svc/kubemq-cluster 8080:8080

Then open http://localhost:8080 in your browser.

Charts & images

All four charts are published as stable GA releases — kubemq-crds 3.2.0, kubemq-cluster 3.2.0, the umbrella kubemq 3.2.0, and kubemq-controller 2.0.0 — a plain helm install resolves them, no --devel needed (see the callout above).

Images and the :next channel

The kubemq-controller chart's operator and server images default to the mutable image-tag :next — operatorImage and kubemqImage in the Controller chart values below. kubemqImage isn't consumed by the operator's own container — it feeds the operator's RELATED_IMAGE_KUBEMQ_CLUSTER environment variable, which is what the operator uses as the container image when it renders a KubemqCluster StatefulSet.

docker pull europe-docker.pkg.dev/kubemq/images/kubemq:next && \
  docker inspect --format='{{index .RepoDigests 0}}' europe-docker.pkg.dev/kubemq/images/kubemq:next

server-side apply failed … .spec.image.tag: field not declared in schema

image:
  image: europe-docker.pkg.dev/kubemq/images/kubemq:next@sha256:<digest>
  pullPolicy: IfNotPresent

Configurable values

The snippets below are illustrative, one per chart — not exhaustive field tables. Field-by-field defaults and valid values for the KubemqCluster spec live in the Configuration Reference (linked throughout this section).

Controller chart values

operatorImage: europe-docker.pkg.dev/kubemq/images/kubemq-operator:next
kubemqImage: europe-docker.pkg.dev/kubemq/images/kubemq:next
imagePullSecrets:
  - name: my-registry-secret

# Images for the connector workloads started by the operator
connectorTargetsImage: europe-docker.pkg.dev/kubemq/images/kubemq-targets:next
connectorSourcesImage: europe-docker.pkg.dev/kubemq/images/kubemq-sources:next
connectorBridgesImage: europe-docker.pkg.dev/kubemq/images/kubemq-bridges:next

connectorTargetsImage, connectorSourcesImage, and connectorBridgesImage set the images the operator uses for the Targets, Sources, and Bridges connector workloads. Pin these to your own registry mirror in production — don't rely on the chart's built-in default.

Cluster chart values

Only key (your license, or keySecretRef — see Supplying the license from a Secret) and imagePullSecrets are native to this chart. Every other value is a verbatim passthrough to the KubemqCluster CR — a Helm value maps 1:1 to the spec.* field of the same name:

key: "YOUR_LICENSE_KEY"

# Everything below passes through as spec.* on the KubemqCluster CR —
# see the Configuration Reference for the full field list.
replicas: 3
volume:
  size: 50Gi

For the complete field list, see Deployment & High Availability and Storage Engines.

Umbrella chart values

Only key is chart-native, and it's required — the release fails to render without it. The operator image is hardcoded in the chart's template, not driven by operatorImage/kubemqImage:

key: "YOUR_LICENSE_KEY"

Using a values file

For complex configurations, create a values.yaml file for the kubemq-cluster chart:

key: "YOUR_LICENSE_KEY"
replicas: 3
standalone: false

volume:
  size: 20Gi
  storageClass: fast-ssd

grpc:
  expose: LoadBalancer
  port: 50000

api:
  expose: LoadBalancer
  port: 8080

resources:
  requestsCpu: "2"
  requestsMemory: 4Gi
  limitsCpu: "4"
  limitsMemory: 8Gi

Then install with:

helm install --wait -n kubemq kubemq-cluster kubemq-charts/kubemq-cluster -f values.yaml

Declarative install (KubemqCluster CR)

The kubemq-controller you installed above is the KubeMQ operator: it watches for KubemqCluster custom resources and reconciles the actual cluster state to match. Instead of passing cluster settings as Helm flags, you can describe the desired cluster declaratively in a KubemqCluster manifest and let the controller create and manage it.

Create a KubeMQ cluster

Define the desired cluster state in a KubemqCluster custom resource, then apply it with kubectl.

Basic cluster

apiVersion: core.k8s.kubemq.io/v1beta1
kind: KubemqCluster
metadata:
  name: kubemq-cluster
  namespace: kubemq
spec:
  replicas: 3
  key: "YOUR_LICENSE_KEY"

Apply the manifest:

kubectl apply -f kubemq-cluster.yaml

Standalone node (development)

For local development or testing, deploy a single standalone node:

apiVersion: core.k8s.kubemq.io/v1beta1
kind: KubemqCluster
metadata:
  name: kubemq-dev
  namespace: kubemq
spec:
  replicas: 1
  standalone: true
  key: "YOUR_LICENSE_KEY"
  grpc:
    expose: NodePort
    nodePort: 32000
  api:
    expose: NodePort
    nodePort: 32080

Production cluster

A production-ready configuration with resource limits, persistent storage, and LoadBalancer services:

apiVersion: core.k8s.kubemq.io/v1beta1
kind: KubemqCluster
metadata:
  name: kubemq-production
  namespace: kubemq
spec:
  replicas: 3
  key: "YOUR_LICENSE_KEY"
  volume:
    size: 50Gi
    storageClass: fast-ssd
  grpc:
    expose: LoadBalancer
    port: 50000
    bodyLimit: 100000000
  rest:
    disabled: false
    expose: ClusterIP
    port: 9090
  api:
    expose: LoadBalancer
    port: 8080
  resources:
    requestsCpu: "2"
    requestsMemory: 4Gi
    limitsCpu: "4"
    limitsMemory: 8Gi
  health:
    initialDelaySeconds: 5
    periodSeconds: 10
    timeoutSeconds: 5

To enable Kafka on Kubernetes, see the zero-config recipe in Configure → Zero-config Kafka.

Check the status of your cluster after applying a manifest:

kubectl get kubemqclusters -n kubemq

Manage the cluster

Scale

Update the replicas field in your manifest and re-apply, or patch the resource directly:

kubectl patch kubemqcluster kubemq-cluster -n kubemq \
  --type merge -p '{"spec":{"replicas":5}}'

Update configuration

Edit the KubemqCluster resource to change configuration. The operator reconciles changes automatically.

kubectl edit kubemqcluster kubemq-cluster -n kubemq

Or apply an updated manifest:

kubectl apply -f kubemq-cluster-updated.yaml

Delete

Remove a KubeMQ cluster while keeping the controller running (so it can still manage other clusters):

kubectl delete kubemqcluster kubemq-cluster -n kubemq

This removes all pods and services for that cluster. Persistent volume claims are retained by default.

Field reference

Field-by-field settings for the KubemqCluster spec — types, defaults, and valid values — live in the Configuration Reference, not here: Deployment & High Availability, Storage Engines, and Connectors.

Upgrade

Upgrade an existing KubeMQ installation to a new version or change configuration:

helm upgrade --wait -n kubemq kubemq-cluster kubemq-charts/kubemq-cluster \
  --set key=YOUR_LICENSE_KEY \
  --reuse-values

The --reuse-values flag preserves your existing configuration and only applies the changes you specify.

Helm does not upgrade CRDs

Helm never upgrades CRDs shipped in a chart's crds/ directory — running helm upgrade against kubemq-crds will not update an already-installed KubemqCluster CRD. That is deliberate: it is what stops a helm uninstall from cascade-deleting every KubemqCluster and its data. The CRD-upgrade path is applying the canonical manifest directly, not helm upgrade:

kubectl apply -f https://raw.githubusercontent.com/kubemq-io/charts/master/kubemq-crds/crds/kubemqclusters.core.k8s.kubemq.io.crd.yaml

Upgrade order

Upgrade in this order:

1. CRDs and the operator, together, in one step. The window where CRDs are upgraded but the operator is still old is transient — it is not a resting state you should pause in.
2. Server images. Because the server rides the mutable :next tag rather than a pinned semantic version, "upgrading" the server means rolling the pods so they re-pull the current :next image — there's no version number to bump to. If you've pinned the image to a digest for reproducibility (see Images and the :next channel), a plain pod roll won't pick up a new build on its own — re-pull :next, read its current digest, and re-pin it to upgrade.
3. Charts — the Helm release metadata itself (--reuse-values/--set as needed).

An explicit legacy CR gets one checksum-triggered rolling restart on upgrade. An established cluster keeps the engine it already has — the operator names it explicitly and nothing rolls. A fresh cluster with no engine on record is created with STORE_ENGINE=auto, and the server resolves it at boot. Once the engine is established as next, the replicas-freeze arms: spec.replicas becomes immutable on that CR.

v2.8.x → v2.9.0 (breaking)

The six wire-protocol connectors — MQTT, AMQP 0.9.1, AMQP 1.0, STOMP, AWS, and GCP — changed their CRD field from disabled: bool to enabled: *bool. This requires all three components upgraded in lockstep: kubemq-crds ≥ 2.13.0, kubemq-operator ≥ 1.19.0, and the server ≥ v3.0.0-b7. Kafka's enabled: *bool opt-in field is unaffected — it already used this shape, consistent with the post-v2.9 pattern.

Uninstall

Remove KubeMQ from your cluster. If you installed the three charts separately, uninstall in reverse order — this is the recommended, default path:

helm uninstall -n kubemq kubemq-cluster
helm uninstall -n kubemq kubemq-controller
helm uninstall -n kubemq kubemq-crds

If you installed the umbrella kubemq chart, you can remove the whole release in one step instead:

helm uninstall kubemq -n kubemq

The umbrella chart ships a pre-delete hook designed to delete the KubemqCluster resource and let the operator drain its finalizer before the operator itself is removed — that's what makes the one-step path possible.

helm upgrade kubemq kubemq-charts/kubemq -n kubemq --reuse-values \
  --set preDelete.image=<a-reachable-kubectl-image>
helm uninstall kubemq -n kubemq

helm upgrade kubemq kubemq-charts/kubemq -n kubemq --reuse-values \
  --set preDelete.enabled=false
kubectl delete kubemqcluster <name> -n kubemq
helm uninstall kubemq -n kubemq

To also remove the namespace:

kubectl delete namespace kubemq

Production checklist

Before you point real traffic at a cluster, run down this list.

Sizing: eval vs. production

Illustrative starting points, not hard requirements — tune to your message volume, payload size, and retention needs.

Related