Monedula

Scenario 10.2.2 · Mirror topics are read-only; promotion makes them writable

Kafka mirror topics (Confluent): read-only until promoted

Disaster recovery · Advanced · about 4 min · Apache Kafka 4.3

A cluster-link destination is a READ-ONLY mirror - only the link writes it - until promote_mirror flips it to a normal writable topic and stops mirroring that topic (the link stays up for other mirror topics), after which a local producer can append.

Run this scenario in the playground

Local producer appends. t+1.600s

Because promotion made primary.orders writable, the dr-local producer p-dr appends a new record (D1) directly to it - HW advances to 4, past the mirrored tail. This local write was impossible while the topic was a read-only mirror; only promotion enabled it.

Open at this step: step 4, Local producer appends

What you start with

A Cluster Linking destination starts as a read-only mirror topic: only the link itself may write to it, so local producers are rejected. Calling promote_mirror flips it to a normal writable topic and stops mirroring that topic (the link stays up for other mirror topics), after which a local producer can append.

Step by step

  1. Read-only mirror stands up t+0.000s A cluster link from primary→dr creates the destination primary.orders as a READ-ONLY mirror (mirrorState 'mirror', partitions flagged mirrored). Clients cannot produce to it - only the link writes it. The source orders topic in primary is the writable one. Open at this step: step 1, Read-only mirror stands up
  2. Link mirrors orders read-only t+0.700s Three records produced to the SOURCE orders are mirrored byte-for-byte into primary.orders by the link (each mirror step emits cross_region_replicate). Destination HW == source HW = 3. The destination is still a read-only mirror - its only writer is the cluster link. Open at this step: step 2, Link mirrors orders read-only
  3. promote_mirror → writable t+1.300s promote_mirror flips primary.orders mirrorState 'mirror' → 'promoted' and clears the read-only mirrored flags - it is now an ordinary writable topic - and stops mirroring that topic. The simulator removes the link, which carried only this topic; a real cluster link stays up for its other mirror topics. A mirror_promoted event records the transition (drives replay). Open at this step: step 3, promote_mirror → writable
  4. Local producer appends t+1.600s Because promotion made primary.orders writable, the dr-local producer p-dr appends a new record (D1) directly to it - HW advances to 4, past the mirrored tail. This local write was impossible while the topic was a read-only mirror; only promotion enabled it. Open at this step: step 4, Local producer appends

The takeaway

Promotion is the deliberate one-way cutover step in Cluster Linking - it turns a passive mirror into the new source of truth. Confluent's promote needs the source reachable and zero lag, so it suits a planned cutover; in a disaster with the source gone you run failover instead.

Embed this scenario

Paste this into a blog post, a course page or your team's docs. The scenario plays inside your page, and the link under it points readers to this walkthrough.

<iframe src="https://monedula.dev/kafka-simulator/embed/?scenario=10.2.2" title="Kafka Simulator: Mirror topics are read-only; promotion makes them writable" width="100%" height="520" style="border:1px solid #d0d0d0;border-radius:8px" loading="lazy"></iframe>
<p><a href="https://monedula.dev/kafka-simulator/scenarios/mirror-read-only-promote-writable/">Kafka mirror topics (Confluent): read-only until promoted</a></p>

Further reading

Confluent documentation

More in Disaster recovery

All scenarios