Replication Factor

Pilot can automatically increase the replication factor (RF) of partitions that are below a configured target. This is useful for gradually improving data durability across your cluster.

Configuration

PILOT_BALANCE_MIN_RF=3  # Target replication factor (0 = disabled)

When set, all partitions with an RF below this value will have additional replicas proposed by the engine.

Behavior

When the target replication factor is configured:

1. Detection - the proposal engine scans all partitions and identifies those below the target RF
2. Replica addition - for each under-replicated partition, new replica brokers are selected
3. Rack awareness - new replicas are always placed in a rack-aware manner (no two replicas on the same rack)
4. No leadership changes - leaders remain unchanged; only followers are added
5. Load balancing - new replicas are placed on the least-loaded brokers

Example

Before (RF = 2)

topic: my-topic, partition: 0
replicas: [1, 2]
leader: 1

After (target RF = 3)

topic: my-topic, partition: 0
replicas: [1, 2, 3]
leader: 1 (unchanged)

The proposal output includes the reason:

{
  "topic": "my-topic",
  "partition": 0,
  "currentReplicas": [1, 2],
  "proposedReplicas": [1, 2, 3],
  "reason": "Increase replication factor from 2 to 3 (target: 3)"
}

Safety Features

• No RF decreases - the system will never reduce replication factor
• Rack awareness - all new replicas respect rack constraints
• Broker availability - only online, non-maintenance brokers are selected
• Duplicate prevention - no duplicate brokers in the replica set
• Leader preservation - the leader always remains in the replica set

Self-Healing Integration

RF increases can run automatically via the self-healing RF loop:

PILOT_HEAL_RF_ENABLED=true
PILOT_HEAL_RF_INTERVAL=15m
PILOT_HEAL_DRY_RUN=false

See Self-Healing for details on enabling automatic healing.

Limitations

• Rack constraints - if there aren’t enough racks, the target RF may not be reachable
• Broker availability - requires sufficient online brokers to host additional replicas
• Maintenance mode - brokers in maintenance are not selected for new replicas

Use Cases

• Gradual RF increase - safely increase RF across your cluster without manual intervention
• Compliance - ensure all partitions meet minimum durability requirements
• Cluster expansion - increase RF when adding new brokers and racks
• Data protection - automatically add replicas for under-replicated topics