---
title: "Replication Factor - Pilot Docs"
description: "Automatic replication factor increase for under-replicated topics"
url: "https://docs.calinora.io/features/replication-factor/"
---

# 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

```bash
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:

```json
{
  "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:

```bash
PILOT_HEAL_RF_ENABLED=true
PILOT_HEAL_RF_INTERVAL=15m
PILOT_HEAL_DRY_RUN=false
```

See [Self-Healing](https://docs.calinora.io/features/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