# Migrate from v2 to v3 (/deploy/migrate-v2-to-v3) Moving from KubeMQ v2.10.x to KubeMQ v3. Companion to the [KubeMQ v3 release notes](/release-notes/v3). ## The short version [#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 [#choosing-your-path] | | Path A — new cluster (recommended) | Path B — in-place upgrade | | ------------------------------ | ----------------------------------- | ------------------------- | | Storage engine after migration | next (new) | legacy (unchanged) | | Existing data | not carried over — fresh start | fully preserved | | Kafka connector available | yes | no (requires next) | | Application cutover | planned, gradual | none — same endpoints | | Rollback to v2 | old cluster untouched until retired | **none** | * Choose **Path A** when you want the full v3 feature set — the [Kafka connector](/connectors/kafka), 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 [#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](/deploy/license-key)). Unsure whether your license covers v3? Ask [support@kubemq.io](mailto:support@kubemq.io) before you start. * **Get v3** — images and install commands are in [Docker](/deploy/docker) and [Kubernetes with Helm](/deploy/kubernetes-helm). Note the v3 Helm charts are published on the prerelease channel and require `--devel` on install and upgrade. * **Read** the [breaking changes](/release-notes/v3#breaking-changes-at-a-glance) in the release notes. ## Path A — start a new v3 cluster (recommended) [#path-a--start-a-new-v3-cluster-recommended] ### Deploy the new cluster [#deploy-the-new-cluster] * **Docker / VM** — follow the [install guide](/deploy/docker). 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](/deploy/kubernetes-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 [#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](/operate/web-dashboard). ### Drain and retire the v2 cluster [#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 [#path-b--upgrade-the-existing-cluster-in-place] ### What happens on first start [#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 [#upgrade-steps] * **Docker / VM** — stop v2, back up the store directory, start v3 on the same store path (same commands as in [Docker](/deploy/docker), pointing at your existing data volume). * **Kubernetes** — update the chart/image per [Kubernetes with Helm](/deploy/kubernetes-helm) (remember `--devel`). Plan a maintenance window for the restart rather than assuming a zero-downtime mixed-version roll. ### Verify [#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](/operate/kmq-cli)). ### Life on the legacy engine [#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](/configure/reference/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 [#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 [#after-you-migrate] * Enable what you need — [protocol connectors](/connectors), [management-plane accounts](/configure/reference/security), [OpenTelemetry](/learn/guides/opentelemetry) — all off by default. * Use the [kmq CLI](/operate/kmq-cli) for day-2 operations. * Help: [support@kubemq.io](mailto:support@kubemq.io). ## Frequently asked questions [#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.