skip to content

How do you create and inspect a Kafka topic from the command line, and what do the key options control?

level: juniorimportance: must knowfreq 80%

answer

  1. --bootstrap-server not --zookeeper
  2. --create / --describe / --list / --alter
  3. Leader / Replicas / Isr columns
  4. partitions = parallelism, RF = fault tolerance
  5. RF must be <= broker count

basics

~10 s

Use kafka-topics.sh with --bootstrap-server. To create: --create --topic name --partitions N --replication-factor R. To inspect: --describe --topic name, which shows partitions, leaders, replicas, and in-sync replicas (ISR).

solid answer

~40 s

The kafka-topics CLI is the primary tool for topic lifecycle. Creation: kafka-topics.sh --bootstrap-server host:9092 --create --topic orders --partitions 6 --replication-factor 3. Partitions set the unit of parallelism (one consumer per partition max within a group) and replication-factor sets fault tolerance (must be <= broker count). You can pass per-topic configs with --config, e.g. --config retention.ms=604800000 or cleanup.policy=compact. --describe --topic orders prints each partition's Leader (the broker serving reads/writes), Replicas (assigned broker IDs), and Isr (the in-sync replica set). A shrinking ISR or 'Leader: none' signals under-replication or offline partitions. --list shows all topics. In modern Kafka all of these talk to brokers via --bootstrap-server; the old --zookeeper flag is removed in KRaft clusters.

go deeper

for a junior

Know the create/describe/list commands and that --bootstrap-server points at a broker.

for a middle

Read --describe output: interpret Leader/Replicas/Isr and spot under-replicated partitions.

for a senior

Reason about partition sizing tradeoffs, RF vs min.insync.replicas, and config vs topic alter split.

for a principal

Set org-wide conventions for partition counts, RF policy, and incident runbooks using describe filters.

## What a topic is A Kafka **topic** is a named, append-only log of records. It is split into **partitions** — independent ordered logs that Kafka distributes across brokers. Partitions are why Kafka scales: producers write to many partitions in parallel, and within a **consumer group** at most one consumer reads each partition, so partition count caps a group's parallelism. Each partition is replicated for fault tolerance. **replication-factor = R** means R copies exist on R different brokers. One replica is the **leader** (handles all reads/writes); the rest are **followers** that fetch from the leader. The **ISR (in-sync replica set)** is the subset of replicas currently caught up to the leader. ## Creating a topic ``` kafka-topics.sh --bootstrap-server broker:9092 \ --create --topic orders \ --partitions 6 --replication-factor 3 \ --config retention.ms=604800000 \ --config cleanup.policy=delete ``` - `--partitions` — number of partitions. Increasing later is possible but **breaks key→partition ordering** for existing keys (the hash mapping changes), so size it up front. - `--replication-factor` — copies per partition; must be `<=` number of brokers, else creation fails. - `--config k=v` — per-topic overrides of broker defaults (retention, compaction, min.insync.replicas, etc.). ## Inspecting topics - `--list` — names of all topics. - `--describe --topic orders` — per-partition layout: ``` Topic: orders Partition: 0 Leader: 1 Replicas: 1,2,3 Isr: 1,2,3 ``` - **Leader** = broker serving that partition. `Leader: none` means no leader is available (partition offline). - **Replicas** = assigned broker IDs (preferred leader is listed first). - **Isr** = replicas in sync. If `Isr` is smaller than `Replicas`, the partition is **under-replicated** — a follower is lagging or its broker is down. - `--describe --under-replicated-partitions` / `--unavailable-partitions` filter to only problem partitions — the first thing to run during an incident. ## Altering and deleting - `--alter --topic orders --partitions 12` increases partition count (cannot decrease). - Topic *config* changes go through `kafka-configs.sh --alter --entity-type topics`, not `kafka-topics --alter` (which now only handles partition count). - `--delete --topic orders` marks it for deletion (requires `delete.topic.enable=true`, default true). ## Modern vs legacy All commands use `--bootstrap-server` to talk to brokers. The legacy `--zookeeper` flag is gone in KRaft-mode clusters; metadata now lives in the KRaft controller quorum, not ZooKeeper.

  • What does it mean when Isr is smaller than Replicas in --describe output?
    The partition is under-replicated: one or more follower replicas have fallen behind the leader (lagging beyond replica.lag.time.max.ms) or their broker is down. Durability is reduced; if min.insync.replicas can't be met, producers with acks=all start failing.
  • Can you reduce the partition count of an existing topic with --alter?
    No. Kafka only supports increasing partitions. Decreasing would require dropping data and reassigning keys, so it's not allowed — you must delete and recreate the topic (or create a new one and migrate).

saying these in an interview costs you the question

  • Saying you still need --zookeeper to manage topics (removed in KRaft).
  • Claiming you can decrease partitions with --alter.
  • Confusing Replicas (assigned) with Isr (currently in sync).
  • Thinking kafka-topics --alter changes topic configs like retention.ms (that's kafka-configs).

context

resolving links…