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 Polystack administrator if you do not have sufficient permissions.

​
Ring Structure

Each ring file (e.g., object.ring.gz) contains:

​
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
2

Rebalance the ring

Rebalance ring
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
Distribute object.ring.gz to /etc/ironcore-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
2

Rebalance to drain the device

Rebalance to migrate data off device
3

Wait for replication to complete

Monitor with ironcore-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
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
All nodes should report identical MD5 hashes for each ring file. Mismatched hashes indicate stale ring files on specific nodes.

​
Ring Builder Operations Reference

​
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