Ring Management

Manage NxtSight Object Storage consistent hash rings — add and remove devices, adjust weights, rebalance rings, and distribute updated ring files to all nodes.

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

---

Ring Structure

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

Component	Description
Devices	All registered storage drives with zone, region, IP, port, and weight
Partitions	Virtual partition slots distributed across devices based on weight
Replicas	Number 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

   nxtVirt-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

   nxtVirt-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

   nxtVirt-ring-builder object.builder write_ring
   

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

   nxtVirt-ring-builder object.builder set_weight <device-id> 0
   
2. Rebalance to drain the device

   Rebalance to migrate data off device

   nxtVirt-ring-builder object.builder rebalance
   
3. Wait for replication to complete

   Monitor with nxtVirt-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

   nxtVirt-ring-builder object.builder remove <device-id>
   nxtVirt-ring-builder object.builder rebalance
   nxtVirt-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

nxtVirt-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

Show ring builder contents

nxtVirt-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