# Replace Kafka with KubeMQ (/deploy/scenarios/replace/replace-kafka)



<Callout type="info">
  You need a license key to start KubeMQ — it's free, about 2-3 minutes (it includes creating a free account). 

  [Get one](/deploy/license-key)

  . Step 1 below starts the broker with the connector enabled.
</Callout>

Your Kafka client keeps its library, its code, and the real Kafka wire protocol — only
`bootstrap.servers` changes, from your Kafka cluster to a local KubeMQ server.

**Drop-in level:** endpoint-only ([legend](/deploy/scenarios/replace#drop-in-levels))

## 1 · Enable the connector [#1--enable-the-connector]

The Kafka connector is disabled by default — enable it and publish its ports:

<RunKubeMQ ports="[9092, 9093, 50000]" env="{ CONNECTORS_KAFKA_ENABLE: 'true' }" />

## 2 · Point your client at KubeMQ [#2--point-your-client-at-kubemq]

```text title="bootstrap.servers"
# Before (Kafka)
bootstrap.servers=your-kafka-cluster.example.com:9092

# After (KubeMQ)
bootstrap.servers=localhost:9092
```

Same client library, same producer/consumer code — only the seed broker address moves.

## 3 · Smoke test [#3--smoke-test]

Produce and consume one record with `kcat` (the librdkafka CLI needs no client code at all):

```bash title="produce"
echo "hello kubemq" | kcat -b localhost:9092 -t orders -P
```

```bash title="consume"
kcat -b localhost:9092 -G orders-group -o beginning -c 1 orders
```

`-o beginning` reads from the start of the topic, so a brand-new consumer group still
sees the record you just produced (without it, a fresh group starts at the latest offset
and the consumer would block waiting for the next message).

The producer is silent on success; the consumer prints the record body (kcat also
logs consumer-group rebalance lines to stderr). You should see:

```text
hello kubemq
```

This is the same round-trip as [Getting Started](/connectors/kafka/tutorials/getting-started),
which also covers the same produce/consume flow in Go, Python, Java, JavaScript, C#, Ruby,
and Rust — no `kcat` required.

## What carries over — and what doesn't [#what-carries-over--and-what-doesnt]

Your client library, code, topic and consumer-group names, and produce/consume semantics all
carry over unchanged — only the broker address moves. Bringing an *existing* cluster's topic
history and consumer offsets across (rather than starting fresh) is a separate step covered
by the migration guide's `kmq migrate` tool.

<Cards>
  <Card title="Getting Started" href="/connectors/kafka/tutorials/getting-started" description="The full produce/consume round-trip across kcat and seven client libraries, plus how topics and partitions map to storage." />

  <Card title="Migrate from Kafka" href="/connectors/kafka/how-to/migrate-from-kafka" description="Assess fit, then move an existing cluster's topic history and consumer-group offsets onto KubeMQ." />
</Cards>

## Didn't work? [#didnt-work]

<Callout type="warn">
  * **Wrong port** — confirm `9092` (plain) or `9093` (TLS) is published and matches
    `bootstrap.servers`.
  * **Connector not enabled** — a stock server doesn't bind the Kafka listener until
    `CONNECTORS_KAFKA_ENABLE=true` is set.
  * **Auth mismatch** — if you enabled authentication, confirm your client's SASL/JWT
    credentials match.
</Callout>