From Kafka
Prepare KubeMQ alongside your existing Kafka environment. Copy topic history, map consumer positions and validate the target while your source continues serving applications. Then move each workload in a coordinated cutover.
During migration · both environments running
Source stays in place. You choose the cutover.
Two environments. One controlled transition.
Replication and validation happen alongside your source environment. The application switch is a separate, deliberate step.
Your producers and consumers stay connected to the source during preparation. The migration tool reads source topics without producing records, committing source offsets or joining source consumer groups.
Topic records are written into KubeMQ with their keys, values, headers and source partition preserved. Validate application behavior and throughput on the target before moving production traffic.
Use --topic to scope record copying. Group related producers, topics and consumers into a migration wave, then repeat for the next independent workload.
At cutover, coordinate producers, pause the selected consumers, complete the remaining copy and seed translated offsets before reconnecting them to KubeMQ.
These constraints apply to the KubeMQ migration tools.
Inside the kmq CLI
Each phase has a specific job. All migration writes go to the KubeMQ target; the source is read-only to the tools.
kmq migrate assessInspect topic configuration and consumer groups. Get per-topic fitness results so you can select the first migration wave and address compatibility requirements up front.
kmq migrate replicateCopy in parallel. Catch up before you switch. Each run copies records up to the source offsets captured at its start. Run it again to catch up with new records while Kafka stays active. Copy history into the corresponding target partitions. A local state file tracks copied positions and the source-to-target offset map. Re-run with the same state file to resume copying and bring over additional records.
kmq migrate translateSee where each consumer group will resume on the target. This read-only preview translates committed offsets using the recorded map, giving your team a checkpoint before cutover.
kmq migrate cutoverWith the selected source and target consumer groups inactive, verify replication has reached the committed positions and seed their target offsets. Update client endpoints and authentication settings, then resume consumers on KubeMQ.
Consumer continuity
Kafka and KubeMQ can assign different offsets to a record. The migration tools record the correspondence so consumers resume from the mapped target position.
Kafka / partition 0 / 1042↓ offset mapKubeMQ / partition 0 / 876Deploy KubeMQ alongside the source and use the migration tools to copy records into it. Existing applications continue using Kafka during preparation while you validate KubeMQ separately. Re-run replication with the same state file to copy additional records, then coordinate the final catch-up and client switch for each workload.
For supported Kafka clients and features, keep your existing client library and application code. Change bootstrap.servers to KubeMQ and configure the target’s authentication. The assessment and a staged test identify any workload-specific adjustments before production cutover.
Do the copying and validation ahead of the switch. Choose a cutover window for the selected workload, coordinate its producers and pause its consumers for the final catch-up and offset seeding. Resume on KubeMQ and verify processing before expanding to the next wave. This concentrates the production change into a planned step rather than the entire migration period.
Use a target running the replicated storage engine used by new installations with strict acknowledgment policy, and retain the migration state file. Copying is resumable and at-least-once: a crash between target acknowledgment and saving the offset map can cause a record to be copied again. Include duplicate handling in your application validation.
Confirm a producer can write and a consumer can read through the KubeMQ Kafka listener. Check that migrated consumer groups resume at the positions shown in the translation preview, then compare processing behavior, throughput and latency with your acceptance criteria.
Follow the post-cutover checksYes. The migration tools leave source records and committed offsets untouched, so you can retain the original environment while validating each wave. Plan how to handle any new records written after cutover if you need to return traffic to the source; those target writes are not automatically copied back.
Bring your topics, consumer groups and throughput requirements. We’ll help plan the parallel setup and cutover.
Install kmq for macOS, Linux or Windows, start Docker, then run:
kmq onboard --goal evaluation --name kubemq --platform linux/amd64 --pullUse the returned installation identifier to authenticate and verify. Enter your password locally when prompted.
kmq auth setup --installation INSTALLATION_ID --username admin
kmq deploy verify --installation INSTALLATION_IDSee installation and verification steps →
For Podman, add the --runtime podman option. The server image is Linux x86-64; Apple Silicon needs x86-64 emulation in the container runtime. Coding agents can read the installed kmq command schema and skills before planning changes.
Help me deploy KubeMQ using kmq. Read https://docs.kubemq.io/deploy/cli and inspect `kmq version`, `kmq schema -o json` and `kmq skills get core`. Ask whether I want evaluation, trial or production and which runtime/context to use. Explain missing prerequisites. Inspect before changing resources. Use saved plans and explicit targets. Keep passwords, email codes and license keys out of chat, command arguments and logs; let me enter them through protected local input. Preserve existing data and installation identity. Verify license adoption, authenticated access and an exact message round trip before reporting success. If anything fails, show the actual state and a bounded recovery step.This single-line evaluation command works in macOS and Linux shells and Windows PowerShell. Replace Docker with Podman when using Podman.
docker run -d --platform linux/amd64 --name kubemq --hostname kubemq -p 127.0.0.1:8080:8080 -p 127.0.0.1:50000:50000 -p 127.0.0.1:9090:9090 -v kubemq-data:/kubemq/store europe-docker.pkg.dev/kubemq/images/kubemq-next:v3.5.0Open the local dashboard to create your administrator account. Verify the installation and send a message →
The evaluation starts on a fresh standalone data volume. Keep that volume if you later add a trial or paid license. Online evaluation needs outbound HTTPS to license.kubemq.io. By running it, you accept the evaluation terms, including required usage reporting.