skip to content

When setting a dynamic broker config, what is the difference between --entity-name <id> and --entity-default, and when would you use each?

level: middleimportance: should knowfreq 40%

answer

  1. --entity-name <id> = one broker (DYNAMIC_BROKER_CONFIG)
  2. --entity-default = all brokers (DYNAMIC_DEFAULT_BROKER_CONFIG)
  3. per-broker beats cluster default
  4. canary on one broker, then default everywhere
  5. sensitive/SSL configs are per-broker

basics

~10 s

--entity-name <brokerId> sets a per-broker config that applies to just that broker. --entity-default sets a cluster-wide default applied to all brokers. Per-broker overrides the cluster default for that broker.

solid answer

~40 s

With --entity-type brokers, --entity-name <id> targets one specific broker, persisting a per-broker dynamic config (ConfigSource DYNAMIC_BROKER_CONFIG) that overrides everything else for that broker. --entity-default (no id) sets a cluster-wide dynamic default (DYNAMIC_DEFAULT_BROKER_CONFIG) that every broker uses unless it has its own per-broker override. Use --entity-default for a fleet-wide tuning change you want everywhere — e.g. raise num.replica.fetchers or log.cleaner.threads across the cluster in one command. Use --entity-name when one broker needs something different: different SSL keystore paths/passwords (which are per-broker by nature), heterogeneous hardware needing more fetcher threads, or a canary change on a single broker before rolling it out cluster-wide. Sensitive configs are normally per-broker because each broker encrypts them with its own static password.encoder.secret.

go deeper

for a junior

Know --entity-name targets one broker and --entity-default targets all of them.

for a middle

Explain the precedence between the two and pick the right scope for a change.

for a senior

Design a canary-then-cluster-default rollout and reason about override cleanup.

for a principal

Set fleet config-management policy: defaults for uniformity, per-broker only for genuine heterogeneity/secrets.

## Two scopes for dynamic broker configs When you run `kafka-configs --entity-type brokers`, you choose **who** the config applies to: ### Per-broker: --entity-name <id> ``` kafka-configs.sh --bootstrap-server b:9092 \ --entity-type brokers --entity-name 2 \ --alter --add-config num.replica.fetchers=8 ``` Applies to **broker 2 only**. Stored as `DYNAMIC_BROKER_CONFIG`. This is the most specific dynamic source and overrides the cluster default and the file for that broker. ### Cluster-wide default: --entity-default ``` kafka-configs.sh --bootstrap-server b:9092 \ --entity-type brokers --entity-default \ --alter --add-config num.replica.fetchers=4 ``` Applies to **every broker** that lacks a per-broker override. Stored as `DYNAMIC_DEFAULT_BROKER_CONFIG`. ## How they interact (precedence) For a given key on a given broker: per-broker (`--entity-name`) > cluster default (`--entity-default`) > `server.properties` > built-in. So a broker with its own value ignores the cluster default; brokers without one follow the cluster default. ## When to use which **Use --entity-default when:** - You want a uniform tuning change everywhere (fetcher threads, cleaner threads, default retention) in a single command. - You want new/replacement brokers to inherit the value automatically. **Use --entity-name when:** - A config is inherently per-broker: SSL keystore location/passwords differ per host. - Hardware is heterogeneous (one broker has more cores/disks and needs more threads). - You're canarying: apply to one broker, observe metrics, then promote to `--entity-default`. - Sensitive configs: each broker encrypts with its own static `password.encoder.secret`, so they are set per-broker. ## Operational pattern A common safe rollout is: set per-broker on a canary, validate, then set `--entity-default` cluster-wide and delete the per-broker override (so the broker falls back to the now-correct default). ## Edge cases - Deleting a per-broker override makes that broker fall to the cluster default (if any), then file, then built-in — not directly to the file. - Read-only configs cannot be set by either scope; they need a restart with `server.properties` changes. - `--entity-default` does not retroactively remove existing per-broker overrides; those still win until deleted.

  • You set a cluster default but one broker still shows the old value. Why?
    That broker likely has a per-broker override (DYNAMIC_BROKER_CONFIG), which outranks the cluster default. Delete the per-broker override for it to inherit the default.
  • Why are SSL keystore passwords typically set per-broker rather than cluster-wide?
    Each broker may have different keystore paths/passwords, and sensitive values are encrypted with that broker's own static password.encoder.secret, so they are applied per-broker.

saying these in an interview costs you the question

  • Thinking --entity-default overrides existing per-broker values — per-broker still wins until deleted.
  • Assuming sensitive/SSL configs can be set cluster-wide like a tuning knob.
  • Believing read-only configs can be set per-broker dynamically.

context

resolving links…