# Coming from legacy v2 (/deploy/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](/deploy/kubernetes-helm) or [Install with Docker](/deploy/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 [#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. | | Kubernetes | Docker / VM | | ------------------- | ----------------------------------- | ---------------------------------- | | In-place upgrade | **not supported** | supported (standalone node proven) | | Existing data | not carried over — fresh start | preserved | | Application cutover | planned, gradual | none — same endpoints | | Way back | old cluster untouched until retired | the backup you take first | ## Before you begin [#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](/deploy/license-key)). Unsure whether your license covers it? Ask [support@kubemq.io](mailto:support@kubemq.io) before you start. * **Platform** — `-next` images are built for `linux/amd64`. ## Kubernetes — install fresh beside the legacy installation [#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 [#install-the-new-line] ```bash title="Terminal" 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](/deploy/kubernetes-helm). With both lines installed, a short resource name such as `kubemqcluster` is ambiguous. **Always name the API group in `kubectl`:** ```bash title="Terminal" 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 [#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](/operate/web-dashboard). ### Drain and retire the legacy cluster [#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 [#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`**: ```bash title="Terminal" 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](/deploy/docker)). ### What happens on first start [#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. **Proven for a standalone node. Not yet proven for a clustered Docker/VM deployment.** The in-place move has been verified on a single standalone server. A multi-node v2 cluster on Docker or VMs has not been verified yet — for that topology, stand up a fresh next-line cluster beside the old one and move traffic, as on Kubernetes. ### Verify [#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](/operate/kmq-cli)). ### Life on the legacy storage engine [#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](/connectors/kafka), 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). 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 [#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 [#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 [#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.