Kubernetes (Helm)

On Kubernetes, KubeMQ runs through the operator. You describe the server with a KubemqCluster custom resource, the operator reconciles it into a StatefulSet, Services, and configuration, and the kubemq-next Helm chart renders that resource from your cluster-values.yaml. Because the chart writes values straight into the CR, a Helm value path equals the KubemqCluster spec.* path with the leading spec. removed (spec.grpc.port → grpc.port).

This guide is the single source of truth for complete, runnable Helm and CRD configurations. The Configuration overview and the reference pages show minimal single-setting snippets and link here.

Configure with cluster-values.yaml

For anything beyond the license, add settings to the cluster-values.yaml you created in Install on Kubernetes. The license is set by Install on Kubernetes; its fields are listed in License. Each value maps 1:1 to a KubemqCluster spec.* field — the chart renders your values verbatim into the CR spec, so there is no separate Helm schema to learn.

Add each key once. Helm does not merge a repeated key: a second api: block replaces the first and drops your sign-in settings. To change a key the file already has (replicas, volume, api, licenseKeySecretRef, env), edit it in place instead of adding a second copy.

# Example keys — add only the ones you need. Each maps to spec.<key>.
# To publish an interface outside the cluster, see Expose interfaces below.

# REST is on by default; MCP / A2A / CloudEvents ride the REST HTTP port
# (disabled: false is the default — shown here only to be explicit)
rest:
  disabled: false
  port: 9090
  expose: ClusterIP

# Store limits and retention — enforced on the `legacy` engine only (see callout below)
store:
  messagesRetentionMinutes: 1440
  maxChannels: 0

# Pod resources — development-sized; size them for your load
resources:
  requestsCpu: 250m
  requestsMemory: 512Mi
  limitsCpu: "2"
  limitsMemory: 2Gi

Changing resources restarts the servers one at a time. Size them for your load with Resources.

Apply the file with the commands in Apply a settings change.

The same settings as a KubemqCluster resource, for a cluster you manage yourself with kubectl apply -f instead of Helm. Do not apply it to a cluster that Helm or kmq installed: they overwrite the resource on their next update. It reads the license from the Secret messaging-license that the Helm path of Install on Kubernetes creates.

apiVersion: next.kubemq.io/v1
kind: KubemqCluster
metadata:
  name: messaging
  namespace: kubemq
spec:
  licenseKeySecretRef:
    name: messaging-license
    key: licenseKey
  replicas: 3
  volume:
    size: 20Gi
    storageClass: YOUR_STORAGE_CLASS
  rest:
    disabled: false
    port: 9090
    expose: ClusterIP
  api:
    port: 8080
    expose: ClusterIP
    auth:
      enable: true
      adminUsername: admin
  store:
    messagesRetentionMinutes: 1440
    maxChannels: 0
  resources:
    requestsCpu: 250m
    requestsMemory: 512Mi
    limitsCpu: "2"
    limitsMemory: 2Gi

Replace:

• YOUR_STORAGE_CLASS — a storage class in your cluster, from kubectl get storageclass.

Apply a settings change

Find the chart version the cluster runs:

helm list --kube-context YOUR_KUBE_CONTEXT -n kubemq

Replace:

• YOUR_KUBE_CONTEXT — the kubectl context of your cluster, from kubectl config get-contexts.

You should see a row named messaging whose CHART column reads kubemq-next- followed by the chart version.

Apply cluster-values.yaml at that same version:

helm upgrade --install messaging kubemq-next/kubemq-next \
  --kube-context YOUR_KUBE_CONTEXT \
  -n kubemq \
  --version YOUR_VERSION \
  -f cluster-values.yaml \
  --wait

Replace:

• YOUR_VERSION — the version after kubemq-next- in the CHART column above.

You should see STATUS: deployed and a REVISION one higher than before.

Passing the version you already run changes settings only. To move to the latest release, follow Upgrade KubeMQ instead, which also updates the CRDs. Do not use --reuse-values.

Wait for the cluster to be ready with the new settings:

kubectl --context YOUR_KUBE_CONTEXT -n kubemq wait --for=condition=Ready kubemqclusters.next.kubemq.io/messaging --timeout=10m

You should see kubemqcluster.next.kubemq.io/messaging condition met.

Cluster size

A cluster runs 3 or more servers; see Requirements and supported setups. Use an odd count such as 3, 5, or 7, and choose it before you install: the count cannot change once the cluster is established (see High availability). For local development and testing, use the single-node Docker guide.

Expose interfaces

Set expose under the grpc: key (add the key if your file does not have it yet). Messaging authentication is off by default, so turn it on before you publish gRPC outside the cluster; see Security.

grpc:
  expose: LoadBalancer    # ClusterIP | NodePort | LoadBalancer

To publish the management API, add expose (and nodePort) under the api: key your file already has, keeping its auth settings. Beyond the cluster, serve it over TLS; see Use your own management certificate.

api:
  expose: NodePort
  nodePort: 32080         # only used with NodePort
  auth:
    enable: true
    adminUsername: admin

• ClusterIP — reachable only inside the cluster (the default for internal-only interfaces).
• NodePort — published on every node at nodePort; useful for direct access without a cloud load balancer.
• LoadBalancer — provisions an external load balancer (cloud environments).

nodePort applies only when expose: NodePort. On Docker there is no Service — publish ports with -p instead (see the Docker guide).

Zero-config Kafka

The Kafka connector is on by default — a fresh cluster needs no kafka: block at all, and no separate engine setting to manage.

With the store empty and store.engine left unset, the server auto-selects the next storage engine (store.engine: next) at first boot — see Storage Engines → Zero-config engine selection for the full selection rules. To run without Kafka, turn it off explicitly:

kafka:
  enabled: false

External reachability needs spec.kafka.expose plus an advertised host/port pair — see Connectors → Kafka for the full listener/TLS/SAN details.

Configure by domain

Every server setting — with its type, default, valid values, and both per-target columns — lives in the domain reference pages.

Verify

Confirm the operator has reconciled the cluster and the pods are ready.

Check the KubemqCluster resource and its status:

kubectl --context YOUR_KUBE_CONTEXT -n kubemq get kubemqclusters.next.kubemq.io

Replace:

• YOUR_KUBE_CONTEXT — the kubectl context of your cluster, from kubectl config get-contexts.

Inspect the full status, including the reconcile phase and any conditions:

kubectl --context YOUR_KUBE_CONTEXT -n kubemq describe kubemqclusters.next.kubemq.io messaging

Confirm the server pods are running:

kubectl --context YOUR_KUBE_CONTEXT -n kubemq get pods

You should see messaging-0, messaging-1 and messaging-2 with status Running.

To reach the dashboard, open a tunnel to the first server, then open http://127.0.0.1:18080 (https://127.0.0.1:18080 on a cluster kmq installed):

kubectl --context YOUR_KUBE_CONTEXT -n kubemq port-forward pod/messaging-0 18080:8080

Related

• Configuration overview — the two targets and the config model.
• Docker (single-node) — the local / dev target.
• Deployment & HA reference — packaging, replicas, and exposure in full.
• Install on Kubernetes — the step-by-step install guide.
• Upgrade KubeMQ — move a cluster to the latest release.