Upgrade KubeMQ

This page upgrades a running KubeMQ installation to the latest release. When you finish, kmq license shows the new release in its VERSION column, the license is still active, and a test message round-trips. Time: about 15 minutes.

Commands use the default names kubemq-operator, messaging, kubemq and the namespace kubemq; use your own if they differ.

These commands are for bash on macOS and Linux. On Windows, run them in WSL (Windows Subsystem for Linux), or use the kmq tab of Try KubeMQ, which runs natively on Windows.

Before you start

1. Update kmq, the KubeMQ command-line tool:

   kmq update

   You should see:

   HARNESS_OUTPUT_PENDING

   If kmq reports unknown command "update", re-run the installer from Try KubeMQ.

2. Find what you run: the VERSION column of kmq license (on Kubernetes, kmq license --kube-context YOUR_KUBE_CONTEXT). For Helm, list the releases:

   helm list --kube-context YOUR_KUBE_CONTEXT -A

   Replace: YOUR_KUBE_CONTEXT — your cluster's kubectl context; kubectl config get-contexts lists them.

   If one Helm release holds both the operator and the cluster, go to Move from the old combined chart release first. Artifact names: Requirements and supported setups.

3. Read Release notes for each release after yours, especially "Before you upgrade".

4. Back up: on one server, steps 1 to 4 of Back up and restore. For Kubernetes, contact support before relying on a restore.

Steps

Upgrade one server

kmq deploy update --installation kubemq --deadline 10m

HARNESS_OUTPUT_PENDING

docker pull --platform linux/amd64 europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

HARNESS_OUTPUT_PENDING

docker stop kubemq

docker rm kubemq

docker volume ls --filter name=kubemq-data --format '{{.Name}}'

HARNESS_OUTPUT_PENDING

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  --env-file kubemq-license.env \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

docker ps --filter name=kubemq --format '{{.Names}}: {{.Status}}'

HARNESS_OUTPUT_PENDING

Then check the license:

kmq license

You should see:

HARNESS_OUTPUT_PENDING

VERSION shows the new release; STATE is unchanged. If kmq cannot connect, the server is still starting: wait a few seconds and run it again. Sign in at http://localhost:8080: your channels are still there.

Upgrade a Kubernetes cluster

kmq deploy update --installation messaging --deadline 20m

HARNESS_OUTPUT_PENDING

helm repo update kubemq-next

HARNESS_OUTPUT_PENDING

helm show crds kubemq-next/kubemq-next | kubectl --context YOUR_KUBE_CONTEXT apply --server-side --force-conflicts -f -

HARNESS_OUTPUT_PENDING

helm upgrade --install kubemq-operator kubemq-next/kubemq-next --kube-context YOUR_KUBE_CONTEXT -n kubemq \
  --set operator.enabled=true --set cluster.enabled=false --wait

HARNESS_OUTPUT_PENDING

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

HARNESS_OUTPUT_PENDING

Then wait until every server is ready:

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

Replace: YOUR_KUBE_CONTEXT — your cluster's kubectl context; kubectl config get-contexts lists them.

You should see:

HARNESS_OUTPUT_PENDING

Check the license:

kmq license --kube-context YOUR_KUBE_CONTEXT

You should see:

HARNESS_OUTPUT_PENDING

Then send a test message as in Install on Kubernetes.

Roll back

A store written by a newer release may not be readable by an older one. Roll back only when the release notes say the upgrade is reversible: install the previous release as "Pin a version" shows, and on Kubernetes also run helm rollback for the operator. Otherwise, restore your backup as in Back up and restore; for Kubernetes, contact support first.

Move from the old combined chart release

Older charts put the operator and the cluster in one Helm release. The current chart refuses a release that enables both: operator and cluster must use independent releases. Contact support before upgrading a release that contains both the operator and the cluster.

If something goes wrong

• The servers still run the old release. Run the wait command again. If they stay old, repeat the Helm steps without --reuse-values.
• A server restarts with a storage error in its log. Restore your backup and check the release notes.
• A licensing message in the log. Look up the anchor it prints in Troubleshooting.

Next steps