Running Kafka in KRaft Mode with Docker Compose
Running Kafka in KRaft mode with Docker Compose takes one service and a handful of environment variables. The official apache/kafka image runs KRaft out of the box — no ZooKeeper container, no migration steps, and docker run -p 9092:9092 apache/kafka:4.3.1 alone gives you a working broker. A short Compose file makes that broker reproducible, and a slightly longer one gives you a 3-controller, 3-broker cluster that mirrors production topology.
This post walks through both files, the env-var conventions behind them, and how to keep data across restarts. For what KRaft mode actually is, see our KRaft guide.
Use apache/kafka (JVM) for everyday work and apache/kafka-native (GraalVM, sub-second startup) for integration tests. Configure through KAFKA_* environment variables — but the moment you override anything, the image's defaults vanish and you own the full config. Pin CLUSTER_ID and mount a volume on the log directory if data should survive docker compose down.
The fastest KRaft container: docker run
One command starts a combined-mode node — a single process acting as both broker and controller — with a client listener on localhost:9092:
docker pull apache/kafka:4.3.1
docker run -p 9092:9092 apache/kafka:4.3.1
Two official images exist, and the version history matters. Kafka 3.7.0 shipped apache/kafka (KIP-975): a JVM image on a slim JRE base, published for linux/amd64 and linux/arm64. Kafka 3.8.0 added apache/kafka-native (KIP-974): the broker compiled ahead-of-time to a native binary with GraalVM. The native image starts in under a second, which is excellent for integration tests and CI — but the project recommends it for development and testing only, not production.
The image bundles the full CLI under /opt/kafka/bin, so you can smoke-test without installing anything on the host:
docker exec --workdir /opt/kafka/bin/ -it <container> sh
./kafka-topics.sh --bootstrap-server localhost:9092 \
--create --topic smoke-test --partitions 1 --replication-factor 1
How the apache/kafka image configures KRaft
The image reads any Kafka server property from an environment variable. The naming convention: prefix with KAFKA_, replace . with _, _ with __, and - with ___. So process.roles becomes KAFKA_PROCESS_ROLES, and controller.quorum.voters becomes KAFKA_CONTROLLER_QUORUM_VOTERS.
Precedence runs in three layers. Environment variables win over a property file you mount at /mnt/shared/config, which in turn replaces the defaults baked into the image.
One caveat catches almost everyone. The defaults are all-or-nothing: the moment you override any property, none of the built-in configuration applies, and you must supply a complete working config — listeners, quorum voters, the lot. This is why a bare docker run works with zero variables, then "just adding one setting" in Compose breaks startup.
The container also formats its own storage. On a bare-metal host you generate a cluster ID and run kafka-storage.sh format before first boot — the flow our Kafka without ZooKeeper post walks through. The image does the equivalent at startup, driven by the CLUSTER_ID environment variable.