Page History

...

• UNKNOWN: The partition has no cached state (broker just became leader, state not loaded yet). Not an explicit API-driven state, just the absence of state.
• PREPARING: The coordinator for this partition detects via onMetadataUpdate that it leads a mirror partition. It fetches last mirrored epochs from the source cluster and truncates logs to align the local log with the source.Valid from: UNKNOWN, MIRRORING, STOPPED.
• MIRRORING: All ISR set members have completed truncation. A mirror fetcher thread is started to continuously replicate records from the source cluster. Valid from: PREPARING, PAUSED.
• PAUSING: Triggered by the pause operation. The system removes fetchers for the affected partitions. Valid from: MIRRORING only.
• PAUSED: Fetchers have been removed. The partition stays read-only with no active fetchers and no metadata sync (configs, consumer groups, ACLs). On resume, transitions directly to MIRRORING. Valid from: PAUSING only.
• STOPPING: Triggered by the remove topics from mirror operation or topic deletion on the source. The system stores the last mirrored epoch to Performs the following actions.
  1. Remove mirror fetcher threads: Stops cross-cluster replication for the affected partitions.
  2. In parallel:
     1. Bump leader epoch (async): Sends a BumpLeaderEpochsRequest to the controller with the latest local log epoch as minLeaderEpoch, ensuring the destination leader epoch exceeds the source cluster's last known epoch.

     2. Truncate to LSO, then update LME: Truncates each partition's log to LSO, discarding any uncommitted tail, then persists the latest leader epoch from each partition's log into the __mirror_state

  topic and bumps the leader epoch. Valid from: MIRRORING, PAUSED

  1. 1. coordinator topic, recording LME for future failback.

  2. Write PID reset barrier: Once both parallel branches complete, appends a MIRROR_PID_RESET control record to each partition, fencing stale producer IDs from the source cluster.
• STOPPED: The last mirrored epoch have been persisted. The topic becomes writable on the destination cluster. Tthe The mirror fetcher is removed and the read-only flag is cleared. Valid from: STOPPING only.
• FAILED: An error occurred. Valid from: any state. The operator that wants to restart a failed mirror partition can remove the topic from the mirror and add it back again. The STOPPING handler already removes fetchers and truncates to the LSO, both of which are safe operations on a failed partition (fetchers are likely already gone, and truncation is a best-effort cleanup). More sophisticated recovery strategies can be added later with a follow-up KIP.

...

• Starting a mirror (UNKNOWN -> PREPARING -> MIRRORING): The addTopicsToMirror command StartMirrorTopics command sets mirror.name config via the controller. The metadata update propagates to brokers. The broker leading the partition finds out the partition state via the coordinator, and this might trigger readMirrorState RPC to query from the remote coordinator responsible for handling that mirror partition, and transitions to PREPARING if it's in a valid transition state. After truncation completes, it moves to MIRRORING and starts the mirror fetcher to fetch data from the source cluster.
• Failing over to destination (MIRRORING -> STOPPING -> STOPPED): The removeTopicsFromMirror command StopMirrorTopics command appends the ".removed” suffix to the mirror.name config. The partition leader  detects the stop request, transitions to STOPPING, truncates to LSO, persists the last mirrored epoch, then moves to STOPPED. The topic is now writable after the STOPPED state.
• Restarting a stopped mirror (STOPPED -> PREPARING -> MIRRORING): The mirror.name config is set again. The controller is notified, sees the partition in STOPPED state and transitions to PREPARING, re-truncating and resuming replication.

...

...

Failover is initiated by calling the RemoveTopicsFromMirror APIStopMirrorTopics API, which appends a ".removed" suffix to the mirror.name internal config. This transitions the mirror topics from read-only to writable state after the stopping process completes gracefully. When producers reconnect to the destination cluster after failover, they obtain new producer IDs which are separate from previously mirrored IDs, so they begin writing with fresh sequence numbers starting from 0. Consumers can reconnect to the destination cluster using the same group ID, resuming from the last synchronized offsets, minimizing data re-processing or gaps. The transition is transparent from the consumer's perspective and offset management continues normally through the destination's group coordinator.

...

...

• CLI Workflow: Create mirror with kafka-mirrors.sh, add topicsstart mirroring, verify replicationlog convergence
• Basic Replication: Create mirror via API, replicate topicstart mirroring, verify data consistencylog convergence
• Metadata Sync: Modify topic config in source, verify automatic sync to destination
• Partition Expansion: Add partitions to source topic, verify destination expands
• Consumer Groups: Commit offsets in source, verify replication to destination
• ACL Replication: Create ACL in source, verify creation in destination
• Leader Changes: Trigger leader election in source, verify fetcher reconnects
• Broker Failures: Stop destination broker, verify replication continues after recovery

...