skip to content

A topic's effective config value can come from several sources. What is the full precedence order Kafka uses to resolve a dynamic config, and how would you diagnose an unexpected effective value?

level: principalimportance: should knowfreq 30%

answer

  1. topic dyn > per-broker dyn > cluster-default dyn > static > default
  2. first source that defines key wins
  3. synonyms list = full chain
  4. describe --all shows inherited + source
  5. delete to fall through, don't set equal

basics

~20 s

Order, highest to lowest: per-topic dynamic override, then per-broker dynamic config, then cluster-wide dynamic default broker config, then static broker config (server.properties), then the built-in default. To diagnose, describe the topic and read each entry's source tag.

solid answer

~40 s

Kafka resolves an effective config by walking sources from most to least specific: (1) DYNAMIC_TOPIC_CONFIG — explicit per-topic override; (2) DYNAMIC_BROKER_CONFIG — a dynamic config set on the specific broker; (3) DYNAMIC_DEFAULT_BROKER_CONFIG — a cluster-wide dynamic default applied to all brokers; (4) STATIC_BROKER_CONFIG — value from server.properties read at startup; (5) DEFAULT_CONFIG — the code-level built-in default. The first source that defines the key wins. To diagnose an unexpected effective value, run kafka-configs.sh --describe (or AdminClient.describeConfigs with the config synonyms) which reports the winning value plus the ordered list of synonyms showing every level that defines it and which one is in effect. This makes drift — e.g. a stale per-topic override masking a corrected broker default — immediately visible. Remember that deleting a higher-precedence override is what lets a lower source take effect.

go deeper

for a junior

Know that a topic override beats the broker default; deeper precedence is advanced.

for a middle

Recall the topic-vs-broker ordering and that describe shows a source tag.

for a senior

List the dynamic-broker / cluster-default / static / default chain and use synonyms to diagnose.

for a principal

Teach the full resolution model, design drift detection across brokers/topics, and codify which level owns each setting.

## Why precedence matters The same logical setting (say log retention) can be defined at multiple scopes simultaneously. The **effective value** a topic actually uses is whichever the precedence chain resolves to. Misunderstanding the chain leads to changes that 'don't take' because a higher-precedence source still wins. ## The full precedence order (highest wins) 1. **DYNAMIC_TOPIC_CONFIG** — an explicit override on this topic (set via kafka-configs.sh --entity-type topics or incrementalAlterConfigs on a TOPIC ConfigResource). Most specific, always wins if present. 2. **DYNAMIC_BROKER_CONFIG** — a dynamic config set on a *specific* broker id (--entity-type brokers --entity-name <id>). 3. **DYNAMIC_DEFAULT_BROKER_CONFIG** — a *cluster-wide* dynamic default applied to all brokers (--entity-type brokers --entity-default). Lower than a per-broker dynamic value. 4. **STATIC_BROKER_CONFIG** — value loaded from server.properties at broker startup. 5. **DEFAULT_CONFIG** — the hard-coded built-in default shipped with Kafka. The first level that defines the key supplies the effective value; everything below is shadowed. ## How config synonyms expose this When you `describeConfigs`, each `ConfigEntry` carries: - `value()` — the winning effective value. - `source()` — the source tag of the winner. - `synonyms()` — an **ordered list** of every level that defines the key, top to bottom. The first synonym is the effective one. So a single describe shows you the entire resolution chain. CLI: ``` kafka-configs.sh --bootstrap-server b:9092 --describe \ --entity-type topics --entity-name orders --all ``` The `--all` flag prints inherited values and their sources too, not just explicit overrides. ## Diagnosing an unexpected effective value Scenario: you raised the broker default `log.retention.ms` but topic `orders` still expires data early. 1. Describe `orders` with `--all`. 2. Look at `retention.ms`: if its source is `DYNAMIC_TOPIC_CONFIG`, a stale per-topic override is masking your broker change. 3. The synonyms list confirms both the topic override (winner) and the broker default (shadowed). 4. Fix: `--delete-config retention.ms` on the topic so it falls through to the broker default. Another scenario: a per-broker dynamic value (level 2) on one broker shadows the cluster-wide default (level 3), causing one broker to behave differently — describe that broker's configs to spot it. ## Operational implications - **Reverting** any level means *deleting* its entry, not setting it equal to a lower level — setting it pins it at that level. - Static vs dynamic: STATIC_BROKER_CONFIG requires editing server.properties + restart; the dynamic levels are runtime-changeable. - Governance: track which keys are managed at cluster-default level vs left as per-topic exceptions; per-topic overrides are the most common source of silent drift. ## Edge cases - Sensitive values render as null but their source still appears. - Some configs are read-only (no dynamic levels apply); their only sources are STATIC_BROKER_CONFIG and DEFAULT_CONFIG. - A per-broker dynamic value affects only that broker, so a topic's partitions on different brokers could in principle see different effective broker-level values — another drift source.

  • You raised the broker default retention but one topic still expires early — how do you find why?
    Describe the topic with --all and check retention.ms's source; a DYNAMIC_TOPIC_CONFIG override is shadowing the broker default. Delete the override to let it inherit.
  • What's the difference between DYNAMIC_BROKER_CONFIG and DYNAMIC_DEFAULT_BROKER_CONFIG?
    The former is set on a specific broker id and takes precedence; the latter is a cluster-wide dynamic default applied to all brokers and sits one level lower in precedence.
  • Why can the same config differ between two brokers in a cluster?
    A per-broker dynamic config (or static server.properties value) set on only one broker shadows the cluster-wide default there, so that broker resolves a different effective value.

saying these in an interview costs you the question

  • Putting static broker config above dynamic configs (dynamic wins)
  • Saying per-topic and broker overrides 'merge' — the highest-precedence source wins outright
  • Claiming describe only shows explicit overrides (--all shows inherited + synonyms)
  • Thinking setting a value equal to the lower level reverts it (you must delete the higher entry)

context

resolving links…