Migrate from v2 to v3

Moving from KubeMQ v2.10.x to KubeMQ v3. Companion to the KubeMQ v3 release notes.

The short version

• Recommended: start fresh. Deploy a new v3 cluster on the new (next) storage engine, move your applications to it, and retire the v2 cluster when you're done. The new cluster starts empty; no data is carried over.
• Alternative: upgrade in place. Replace the v2 server with v3 on your existing cluster. The server detects your existing data automatically and keeps running on it — same data, same configuration, no conversion.
• Either way, v3 is a one-way door. There is no rollback to v2. Plan the move, take a backup first, and validate before you commit.

Choosing your path

• Choose Path A when you want the full v3 feature set — the Kafka connector, strict durability mode, log compaction — and can treat messaging data as transient: queues drained before cutover, event history not needed on the new cluster.
• Choose Path B when preserving in-flight data and endpoints matters more than the next-engine features. It also works as a first step — you can stand up a fresh next-engine cluster later and move to it.

Before you begin

• Version — confirm you are on v2.10.x.
• Back up your store directory. Mandatory for Path B — it is your only way back. Recommended for Path A as part of retiring the old cluster.
• License — v3 uses the same license mechanism as v2 (see License key). Unsure whether your license covers v3? Ask support@kubemq.io before you start.
• Get v3 — images and install commands are in Docker and Kubernetes with Helm. Note the v3 Helm charts are published on the prerelease channel and require --devel on install and upgrade.
• Read the breaking changes in the release notes.

Path A — start a new v3 cluster (recommended)

Deploy the new cluster

• Docker / VM — follow the install guide. A fresh data directory means the server selects the next storage engine on its own; no engine setting required.
• Kubernetes — create a new KubemqCluster resource per Kubernetes with Helm, and set the storage engine explicitly in the cluster spec (spec.store.engine: next) so the new cluster starts on the next engine.
• Verify — the dashboard cluster overview shows the engine per node, or run kmq cluster info. The startup log also prints the selected engine.

Move your applications

The connection change is the whole change: same APIs, same SDK calls — point your applications at the new address. v2-era SDKs keep working against v3; upgrading SDKs is separate and not required for migration.

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 v2 cluster

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

The old cluster is your safety net until this moment — after retirement, the move is complete and there is nothing to roll back to.

Path B — upgrade the existing cluster in place

What happens on first start

The v3 server inspects the existing data directory and detects the v2-era (legacy) engine automatically — your data and configuration are used as-is. 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. Your endpoints, channels, queues, and subscriptions continue unchanged; applications reconnect and continue.

Upgrade steps

• Docker / VM — stop v2, back up the store directory, start v3 on the same store path (same commands as in Docker, pointing at your existing data volume).
• Kubernetes — update the chart/image per Kubernetes with Helm (remember --devel). Plan a maintenance window for the restart rather than assuming a zero-downtime mixed-version roll.

Verify

• The startup log reports the detected engine; the dashboard overview shows every node healthy on the legacy 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 engine

Everything in v3 works on the legacy engine except the next-engine features: 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.

Moving to the next engine later is Path A with your upgraded cluster as the source — there is no in-place engine conversion.

No rollback — read this before you start

Once a cluster runs v3, returning to v2 is not supported — for either path. Your protections instead of rollback:

• Path A — the untouched v2 cluster remains live until you retire it.
• Path B — the mandatory pre-upgrade backup is the only way back; restoring it means accepting the loss of everything since the backup.

Additionally, cluster nodes rebuilt with the v3 recovery procedure cannot roll back below v3.1.0.

After you migrate

• Enable what you need — protocol connectors, management-plane accounts, OpenTelemetry — all off by default.
• Use the kmq CLI for day-2 operations.
• Help: support@kubemq.io.

Frequently asked questions

Can I run v2 and v3 side by side? Yes — that is Path A. The two clusters are independent until you retire the old one.

Do I have to upgrade my SDKs? No. v2 SDKs work against v3; SDK upgrades are independent of the migration.

Can I move my queue backlog or event history to the 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.

Can I switch my upgraded (legacy) cluster to the next engine later? Yes — by standing up a next-engine cluster and moving to it (Path A). There is no in-place engine switch.

What happens if I try to downgrade? Downgrading is not supported. Restore the pre-upgrade backup to a v2 server if you must go back, accepting the loss of everything since that backup.