Use JBOD with Self-Balancing in Confluent Platform

Self-Balancing Clusters can balance data across the disks within a single broker in clusters that use Just a Bunch of Disks (JBOD) setups. With JBOD enabled, you run commands to move replicas between the disks on a broker so that data is evenly distributed.

This intra-broker balancing is distinct from the inter-broker balancing that Self-Balancing performs automatically. Intra-broker balancing is on demand only: you run a command when you want to rebalance disks, and Self-Balancing doesn’t trigger it as part of its self-healing. For an overview of Self-Balancing, see Manage Self-Balancing Kafka Clusters in Confluent Platform.

Enable JBOD support

To enable JBOD support, configure multiple log directories and set the Self-Balancing and JBOD properties on the brokers and controllers.

Prerequisites

A cluster with a JBOD setup must specify multiple log directories in the log.dirs configuration in each broker’s properties file, where each log directory is on a different disk. If the log directories are not on different disks, Self-Balancing JBOD support doesn’t work.

The following code shows an example of multiple log directories in a broker’s properties file:

log.dirs=/mnt/disk1/kafka-logs,/mnt/disk2/kafka-logs,/mnt/disk3/kafka-logs

The log.dirs configuration is not dynamic, meaning that you must restart the brokers after you change it.

After you configure multiple log directories, enable Self-Balancing for JBOD as described in the next section.

Configure Self-Balancing for JBOD

To enable Self-Balancing to balance data across broker disks:

Enable Self-Balancing by setting confluent.balancer.enable to true in the properties file for every broker and controller in the cluster:
```
confluent.balancer.enable=true
```
Enable confluent.telemetry.metrics.collector.volume.include.logDirs.label for each broker so that brokers communicate per-disk capacity information to Self-Balancing:
```
confluent.telemetry.metrics.collector.volume.include.logDirs.label=true
```
This configuration is not dynamic, so you must restart the brokers after you set it.
Enable confluent.balancer.jbod.enable so that Self-Balancing balances data across disks. Set this in the properties file for every controller in the cluster:
```
confluent.balancer.jbod.enable=true
```
This configuration is not dynamic, so you must restart the controllers after you set it.

These configurations work together: Self-Balancing balances data across disks only when all are set. For the full requirement list, see confluent.balancer.jbod.enable.

Disable JBOD support

To disable JBOD support, set the JBOD configuration to false on the controllers and stop the brokers from emitting per-disk capacity metrics. Without JBOD support, Self-Balancing doesn’t work with multiple disks.

Before you disable JBOD support, ensure that no intra-broker rebalance is in progress (see Limitations).

Complete the following steps:

Set confluent.balancer.jbod.enable to false in the properties file for every controller in the cluster, and restart the controllers:
```
confluent.balancer.jbod.enable=false
```
To stop the brokers from emitting per-disk capacity metrics, set confluent.telemetry.metrics.collector.volume.include.logDirs.label to false in the properties file for every broker, and restart the brokers:
```
confluent.telemetry.metrics.collector.volume.include.logDirs.label=false
```

Balance data across disks

Use the kafka-rebalance-cluster command-line tool to balance data across the disks on your brokers. To learn more about this tool, see Monitoring the balancer with kafka-rebalance-cluster.

Preview an intra-broker rebalance

Run the command with the --intra-broker-rebalance-dry-run flag to compute and review the rebalance plan without moving any data:

kafka-rebalance-cluster --bootstrap-server <host:port> --command-config <path_to_client.properties> --intra-broker-rebalance-dry-run

The output shows the proposed moves, the goals evaluated, and the projected cluster load before and after rebalancing. For example:

Computing intra-broker rebalance plan...
Optimization has 53 intra-broker replica(2968.00 MB) moves with a cluster model of 12 recent windows and 100.00% of the partitions covered.
New brokers: [].
Dead or removed brokers: [].
Violated goals before optimization: [IntraBrokerDiskCapacityGoal, IntraBrokerDiskUsageDistributionGoal].
Violated goals after optimization: [IntraBrokerDiskUsageDistributionGoal].
Goals which generated movements: [IntraBrokerDiskCapacityGoal, IntraBrokerDiskUsageDistributionGoal].
...
On-demand balancedness score before and after: 0.00 -> 62.26.

Run an intra-broker rebalance

Run the tool with the --intra-broker-rebalance flag to start moving replicas between disks:

kafka-rebalance-cluster --bootstrap-server <host:port> --command-config <path_to_client.properties> --intra-broker-rebalance

Triggering an intra-broker rebalance...
Triggered an intra-broker rebalance operation. You can check its status by calling this command again with the `--describe` option.

Check the status of the rebalance with the --describe flag:

kafka-rebalance-cluster --bootstrap-server <host:port> --command-config <path_to_client.properties> --describe

Uneven load balance status:
  HealUnevenLoadTrigger: ANY_UNEVEN_LOAD
  Current: BALANCING
  Last Update Time: 2026-05-04_09:02:08 UTC
  Previous: BALANCED
  Last Update Time: 2026-05-04_03:23:04 UTC

Limitations

The following limitations apply to Self-Balancing JBOD support:

Intra-broker rebalance is on demand and is not triggered automatically as part of Self-Balancing self-healing. Monitor your intra-broker disk usage and use the balancing commands to balance data across broker disks.
The balancing commands don’t work if Self-Balancing is running an existing reassignment. Wait for the reassignment to complete, and then run the intra-broker rebalance command.
Unlike with brokers, Self-Balancing doesn’t automatically detect a dead disk or take any action for one. The balancing commands don’t work when a dead disk is present.
Self-Balancing cannot expand or shrink the number of broker disks.

Tune intra-broker balancing

Use the following configurations to tune how Self-Balancing balances data across disks:

confluent.balancer.intra.broker.throttle.bytes.per.second configures the replication throttle limit for intra-broker movements.
confluent.balancer.num.concurrent.intra.broker.partition.movements.per.disk changes the parallelism limit on intra-broker movements.
confluent.balancer.intra.broker.disk.max.load, confluent.balancer.intra.broker.disk.balance.threshold, and confluent.balancer.intra.broker.disk.min.free.space.gb control how Self-Balancing acts when an intra-broker rebalance runs.

The following example sets these configurations to their default values in a broker properties file:

confluent.balancer.intra.broker.throttle.bytes.per.second=10485760
confluent.balancer.num.concurrent.intra.broker.partition.movements.per.disk=1
confluent.balancer.intra.broker.disk.max.load=0.85
confluent.balancer.intra.broker.disk.balance.threshold=1.1
confluent.balancer.intra.broker.disk.min.free.space.gb=0

The throttle is a dynamic option, so you can also adjust it while the cluster is running:

kafka-configs --bootstrap-server <host:port> --entity-type brokers --entity-default --alter --add-config confluent.balancer.intra.broker.throttle.bytes.per.second=20971520

For full configuration details, see Self-Balancing configuration.