skip to content

What is directory.id in a dynamic KRaft quorum and why does each voter need one?

level: middleimportance: should knowfreq 35%

answer

  1. UUID for the metadata log directory
  2. stored in meta.properties at format time
  3. voter identity = (node id, directory.id)
  4. guards node-id reuse / disk-wipe rejoin
  5. AddRaftVoter carries it

basics

~20 s

directory.id is a UUID identifying a controller's metadata log directory. It uniquely tags each voter so the quorum can tell apart a node that was wiped and rejoined from the original, preventing a stale replica from being mistaken for a current voter.

solid answer

~40 s

directory.id is a per-replica UUID generated at storage format time and stored in the metadata log directory's meta.properties. In a dynamic quorum a voter is identified by the pair (node id, directory.id), not node id alone. This matters because node ids can be reused — if a controller's disk is lost and reformatted, it gets a new directory.id even with the same id and endpoint. The quorum treats that as a different voter, so it cannot silently pretend to have the old replica's committed log. AddRaftVoter therefore takes both the id and the directory.id; the new voter must be in the cluster's voter set with a matching directory.id to vote. This guards against data-loss scenarios where a wiped node rejoins and could otherwise be counted toward a majority it doesn't actually have.

go deeper

for a junior

Recall that directory.id is a UUID that uniquely identifies a controller's log directory.

for a middle

Explain voter identity as (node id, directory.id) and why node-id reuse needs it.

for a senior

Tie it to Raft safety: preventing a log-less reformatted node from being counted toward a majority.

for a principal

Reason about disk-failure runbooks, JBOD/metadata-dir placement, and the data-loss class this prevents.

## What it is `directory.id` is a **UUID** (e.g. `AbCd...` 22-char base64) that uniquely identifies the **metadata log directory** of a KRaft replica. It is generated when you run `kafka-storage format` and is persisted in that directory's `meta.properties` file. You can read it with `kafka-metadata-quorum describe --status` or by inspecting `meta.properties`. ## Why a node id isn't enough In Raft, safety depends on never counting a replica toward a majority unless it genuinely holds the committed log. KRaft node ids (`node.id`) are operator-assigned integers and **can be reused** — operators commonly reprovision a controller with the same id and endpoint after a disk failure. If identity were node-id-only, a freshly wiped controller (empty log) reusing id `3` could be mistaken for the original voter `3` that held committed entries. It might then participate in elections or be counted in a quorum it has no right to be in, risking **loss of committed metadata** or split-brain. By binding voter identity to `(node id, directory.id)`, a reformatted disk gets a **new** `directory.id`, so the quorum sees it as a genuinely new, log-less replica that must be explicitly re-added and must catch up before counting. ## How it flows through reconfiguration - `AddRaftVoter` carries the new voter's **node id, directory.id, and endpoints**. The `kafka-metadata-quorum add-controller` command reads the joining node's directory.id from its meta.properties. - The voter set stored in the log (`VotersRecord`) records each voter's directory.id. - When a controller starts, it compares its on-disk directory.id against what the voter set expects; a mismatch means it is not (yet) a recognized voter. ## Edge cases - **Disk replacement with same id:** new directory.id ⇒ you must remove the old voter entry and add the new one; you cannot just restart. - **JBOD / multiple metadata dirs:** the metadata log lives in one directory; that directory's id is the voter's directory.id. - **Static mode:** directory.id exists on disk but is not used for dynamic membership identity, since membership is fixed in config. ## Summary directory.id is the mechanism that makes node-id reuse safe under dynamic reconfiguration: it gives every replica's log a durable, unique fingerprint so the quorum never confuses a wiped node for the voter it replaced.

  • Where is directory.id stored and when is it generated?
    It is generated by kafka-storage format and persisted in the metadata log directory's meta.properties file.
  • What must an operator do if a controller's disk is lost and reformatted with the same node id?
    The reformatted node gets a new directory.id, so the operator must remove-controller the old voter entry and add-controller the new (id, directory.id) — a plain restart won't make it a recognized voter.

saying these in an interview costs you the question

  • Saying directory.id and node.id are the same thing or interchangeable.
  • Claiming a wiped controller can rejoin a dynamic quorum just by reusing its old node id.
  • Thinking directory.id is random per-restart — it is stable for the life of the log directory.

context

resolving links…