Bootstrapping a KRaft-mode Kafka cluster before any topic exists
Bootstrapping a new Kafka cluster means generating a cluster ID, formatting every controller and broker storage directory with that ID, and starting the controllers so they elect a leader and form a metadata quorum before any broker serves traffic. In KRaft mode the metadata that ZooKeeper once held lives inside Kafka itself, so there is no external coordination service to install, secure or back up. Kafka 4.0 supports only KRaft, and ZooKeeper mode has been removed. This page is for teams building a brand-new cluster on infrastructure they control. If you are moving an existing ZooKeeper-based cluster, the migration path in the upgrade notes applies first and this procedure does not replace it.
The Apache Kafka project is licensed under Apache-2.0 and has no paid edition, so the software you bootstrap is the same release the community publishes. The downloads page lists 4.3.1 (June 25, 2026), 4.2.2 (September 29, 2026) and 4.1.2 (March 17, 2026) as supported releases, and older versions are archived. Confirm the current list on the Kafka downloads page before you pin a version, because the project publishes new releases about every four months. Choose the release your rollout will run for its planned life, and confirm the Java runtime it requires, since brokers and tools need Java 17 from Kafka 4.0 onward.
Before you format anything, decide the controller count, the node IDs, the listener names and the directories that will hold metadata logs, and record them in a runbook. The cluster ID and the storage format are the steps most often repeated wrongly, so run them once per node, confirm each node reports the same cluster ID, and check the quorum before creating topics. Treat the cluster ID as a value you keep with your configuration. Your team should confirm the exact kafka-storage options and the bootstrap settings against the documentation for the release you chose, because they differ between minor versions.
Choosing the controller layout and formatting method
This table compares the three decisions that shape how a KRaft cluster starts: where controllers run, how storage is formatted, and how brokers find the quorum. Read each row for when the option fits and what it costs you later, then confirm the final choice against the version you will deploy.
| Decision | Option | Fits when | Trade-off |
|---|---|---|---|
| Controller roles | Combined broker and controller roles | Small clusters, test or non-critical environments, and teams with limited hosts | Controllers compete with brokers for memory, disk and network, and a busy broker can slow metadata work |
| Controller roles | Dedicated controllers | Production clusters where metadata stability matters more than host count | Extra hosts to provision, patch and monitor, and more formatting steps at bootstrap |
| Formatting method | Standalone formatting | A single-controller start or a lab where the quorum is not yet final | Cannot be used to build a multi-controller quorum from the start, so it limits the initial layout |
| Formatting method | Formatting with initial controllers | A multi-controller quorum that is defined before the first start | Every controller must agree on the same cluster ID and voter set, so mistakes are found late if not checked |
| Quorum discovery | Static quorum voters | Fixed controller hosts with stable addresses and a small, known membership | Changing voters later means editing configuration on every node and restarting in a planned order |
| Quorum discovery | controller.quorum.bootstrap.servers | Controller addresses may change or you expect to add controllers later | Brokers and new members depend on reachable bootstrap endpoints, which must be managed and tested |
| Cluster ID | Generated once and reused on all nodes | Every bootstrap, since all nodes must format with the same value | Reusing or regenerating it on one node causes nodes to refuse to join |
How to format controllers and brokers with one cluster ID
This sequence gives every controller and broker the same cluster ID, starts a KRaft metadata quorum, and registers the brokers with it. Each step ends with a check that confirms the node is ready before the next one begins.
Confirm the Kafka release and Java runtime
The platform team installs the same Kafka release on every host, chosen from the supported releases on the downloads page (currently 4.3.1, 4.2.2 and 4.1.2), and a Java 17 runtime, which Kafka 4.0 and later require for brokers and tools. Confirm the exact release choice with your own support policy before you install. The step is done when every host reports the same Kafka build and the same Java version.
Generate one cluster ID
Run the kafka-storage tool's ID generation command once, on a single machine, and record the output in your change record. Confirm the exact subcommand against the 4.3 documentation for your install. Every controller and broker in this cluster must receive this same value, so do not regenerate it on other hosts. The step is done when one ID string is recorded and copied unchanged into your host build notes.
Assign node IDs and roles
The platform team records, for each host, a unique node ID, whether it runs as a controller, a broker or both, and its log and metadata directories. The controller voter list and the bootstrap server settings, including controller.quorum.bootstrap.servers where your layout uses it, must match across hosts. Confirm the key names and where each applies in the 4.3 documentation. The step is done when a reviewed host table shows no duplicate IDs and every controller appears in the voter list.
Format the controller nodes
On each controller host, the platform engineer runs kafka-storage to format the metadata directory with the cluster ID. Choose the standalone path for a single-controller test or the initial-controllers path for a multi-controller quorum, and confirm the flags for your release in the 4.3 documentation. Format only controllers in this step. The step is done when each format command completes without error and the metadata directory carries the cluster ID.
Start controllers and confirm a leader
The engineer starts the controller processes, ideally one at a time so the logs stay readable. The controllers exchange votes and elect a leader. Confirm the quorum status command and log messages in the 4.3 operations documentation for your version. The step is done when the logs show an elected leader, every controller reports as a quorum member, and no controller is stuck in repeated election attempts.
Format the broker log directories
On each broker host, the engineer formats the broker log directories with the same cluster ID used for the controllers, using the same kafka-storage procedure but with the broker node's own settings. Do not reuse a log directory from another node. The step is done when each broker's format command completes and its directory metadata matches the cluster ID recorded in step two.
Start brokers and verify registration
The engineer starts the brokers and checks that each one registers with the controller quorum. The check is the broker list reported by the admin tooling described in the 4.3 documentation. Then the engineer creates a throwaway topic, confirms its partitions have leaders, and deletes it. If authorization is enabled, confirm your access rules first, because resources without ACLs are restricted to super users by default. The step is done when every broker is listed, the test topic has leaders, and the quorum remains stable.
Securing the cluster from the first boot
Kafka does not require security, so a bootstrap that skips it will run unsecured until someone retrofits it. The decisions below belong in the bootstrap plan because listeners, authentication and authorization are set while the cluster is first formatted and configured. Work through them in order before any client connects.
Decide listeners before formatting
Security is optional in Kafka, and a cluster can run unsecured or mix secured and unsecured listeners. Define each listener, its protocol and its purpose (client, inter-broker, controller) in the configuration you format with, so no plaintext listener is left open by default. Check that every advertised listener matches the endpoint clients will actually use, because a mismatch breaks connections after startup, not during formatting.
Encrypt traffic with SSL/TLS
Kafka encrypts traffic between clients, brokers and tools with SSL/TLS. Plan the certificate authority, the broker and controller certificates, and how certificates are renewed before expiry. Your internal CA process should cover clients and tools as well as brokers, since all of them connect to the same listeners. Confirm the keystore and truststore locations and permissions on every node before the first start.
Choose a SASL mechanism for clients
Kafka documents five SASL mechanisms: GSSAPI (Kerberos), PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 and OAUTHBEARER. Pick one per listener based on your identity system, and confirm that your client libraries and Connect workers support it. Credentials for SCRAM must be created in the cluster before clients can authenticate, so include that step in the bootstrap runbook.
Set authorization and ACLs at startup
In KRaft clusters the StandardAuthorizer stores ACLs in the cluster metadata log. Resources without ACLs are restricted to super users unless allow.everyone.if.no.acl.found is set to true. Leave that setting at its restrictive default for production, and create the ACLs your applications need as part of bootstrap. Test one producer and one consumer against a topic you created for the purpose before opening the cluster to teams.
Plan super users and controller access
Super users bypass ACLs, so keep the list short and tied to named administrators or service identities. Record who holds super user status, how it is granted and how it is revoked. Secure the controller listeners separately from broker listeners, because controllers hold the metadata that governs the whole cluster. Restrict network access to controller ports to brokers and administrators only.
Keep the security plan in version control
Listener definitions, certificate paths, SASL choices, super user lists and initial ACLs should live in reviewed configuration, not in a shell history. Store secrets in your approved secrets system, and keep the plan next to the formatting commands so a rebuilt node gets identical settings. Verify the final configuration by connecting with each client type and confirming that unauthenticated and unauthorized requests fail as expected.
What goes wrong when the cluster ID or quorum is wrong
Most bootstrap failures in KRaft mode show up as a cluster that never settles, not as a clear error at the point where the mistake was made. The first thing to check is the cluster ID. Every controller and broker must be formatted with the same ID, and a node formatted with a different ID will refuse to join the metadata quorum. The usual symptom is a startup log that reports an inconsistent cluster ID, or a node that stays out of the quorum while the others elect a leader. Compare the meta.properties file in each log directory and confirm that cluster.id matches everywhere. The second common mistake is running kafka-storage against a directory that already holds data, which can silently keep an old ID or metadata state. Check whether the directory was used by an earlier attempt before reformatting it, because the fix is to clear or replace that directory on the node, not to force a new format onto a live one.
Connectivity and addressing problems look different. Unreachable controller endpoints usually appear as repeated connection errors to the controller port, and a quorum that never forms is the result: controllers wait for a majority that cannot be reached. Confirm that each controller.quorum.bootstrap.servers entry resolves and accepts connections from every node, including across firewalls and load balancers. Advertised listener errors are harder to spot because the process starts normally. A broker may advertise a hostname or address that clients or other nodes cannot resolve, so the cluster appears healthy locally and fails for remote clients. Review advertised.listeners and controller.listener.names on each node against the addresses your network actually uses. Because DNS, certificates, load balancers and firewall rules differ between environments, the correct fix belongs to the network and platform owners. Ask them to confirm the path for each endpoint before you change Kafka configuration.
Limits to confirm in your environment
A KRaft bootstrap is only as good as the assumptions behind it. The cards below list the facts to confirm before any node is formatted, from the Java runtime and release pin to controller placement, migration status and the limits of the official image.
Java 17 for brokers and tools
Since Kafka 4.0, brokers, Kafka Connect and command-line tools require Java 17. Clients and Kafka Streams applications need at least Java 11, so the broker hosts and the client fleet may have different requirements. Confirm the runtime on every controller and broker host before running kafka-storage, since a mismatched JVM fails at format time or at first start. Check the JVM and Java settings guidance for supported versions and heap sizing.
The exact release to pin
Choose one release and pin it in every package, archive and image tag. The downloads page lists 4.3.1, 4.2.2 and 4.1.2 as supported, and earlier releases are archived. Confirm which release your security team has approved, because a cluster formatted with one version must run that same version on every node. Ask whether your mirror or artifact repository holds the exact checksum-verified archive you intend to deploy.
Controller hardware and disk
Controllers keep the metadata log on their own disks, so their storage and memory affect quorum stability. Do not size them from this page. Confirm the host profile, dedicated or colocated placement and disk type using the hardware sizing guidance, and confirm that the metadata directory is on persistent storage that survives restarts. Ask your infrastructure team whether the controller hosts meet that profile before the first format.
Network reachability between controllers
Controllers must reach each other on their controller listener ports in both directions, and brokers must reach the controllers as well. Confirm firewall rules, DNS names and any load balancer path that sits between hosts. A controller that resolves to the wrong address will join the quorum slowly or never, and the error often looks like a broker problem. Test each controller-to-controller path with a plain TCP check before you start the processes.
Migration path from ZooKeeper or 3.x
Determine whether you are building a new cluster or migrating an existing one. Kafka 4.0 removed ZooKeeper mode, so any ZooKeeper-based cluster must migrate to KRaft before upgrading to 4.x. Clusters older than 3.3.x should first move to 3.9.x. A bootstrap procedure does not migrate data or metadata from an existing cluster, so confirm the migration route with the project documentation before you format any new nodes.
Official image limits for production
The official apache/kafka images are published by the project and are the usual starting point for containers, but their production fit depends on your environment. Confirm the supported configuration method, the persistent volume paths for log and metadata directories, and whether the native image is intended for production. Ask the project or your platform team which tag you will pin and how that tag is rebuilt, patched and verified.
Questions teams ask before bootstrapping Kafka 4
Can an internal team bootstrap a KRaft cluster on its own?
Yes, an internal team with Linux, Java and network skills can bootstrap a KRaft cluster on its own, because the steps are documented in the Kafka project's own material. The harder part is what surrounds the first start: agreeing on controller count, certificate authority, listener layout, access control and how the cluster ID and storage directories are recorded and protected. Teams that have run Kafka before usually move faster. Teams that have not often benefit from a review of the design before the first formatting run, since several choices are difficult to change later without rebuilding storage.
What drives the effort of a Kafka 4 bootstrap?
Four factors shape most of the effort:
- Node count and layout: how many controllers and brokers, and whether controllers run on dedicated hosts or alongside brokers.
- Security: whether listeners use SSL/TLS, which SASL mechanism is chosen, and how ACLs are designed in the StandardAuthorizer.
- Multi-site needs: whether a second cluster, mirroring or a stretched layout is planned, since each changes networking and naming.
- Automation: whether provisioning runs through configuration management, containers or Kubernetes operators, and how repeatable the build must be.
Each factor adds design decisions and test cycles, so a small single-site lab and a multi-site production cluster differ mainly in these areas.
What does the work need from our side before it starts?
The client needs to provide, or agree on, several items before any formatting command runs:
- Hosts for controllers and brokers, with storage, memory and network sized to the plan.
- A supported Java runtime. Brokers and tools require Java 17 from Kafka 4.0 onward.
- Certificates from an internal or public certificate authority if TLS is used, including subject names that match advertised listeners.
- Network rules that allow controller and broker traffic, client access and monitoring between the right hosts.
- A change window for the first start and for any firewall or DNS work.
Confirm each item with your own security and infrastructure owners, since approval steps vary by organization.
How long does a Kafka 4 bootstrap take?
Duration depends on scope rather than on Kafka itself. A single-site cluster with a fixed node count, a chosen security model and existing infrastructure takes far less time than a multi-site layout with new certificate authority work, new network paths and automated provisioning. Approval cycles and change windows often set the calendar more than the technical work does. Ask for a written timeline as part of the scoped proposal, and ask which of your internal dependencies it assumes. No duration is given here because none has been established for a specific scope.
Is a fixed-scope engagement typical for a new Kafka cluster?
Yes, most DeployOpen engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. For a bootstrap, the written scope usually names the topology, the security model, the verification steps and the handover material. Ongoing items such as upgrades, monitoring or continuous testing can be separated into a retainer, so the one-time build and the recurring support are priced and agreed separately. DeployOpen does not publish a price list, so the quote follows from the written scope.
What happens if the cluster ID is wrong?
If a controller or broker is formatted with a cluster ID that does not match the cluster it is joining, it will not be accepted into that cluster and the mismatch shows up at startup. The cluster ID is generated once and must be used consistently with the kafka-storage format step on every node. Recovering usually means identifying which storage directory was formatted with the wrong value, clearing only that node's metadata directory after confirming it holds no data you need, and reformatting it with the correct ID. Record the cluster ID in your change ticket and check it on each host before the first start to avoid this recovery work.
Should we choose standalone or initial controller formatting?
Choose the formatting mode that matches the cluster you are building, and confirm the choice with the Kafka 4.3 upgrade and getting-started material before you run it. Standalone formatting suits a single controller used for testing or a simple layout, while formatting with initial controllers defines the voters for a multi-node quorum from the start. The decision affects how controller.quorum.bootstrap.servers is set on each host and how the quorum forms at first boot. Changing it later is possible but adds steps, so settle it during design.
Do we need security configured before the first start?
Security is optional in Kafka, so a cluster can start unsecured, but adding TLS or SASL later means changing listeners on every node and updating every client. Kafka supports SSL and SASL, including SCRAM-SHA-256, SCRAM-SHA-512, OAUTHBEARER, PLAIN and GSSAPI (Kerberos), and authorization is enforced through ACLs stored in the cluster metadata log. Decide the listener design and the authorizer behavior before the first start. Without ACLs, resources are limited to super users unless allow.everyone.if.no.acl.found is set, so confirm that setting with your security team.
What to do once the quorum is healthy
Once the controllers report a healthy quorum and the brokers have registered, the first job is handover: record the cluster ID generated for this cluster, the controller node IDs, the directory paths used for log.dirs and metadata.log.dir, and the exact kafka-storage arguments used for formatting. Store these alongside the configuration in your change system. If a node is later reformatted or rebuilt, the cluster ID and node IDs must match what the quorum expects, so an undocumented value is the most common reason a rebuild goes wrong. Back up the metadata directories on each controller while the cluster is quiet, and rehearse restoring one controller onto a spare host before you rely on that backup. Confirm the backup and restore procedure against your own storage layer, since the Kafka documentation does not prescribe a single method.
Next, create the first topics with partition counts and retention chosen from the expected throughput, consumer parallelism and retention obligations, not from defaults. Partition count is hard to reduce later, so write down the reasoning for each topic. Then set ACLs before any application connects. In KRaft clusters the StandardAuthorizer stores ACLs in the metadata log, and resources without an ACL are restricted to super users unless allow.everyone.if.no.acl.found is set to true. Leave that setting at its default unless you have a specific reason to change it, and test a denied request from a non-privileged principal to prove the policy works. Plan the upgrade path and day-two runbooks at this stage too: the Kafka downloads page lists the supported releases, and the operations and upgrade sections of this series cover what follows. If you need to replicate topics, consumer offsets and ACLs to another cluster, MirrorMaker 2 is the documented route, and it preserves partitioning.
Bootstrap choices by environment
On hosts you manage directly, the bootstrap runs as the Kafka documentation describes: you install a supported Java runtime, unpack the release, generate a cluster ID with kafka-storage, and format each controller and broker log directory before any process starts. Each host carries its own server.properties file, so node identity, listener addresses and directory paths are set per machine and checked by hand. Your team owns package installation, service units, file ownership and the order in which nodes start.
- Service management: Write systemd units or equivalent for controllers and brokers, and confirm the service user can write to every log and metadata directory before the first start.
- Per-node configuration: Set
node.id,process.rolesand advertised listeners on each host, and keep those files under version control so a changed host shows up in review. - Formatting on the host: Run the storage format step on each node with the single cluster ID you generated, and record that ID in your runbook because every node must match it.
- Java runtime: Brokers require Java 17 from Kafka 4.0 onward, so confirm the JVM on each host matches the release you installed.
- Start order: Bring up the controller quorum first, then the brokers, and verify the quorum has formed before adding client traffic.
Before you start, check that every host reports the same cluster ID, the same release and the same controller.quorum.bootstrap.servers value.
With the official apache/kafka image, the host operating system stops being the unit you configure. The bootstrap sequence stays the same, but the storage format and process start happen inside the container, and configuration usually arrives through environment variables and mounted volumes. The image tag becomes your release pin, so the version you bootstrap is the version you run until you change the tag on purpose.
- Version pinning: Use an explicit release tag instead of a floating one, so a container restart never changes the Kafka version under an existing metadata log.
- Persistent volumes: Mount the log and metadata directories on volumes that survive container replacement, because formatting into an ephemeral layer loses the metadata.
- Environment-based configuration: Confirm how each environment variable maps to a property key in the release you pinned before you rely on it.
- Cluster ID handling: Generate the cluster ID once and pass it to every container's format step, keeping it out of image layers and build files.
- Image variant: Read the Docker page in this group to confirm which image variant is suited to production before you bootstrap, since the native image is not intended for production use.
After each restart, check that every container's data volume is still bound to the same node identity before you treat the quorum as stable.
On Kubernetes, most bootstrap steps are performed by an operator from declarative resources. With Strimzi, controllers and brokers are declared as separate node pools, and the operator generates the cluster ID, formats storage and sequences the rollout. Your decisions move from shell commands to resource design: which pools exist, what storage each pool receives and which roles each pool carries. The checks you run shift to pod status, operator events and quorum health.
- Pool design: Declare controller and broker pools separately so each can be scaled and given its own storage class, as covered on the Strimzi node pools page in this group.
- Operator-managed identity: Let the operator assign node IDs and format storage, then read the generated cluster ID from the resource status instead of copying it into manifests by hand.
- Storage binding: Confirm persistent volume claims bind before the first pod starts, because a reattached claim determines which metadata a node sees.
- Platform differences: OpenShift adds security context constraints and route handling, so read the OpenShift page before applying the same manifests there.
- Version alignment: Match the operator version to the Kafka release you plan to run, and confirm the pairing in the operator documentation before installation.
Before you create topics, check that every controller pod reports a healthy quorum and that the cluster status shows no pending node pool changes.
How DeployOpen scopes and delivers a KRaft bootstrap
DeployOpen plans and builds self-hosted Kafka inside your own infrastructure, including the first KRaft bootstrap of controllers and brokers. Each engagement starts with a written scope that names the cluster ID process, controller layout, quorum checks and handover records before any node is formatted.
How we scope
- The written scope lists the Kafka version, controller and broker counts, and the hosts or pods that will run each role.
- We confirm whether controllers run combined with brokers or as dedicated nodes, and record the reasoning in the scope.
- Scope names the listener, TLS and SASL decisions that must exist before the first formatted directory is created.
How we build
- We generate and record the cluster ID, then format each controller with kafka-storage using the agreed bootstrap method.
- Controller bootstrap servers and quorum voters are written into configuration and checked against the actual hosts.
- We test quorum election, broker registration and a produce and consume round trip before the cluster is accepted.
How we hand over
- You receive the configuration files, format commands with their inputs, and a runbook for recording and recovering the cluster ID.
- Verification results from quorum status and broker registration are delivered as a dated record.
- Operators walk through the startup order, the restart procedure and the checks to run after any node replacement.
How we support
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Questions about your environment, such as network policy or storage layout, are confirmed with you before changes are made.

