Where does KRaft store the cluster metadata on disk, and what is the on-disk layout of the __cluster_metadata log directory?

## What metadata is Cluster metadata is the catalog of the cluster: topic and partition definitions, broker registrations, ACLs, configs, and controller/leader assignments. In ZooKeeper-based Kafka this lived in ZooKeeper znodes. In **KRaft** it lives in a Kafka topic that Kafka manages itself. ## The __cluster_metadata topic KRaft introduces an internal topic named **`__cluster_metadata`** with **exactly one partition**, so on disk you see the directory **`__cluster_metadata-0`**. This single partition is replicated not by ordinary ISR replication but by a **Raft** consensus protocol across the **controller quorum** (the nodes with `controller` in `process.roles`). One controller is the **active controller** (Raft leader); it appends metadata records, and followers replicate them. Every metadata change (create topic, register broker, change config) is a record appended to this log. ## On-disk layout `__cluster_metadata-0` is a normal Kafka **log directory**, so it contains: - **`*.log`** — segment files holding the actual metadata records (named by their base offset, e.g. `00000000000000000000.log`). - **`*.index`** and **`*.timeindex`** — offset and time indexes for each segment. - **`leader-epoch-checkpoint`** — maps leader epochs to start offsets. - **`partition.metadata`** — records the topic id. Plus KRaft/Raft-specific files in the directory: - **`quorum-state`** — the persisted Raft state: current leader id, current epoch, and who this node voted for. This survives restarts so a node doesn't forget its vote and break the consensus safety guarantees. - **`*.checkpoint`** snapshot files — point-in-time **snapshots** of the materialized metadata state at a given offset/epoch (named like `<offset>-<epoch>.checkpoint`). ## Where it lives By default the metadata partition is placed in the **first directory** of `log.dirs`. The config **`metadata.log.dir`** overrides this so you can put metadata on a dedicated disk — common in production to isolate metadata I/O from data I/O and to use faster storage for low-latency consensus. ## Why snapshots matter A Raft log is append-only; replaying every record since cluster creation would be slow and the log would grow without bound. KRaft periodically writes a **snapshot** capturing the full materialized state at offset N, then can delete log segments before N. A restarting controller or a broker catching up loads the **latest snapshot** and then replays only the tail of the log after it. This bounds recovery time and disk usage. ## Brokers vs controllers - **Controllers** hold the authoritative Raft replica and run the quorum. - **Brokers** are observers: they fetch the metadata log and build a local materialized copy (and their own `__cluster_metadata-0` replica on disk) so each broker has the current cluster state without querying a controller for every decision. ## Edge cases - Corruption or deletion of `quorum-state` can make a node lose its Raft identity; recovery may require re-bootstrapping from the quorum. - Because there's only one partition, metadata throughput is bounded by a single Raft log — fine because metadata events are comparatively low-rate.