Coming from legacy v2

This page is for teams running legacy KubeMQ v2 (the kubemq image, the kubemq-io/charts Helm charts, the core.k8s.kubemq.io API group). New installations should skip it and start at Install with Helm or Install with Docker.

The current product line is published as -next artifacts — the kubemq-next image, the kubemq-next chart, the next.kubemq.io/v1 API group. Its versions restart at v1.0.0. Do not compare that number with a v2 version: next line v1.0.0 is newer than every v2 release.

The short version

• Kubernetes — install fresh, beside the old one. There is no in-place path under the new operator. Install the new chart next to your legacy installation, move traffic across, then retire the old cluster.
• Docker / VM — in place is supported. Point a kubemq-next image at your v2 data directory. The server detects the legacy data layout on its own and keeps running on it.
• Connectors — by manifest only. There are no connector charts on the next line.
• Legacy v2 receives security fixes only. All new work lands on the next line.

Before you begin

• Back up your store directory. For an in-place move it is your only way back.
• License — the next line uses the same license mechanism (see License key). Unsure whether your license covers it? Ask support@kubemq.io before you start.
• Platform — -next images are built for linux/amd64.

Kubernetes — install fresh beside the legacy installation

The new operator manages only next.kubemq.io/v1 resources. It does not adopt, convert, or upgrade a legacy core.k8s.kubemq.io cluster, and the legacy operator does not see the new resources. Because the two lines use different API groups and different object names, both run in one Kubernetes cluster without interfering.

Install the new line

helm repo add kubemq-next https://kubemq-io.github.io/charts-next
helm repo update
helm install kubemq-next kubemq-next/kubemq-next -n kubemq --create-namespace \
  --set key=YOUR_LICENSE_KEY

One chart installs the CRDs, the operator, and one cluster. If your legacy installation already uses the kubemq namespace, that is fine — give the new cluster a different name from the old one (the release name kubemq-next does that by default). Full guide: Install with Helm.

With both lines installed, a short resource name such as kubemqcluster is ambiguous. Always name the API group in kubectl:

kubectl get kubemqclusters.next.kubemq.io -A        # the new line
kubectl get kubemqclusters.core.k8s.kubemq.io -A    # the legacy line

A fresh cluster with a clean store starts on the next storage engine (store.engine: next) — no engine setting required. Verify on the dashboard's cluster overview, or with kmq cluster info.

Move your applications

The connection change is the whole change: same APIs, same SDK calls — point your applications at the new cluster's address. SDKs that work against v2 keep working; upgrading SDKs is separate and not required.

Recommended cutover order per pattern:

• Queues — move producers first. New messages arrive on the new cluster while consumers drain the old backlog; move consumers once the old queues are empty.
• Pub/Sub (Events, Events Store) — move subscribers first so nothing published on the new cluster is missed, then move publishers.
• Commands/Queries — move responders first, then requesters.

Per application: change the connection configuration, deploy, then confirm its traffic on the new cluster's dashboard.

Drain and retire the legacy cluster

1. Let consumers drain the remaining queue backlogs on the old cluster.
2. Confirm zero traffic on the legacy dashboard.
3. Take a final backup, keep it per your retention policy, then uninstall the legacy charts.

There is no data carry-over between the two clusters. The old cluster is your safety net until you retire it.

Docker / VM — move in place

Stop the v2 container, back up the store directory, and start a kubemq-next image on the same store path with the same KUBEMQ_TOKEN:

docker stop kubemq && docker rm kubemq

docker run -d \
  --name kubemq \
  -p 50000:50000 -p 9090:9090 -p 8080:8080 \
  -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY \
  -v kubemq-data:/kubemq/store \
  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

Mount your existing v2 data volume at the path the server writes to (/kubemq/store by default — see Install with Docker).

What happens on first start

The server inspects the data directory and detects the legacy layout automatically — your data and configuration are used as-is, on the legacy storage engine. Detection is read-only and fail-safe: on anything unexpected the server stops with a clear error instead of touching your data. It never wipes, never converts, never guesses. Endpoints, channels, queues, and subscriptions continue unchanged; applications reconnect and continue.

Verify

• The startup log reports the detected storage engine; the dashboard overview shows the node healthy on the legacy storage engine.
• Spot-check queue depths and subscriptions, and run a send/receive round-trip: kmq queue send / kmq queue receive (kmq CLI).

Life on the legacy storage engine

Everything works on the legacy storage engine except the features that need the next storage engine: the Kafka connector, the strict ack durability mode, and log compaction / time-based retention. Native retention limits continue to work exactly as in v2. Details: Storage engines.

There is no in-place conversion between storage engines. To move to the next storage engine later, stand up a fresh deployment with a clean store and move traffic to it.

Connectors

Targets, Sources, and Bridges are installed by applying a next.kubemq.io/v1 KubemqConnector manifest — there are no connector Helm charts on the next line. Connector images ship in next v1.1; set spec.image explicitly on every KubemqConnector until then.

Support status of legacy v2

Legacy v2 receives security fixes only. It gets no new features, and its images, charts, and API group keep their existing names.

Frequently asked questions

Can I run legacy v2 and the next line side by side? Yes. On Kubernetes they use different API groups and object names, so both run in one cluster. On Docker, run them as separate containers with separate data volumes.

Can the new operator take over my existing KubemqCluster? No. It manages next.kubemq.io/v1 resources only. Install fresh and move traffic.

Do I have to upgrade my SDKs? No. SDK upgrades are independent of this move.

Can I move my queue backlog or event history to a new cluster? No — there is no data carry-over between clusters. Plan the cutover so queues drain on the old cluster before you retire it.

Why is the new version number lower than the one I run? Versions restarted with the new artifact names. next line v1.0.0 is a newer product than any v2 release; the numbers are not comparable.

What happens if I need to go back after an in-place move? Restore the pre-move backup to a v2 server, accepting the loss of everything since that backup.