# Migration (/connectors/how-to/migration)
This hub is the entry point for migrating an application from an external messaging
ecosystem onto KubeMQ's **wire-protocol connectors**. Each guide covers what migrates
cleanly, what migrates with caveats, and what does not migrate at all — the
endpoint/connection change, the concept-to-pattern mapping, a working code example, the
security posture, and a copy-pasteable smoke test.
**Important framing:** the nine covered ecosystems are *ecosystems*, not nine
connectors. KubeMQ has **seven wire-protocol connectors**; several ecosystems ride the same
connector. For example, JMS, ActiveMQ-Java, and native AMQP 1.0 clients all use the
**AMQP 1.0 connector** on port 5672.
## Ecosystem → Connector Map [#ecosystem--connector-map]
Each ecosystem maps onto one (or, for ActiveMQ, several) of the seven wire-protocol
connectors. Follow the connector link for that protocol's full reference; follow the
guide link in the [Guides](#guides) table below for the step-by-step migration.
| Ecosystem | KubeMQ connector | Default port(s) | Canonical client (this suite) |
| ----------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------- |
| JMS | [AMQP 1.0](/connectors/amqp) | 5672 / 5671 | Apache Qpid JMS |
| ActiveMQ | [AMQP 1.0](/connectors/amqp) (Java/JMS); [STOMP](/connectors/stomp) & [MQTT](/connectors/mqtt) for non-Java | 5672 / 5671, 61613 / 61614, 1883 / 8883 | Apache Qpid JMS (+ STOMP / MQTT clients) |
| RabbitMQ | [RabbitMQ (AMQP 0-9-1)](/connectors/rabbitmq) | 5672 / 5671 | `pika` (Python) |
| AMQP 1.0 | [AMQP 1.0](/connectors/amqp) | 5672 / 5671 | `go-amqp` (canonical; AMQP.NET Lite alt) |
| AWS SQS/SNS | [AWS](/connectors/aws) | 4566 (HTTP) | AWS SDK (`boto3`) |
| STOMP | [STOMP](/connectors/stomp) | 61613 / 61614 | `stomp.py` |
| GCP Pub/Sub | [Google Cloud Pub/Sub](/connectors/gcp-pub-sub) | 8085 (gRPC) | `google-cloud-pubsub` |
| MQTT | [MQTT](/connectors/mqtt) | 1883 / 8883 / 8083 | Eclipse Paho |
| Kafka | [Kafka](/connectors/kafka) | 9092 / 9093 | `kcat` |
AMQP 0-9-1 (RabbitMQ) and AMQP 1.0 share ports 5672 / 5671 — the server inspects the
protocol header and routes each connection to the right connector. The AWS port (4566) is
a client-side endpoint convention set in `Connectors.Aws.Port`; it is not a fixed broker
listener and does not appear in the standard broker port table.
## Cross-Protocol Comparison [#cross-protocol-comparison]
The table below is transposed: **axes are rows, ecosystems are columns**. Each cell uses
✅ full / ⚠️ partial / ❌ none / N/A (inapplicable — a concept that does not exist in that
ecosystem). ❌ means the concept exists in the source ecosystem but the KubeMQ connector
does not support it.
| Axis | JMS | ActiveMQ | RabbitMQ | AMQP 1.0 | AWS SQS/SNS | STOMP | GCP Pub/Sub | MQTT | Kafka |
| ---------------------------------- | --------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Drop-in level** | client-swap | client-swap / endpoint | endpoint-only | endpoint / client | endpoint-only | endpoint-only | endpoint-only⁴ | endpoint-only⁵ | endpoint-only |
| **Point-to-point queues** | ✅ | ✅ | ✅ | ✅ | ✅ SQS | ✅ | N/A | ✅ `queues/*` | N/A (topic/partition model) |
| **Pub/sub (non-durable)** | ✅ | ✅ | ✅ exchanges | ✅ | ✅ SNS | ✅ | ✅ topic→Events Store | ✅ `events/*`, `store/*` | ✅ native produce/consume |
| **Durable / persistent subs** | ✅¹ | ✅¹ | ✅ durable queues | ✅¹ | ✅ (SQS durable) | ✅ groups + replay | ✅ sub→Queue | ⚠️ `store/*` new-only (no replay) | ✅ committed offsets (consumer groups) |
| **Request / reply (RPC)** | ✅ | ✅² | ✅ Direct Reply-To | ✅ | N/A (no RPC) | ✅ reply-to | N/A | ✅ (v5 only) | N/A (no protocol-level RPC) |
| **Ordering guarantee** | ⚠️ node-local | ⚠️ node-local | ✅ per-queue³ | ⚠️ node-local | ✅ FIFO | ⚠️ | ⚠️ keys node-local | ⚠️ QoS-dependent | ✅ per-partition |
| **Transactions** | ❌ | ❌ | ❌ (use confirms) | ❌ | N/A | ❌ (rejected) | N/A | N/A | ✅⁷ EOS V1 wire |
| **Dead-letter / redrive** | ❌ no client DLQ⁶ | ❌ no client DLQ⁶ | ✅ DLX + `x-death` | ❌ no client DLQ⁶ | ✅ redrive + move-task | ❌ no client DLQ⁶ | ✅ dead-letter topic | ❌ no client DLQ⁶ | N/A (no protocol-level DLQ) |
| **Selectors / filter / wildcards** | ✅ selectors (SQL92 subset) | ✅ (AMQP 1.0) / ❌ (STOMP) | ✅ topic/headers routing | ✅ selectors (SQL92 subset) | ✅ SNS filter policies | ❌ no selectors | ✅ CEL-subset filter | ⚠️ wildcards Events-only | N/A (no broker-side filter) |
| **Auth model** | PLAIN(JWT)/EXTERNAL | PLAIN(JWT) | SASL PLAIN(JWT) | PLAIN/EXTERNAL | SigV4 / accept-any | JWT (CONNECT) | ❌ none (emulator) | JWT (password) | SASL PLAIN/SCRAM/OAUTHBEARER + mTLS |
| **TLS / mTLS** | ✅ 5671 | ✅ | ✅ 5671 | ✅ 5671 | ❌ connector (proxy) | ✅ 61614 | ❌ none (emulator) | ✅ 8883 / wss 8083 | ✅ 9093 |
| **Top unsupported** | JMS transactions/XA; durable-unsub node-local | OpenWire protocol; transactions; selectors on STOMP path | `tx.*`; e2e bindings; immediate; recover-async; update-secret; inert: alt-exchange, max-length, x-expires | transactions; durable-unsub node-local | SNS email/SMS/Lambda/push; queue/topic IAM policies; TLS at connector | transactions; selectors | no auth/TLS; IAM stubs; BigQuery/GCS export subs; ordering/exactly-once node-local; no 24h default retention | MQTT 3.1; retained messages; clients-as-responders; wildcards on non-Events; node-local sessions | >256 partitions; RF>1; KIP-848 next-gen groups; Kerberos/GSSAPI; delegation tokens; horizontal write scale |
**Footnotes:**
¹ Durable subscription via Events Store; `unsubscribe()` is node-local (the unsubscribe
only takes effect on the node that owns the durable subscription).
² ActiveMQ RPC via the AMQP 1.0 (Qpid JMS) path.
³ Requeued messages re-enter at the queue **tail** — this is a deviation from RabbitMQ
classic queues, which preserve near-head position.
⁴ Set `PUBSUB_EMULATOR_HOST=host:8085`; no credentials required.
⁵ MQTT **3.1 clients are rejected** at CONNECT; use MQTT 3.1.1 (Paho default) or 5.0.
⁶ No client-settable dead-letter queue over this protocol. The AMQP 1.0, STOMP, and MQTT
connectors never set a redrive target on published messages, so a poison message
exceeding `MaxReceiveCount` is silently dropped by the broker — it is not delivered to any
consumable dead-letter address. Genuine client-facing DLQ exists only for:
* **RabbitMQ** — DLX, sets a broker redrive target.
* **AWS** — redrive policy, also sets a broker redrive target.
* **GCP** — dead-letters at the connector level by re-publishing to the configured
dead-letter topic (new message IDs), not via a broker redrive target.
⁷ Kafka transactions / exactly-once semantics (V1 wire surface) are supported at proof-tier
T2 — safe for at-least-once delivery plus basic exactly-once semantics — but this is **not**
a KIP-890 soundness guarantee. See the [fitness matrix](/connectors/kafka/reference/fitness-matrix)
for the full tier breakdown.
## Drop-In Levels [#drop-in-levels]
Each guide states its **drop-in level** — how much application change the migration
requires:
* **endpoint-only** — change the host/port or set an environment variable; your existing
client library and code are unchanged.
* **client-swap** — swap the client library (for example, switch your JMS
`ConnectionFactory` to Apache Qpid JMS); application code remains mostly unchanged.
* **partial-rewrite** — some application-level changes are required beyond the client and
the endpoint.
A guide may list a **composite** level (for example `endpoint / client`) when the level
depends on the client type — the lower level covers simple publish/consume, and the higher
level applies only where a specific feature needs it.
## Before You Start [#before-you-start]
Every guide's smoke test assumes a running KubeMQ instance with the relevant connector
turned on. All seven wire-protocol connectors are **opt-in (disabled by default)** — a stock
server does not bind their listeners until you enable them. Enable a connector by setting
its `CONNECTORS__ENABLE` environment variable to `true` and publishing its port. For
example, to bring up a throwaway local server with the AMQP 1.0 connector enabled:
Each guide lists the **exact enable variable and ports for its connector** (the MQTT
variable is the irregular `CONNECTORSMQTT_ENABLE`, with no underscore). To turn a connector
back off, set the same variable to `false`. No live-broker validation is required to
adopt a guide — the smoke test is for your own verification after deployment.
## Guides [#guides]
The drop-in level in each row tells you, at a glance, how much application change to
expect.
| Guide | Drop-in | One-line summary |
| ------------------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Migrating from JMS](/connectors/how-to/migration/from-jms) | client-swap | Swap the JMS `ConnectionFactory` to Apache Qpid JMS over AMQP 1.0; application code is unchanged if you avoid transactions / XA. |
| [Migrating from ActiveMQ](/connectors/how-to/migration/from-activemq) | client-swap / endpoint | Java/JMS apps via Qpid JMS; non-Java apps via STOMP or MQTT by endpoint; OpenWire is not supported. |
| [Migrating from RabbitMQ](/connectors/rabbitmq/reference/migration-from-rabbitmq) | endpoint-only | Host-swap the AMQP 0-9-1 URI; exchanges, bindings, DLX, and publisher confirms work; `tx.*` does not. |
| [Migrating from AMQP 1.0](/connectors/how-to/migration/from-amqp-1-0) | endpoint / client | Point a native AMQP 1.0 client at KubeMQ; queues, topics, durable subs, and RPC all map; no transactions. |
| [Migrating from AWS SQS/SNS](/connectors/aws/reference/migration-from-aws) | endpoint-only | Override the AWS SDK endpoint to KubeMQ; SQS, SNS, FIFO, and DLQ migrate; email/SMS/Lambda do not. |
| [Migrating from STOMP](/connectors/stomp/scenarios/migration-from-stomp) | endpoint-only | Change the STOMP broker host; all destination types map; no transactions or selectors. |
| [Migrating from Google Cloud Pub/Sub](/connectors/gcp-pub-sub/reference/migration-from-gcp) | endpoint-only | Set `PUBSUB_EMULATOR_HOST`; topics and subscriptions map; no auth/TLS; ordering is node-local. |
| [Migrating from MQTT](/connectors/mqtt/scenarios/migration) | endpoint-only | Change the MQTT broker host; 3.1.1 and 5.0 only; retained messages and MQTT 3.1 are not supported. |
| [Migrating from Kafka](/connectors/kafka/how-to/migrate-from-kafka) | endpoint-only | Repoint `bootstrap.servers`; native clients connect unchanged. Assess fit with `kmq assess kafka`, then move existing topics + consumer-group offsets with the beta `kmq migrate` tool; runs on the `next` storage engine. |