Skip to main content

​
Overview

The consistent hash rings determine where every object, container, and account lives in the cluster. Ring changes require building new ring files and distributing them to all nodes. Object rebalancing occurs gradually as the replicator daemon synchronizes data to its new target locations.
Administrator Access Required — This operation requires the admin role. Contact your Xloud administrator if you do not have sufficient permissions.

​
Ring Structure

Each ring file (e.g., object.ring.gz) contains:
ComponentDescription
DevicesAll registered storage drives with zone, region, IP, port, and weight
PartitionsVirtual partition slots distributed across devices based on weight
ReplicasNumber of copies maintained for each partition

​
Add a Storage Device

Adding new drives expands cluster capacity. New drives start with weight 0 and are gradually weighted up to prevent sudden data movement storms.
1

Add the device to the ring builder

Add device to object ring
xavs-ring-builder object.builder add \
  --region 1 \
  --zone 1 \
  --ip <storage-node-ip> \
  --port 6200 \
  --device <device-name> \
  --weight 100
2

Rebalance the ring

Rebalance ring
xavs-ring-builder object.builder rebalance
Rebalancing moves data between nodes. In large clusters, a full rebalance can take hours and generate significant network traffic. Use --max-balance to limit the percentage of partitions moved per rebalance cycle.
3

Write and distribute the ring file

Write the updated ring file
xavs-ring-builder object.builder write_ring
Distribute object.ring.gz to /etc/xavs-object-storage/ on all proxy and storage nodes.

​
Remove a Storage Device

Graceful device removal involves reducing weight to 0 and rebalancing before physically removing the device.
1

Set device weight to 0

Drain device weight
xavs-ring-builder object.builder set_weight <device-id> 0
2

Rebalance to drain the device

Rebalance to migrate data off device
xavs-ring-builder object.builder rebalance
3

Wait for replication to complete

Monitor with xavs-storage-recon --replication until the device shows zero pending objects and no replication errors.
4

Remove the device from the ring

Remove device and final rebalance
xavs-ring-builder object.builder remove <device-id>
xavs-ring-builder object.builder rebalance
xavs-ring-builder object.builder write_ring
Redistribute the updated ring file to all nodes.

​
Verify Ring Consistency

After distributing updated ring files, verify all nodes are using the same ring:
Check MD5 hash of ring files on all nodes
xavs-storage-recon --md5
All nodes should report identical MD5 hashes for each ring file. Mismatched hashes indicate stale ring files on specific nodes.

​
Ring Builder Operations Reference

xavs-ring-builder object.builder show

​
Next Steps

Replication

Monitor data migration after ring changes

Storage Policies

Understand how storage policies map to ring files

Monitoring

Track rebalancing progress and disk usage

Admin Troubleshooting

Diagnose ring inconsistencies and rebalancing failures