How to replace a GlusterFS brick

Replacing a GlusterFS brick swaps a single brick endpoint (server:directory) for a new one while keeping the volume online, restoring redundancy after a disk retirement or node failure without forcing disruptive client remounts.

A brick replacement updates the volume’s brick list and, on replicated or dispersed volumes, triggers background healing so the new brick receives the data it is missing. The gluster volume replace-brick workflow supports both a staged migration (start → status → commit) when the old brick is still reachable, and a forced commit when the old brick is permanently offline.

The replacement target must be a peer in the trusted pool, reachable over the cluster network, and backed by an empty brick directory (for example /srv/gluster/brick1) on the intended mounted filesystem. Brick migration and healing can sustain disk and network load for the duration of the copy, so production clusters typically schedule replacements during quieter periods. On distributed-only volumes (no replication or erasure coding), data that existed only on the failed brick is not recovered by replacing it.

1. Identify the brick entry to replace from the volume definition.

   $ sudo gluster volume info volume1
   
   Volume Name: volume1
   Type: Replicate
   Status: Started
   Bricks:
   Brick1: node1:/srv/gluster/brick1
   Brick2: node2:/srv/gluster/brick1

   Brick names must match exactly, including the node name and full directory path.

2. Confirm the replacement node is Connected in the trusted storage pool.

   $ sudo gluster peer status
   Number of Peers: 2
   
   Hostname: node2
   Uuid: 3b9d4f0c-7a86-4b8f-9c1e-8f1a1c8d9c0d
   State: Peer in Cluster (Connected)
   
   Hostname: node3
   Uuid: 8a0f2d1e-2c59-4e6e-8b4e-3e9b0e8c7b61
   State: Peer in Cluster (Connected)

3. Create the replacement brick directory on the target node.

   $ sudo mkdir -p /srv/gluster/brick1

4. Verify the replacement brick directory is empty on the target node.

   $ sudo ls -A /srv/gluster/brick1
   
   $ df -h /srv/gluster/brick1
   Filesystem      Size  Used Avail Use% Mounted on
   /dev/sdb1       1.8T   32G  1.7T   2% /srv/gluster

   Replacing into a non-empty directory can expose unrelated files to the volume and can cause unexpected behavior during healing.

   Related: How to mount disks and partitions in Linux

5. Start the replace-brick migration when the old brick is still reachable.

   $ sudo gluster volume replace-brick volume1 node2:/srv/gluster/brick1 node3:/srv/gluster/brick1 start
   volume replace-brick: success: replace-brick operation started on volume volume1

   Skip migration start when the old brick is permanently offline, then use a forced commit later.

6. Check the replace-brick migration status until it reports completed.

   $ sudo gluster volume replace-brick volume1 node2:/srv/gluster/brick1 node3:/srv/gluster/brick1 status
   Replace brick status on volume: volume1
   Old Brick: node2:/srv/gluster/brick1
   New Brick: node3:/srv/gluster/brick1
   Migration status: completed

   Re-running the status command during migration provides progress feedback without changing the operation.

7. Commit the brick replacement when migration status reports completed on an online old brick.

   $ sudo gluster volume replace-brick volume1 node2:/srv/gluster/brick1 node3:/srv/gluster/brick1 commit
   volume replace-brick: success: replace-brick commit on volume volume1

8. Force-commit the brick replacement when the old brick is offline.

   $ sudo gluster volume replace-brick volume1 node2:/srv/gluster/brick1 node3:/srv/gluster/brick1 commit force
   volume replace-brick: success: replace-brick commit forced on volume volume1

   Using commit force skips migration checks and can leave data behind on the old brick; reserve it for failed bricks in replicated or dispersed volumes where a healthy copy exists.

9. Confirm the new brick appears in the volume definition.

   $ sudo gluster volume info volume1
   Volume Name: volume1
   Status: Started
   Bricks:
   Brick1: node1:/srv/gluster/brick1
   Brick2: node3:/srv/gluster/brick1

10. Verify brick processes are online for the updated volume.

    $ sudo gluster volume status volume1
    Status of volume: volume1
    Gluster process                             TCP Port  RDMA Port  Online  Pid
    ------------------------------------------------------------------------------
    Brick node1:/srv/gluster/brick1             49152     0          Y       1443
    Brick node3:/srv/gluster/brick1             49154     0          Y       1522
    Self-heal Daemon on node1                   N/A       N/A        Y       1520
    Self-heal Daemon on node3                   N/A       N/A        Y       1631

11. Verify self-heal shows no pending entries after the replacement.

    $ sudo gluster volume heal volume1 info summary
    Brick node1:/srv/gluster/brick1
    Number of entries: 0
    
    Brick node3:/srv/gluster/brick1
    Number of entries: 0

    A non-zero entry count indicates healing is still running or blocked by an error condition.