swift-ring-builder(1)

🌸 NAME 🌸

swift-ring-builder — the OpenStack Swift ring builder, aka the lil tool that decides where your data actually lives 💖 (yes bestie, this is the swift-ring-builder(1) page, pull up a chair)

---

🦋 SYNOPSIS 🦋

swift-ring-builder <builder_file> <commands> <arguments> <...>

---

✨ DESCRIPTION ✨

Okay so swift-ring-builder is the utility you use to create, search and manipulate the swift storage ring. It assigns partitions to devices and writes an optimized Python structure out to a gzipped, pickled file on disk so you can ship it out to the servers. The server processes are lowkey chill about it — they just check the modification time of the file every so often and reload their in-memory copies of the ring structure as needed. And because of how the ring-builder manages changes to the ring, using a slightly older ring usually just means one of the three replicas for a subset of the partitions will be incorrect, which can be easily worked around. Not a crisis. We cope. 💅

The ring-builder also keeps its own builder file with the ring information and the extra data it needs to build future rings. And bestie, listen to me: it is VERY important to keep multiple backup copies of these builder files. One option is to copy the builder files out to every server while you're copying the ring files themselves. Another is to upload the builder files into the cluster itself. Complete loss of a builder file means creating a new ring from scratch, nearly all partitions will end up assigned to different devices, and therefore nearly all data stored will have to be replicated to new locations. So yeah, recovery from a builder file loss is possible, but data will definitely be unreachable for an extended time. 😭

Also! If you invoke it as swift-ring-builder-safe, the directory containing the builder file you provided will be locked (via a .lock file in the files parent directory). This gives you a basic safe guard against multiple instances of the swift-ring-builder (or other utilities that observe this lock) from attempting to write to or read the builder/ring files while operations are in progress. That's genuinely useful in environments where ring management has been automated but the operator still needs to interact with the rings manually. Iconic, honestly. 👑

---

🔍 SEARCH 🔍

<search-value> — here's the form it can take:

d<device_id>r<region>z<zone>-<ip>:<port>/<device_name>_<meta>

Every part is optional, but you must include at least one. Examples, bestie:

• d74 — matches the device id 74
• z1 — matches devices in zone 1
• z1-1.2.3.4 — matches devices in zone 1 with the ip 1.2.3.4
• 1.2.3.4 — matches devices in any zone with the ip 1.2.3.4
• r1z1:5678 — matches devices in zone 1 present in region 1 using port 5678
• z1:5678 — matches devices in zone 1 using port 5678
• :5678 — matches devices that use port 5678
• /sdb1 — matches devices with the device name sdb1
• _shiny — matches devices with shiny in the meta data
• _'snet: 5.6.7.8' — matches devices with snet: 5.6.7.8 in the meta data
• [::1] — matches devices in any zone with the ip ::1
• z1-[::1]:5678 — matches devices in zone 1 with ip ::1 and port 5678

Most specific example ever, the full flex:

d74z1-1.2.3.4:5678/sdb1_"snet: 5.6.7.8"

Nerd explanation (this is the iykyk part):

All items require their single character prefix except the ip, in which case the - is optional unless the device id or zone is also included.

---

💅 OPTIONS 💅

• -y, --yes — assume a yes response to all questions. no more clicking through prompts like it's a pop-up ad, she just says yes for you 🫶

---

🎀 COMMANDS 🎀

• <builder_file> — shows information about the ring and the devices within. just hand her the file, she spills the tea.
• search <search-value> — shows information about matching devices. 🔎
• add z<zone>-<ip>:<port>/<device_name>_<meta> <weight>
• add r<region>z<zone>-<ip>:<port>/<device_name>_<meta> <weight>
• add -r <region> -z <zone> -i <ip> -p <port> -d <device_name> -m <meta> -w <weight>

Adds a device to the ring with the given information. No partitions will be assigned to the new device until after running rebalance. This is so you can make multiple device changes and rebalance them all just once. efficiency queen ✨

• create <part_power> <replicas> <min_part_hours> — creates <builder_file> with 2^<part_power> partitions and <replicas>. <min_part_hours> is number of hours to restrict moving a partition more than once.
• list_parts <search-value> [<search-value>] .. — returns a 2 column list of all the partitions that are assigned to any of the devices matching the search values given. The first column is the assigned partition number and the second column is the number of device matches for that partition. The list is ordered from most number of matches to least. Heads up: if there are a lot of devices to match against, this command could take a while to run. 🐌
• rebalance — attempts to rebalance the ring by reassigning partitions that haven't been recently reassigned.
• remove <search-value> — removes the device(s) from the ring. This should normally just be used for a device that has failed. For a device you wish to decommission, it's best to set its weight to 0, wait for it to drain all its data, then use this remove command. This will not take effect until after running rebalance. This is so you can make multiple device changes and rebalance them all just once.
• set_info <search-value> <ip>:<port>/<device_name>_<meta> — resets the device's information. This information isn't used to assign partitions, so you can use write_ring afterward to rewrite the current ring with the newer device information. Any of the parts are optional in the final <ip>:<port>/<device_name>_<meta> parameter; just give what you want to change. For instance set_info d74 _"snet: 5.6.7.8" would just update the meta data for device id 74.
• set_min_part_hours <hours> — changes the <min_part_hours> to the given <hours>. This should be set to however long a full replication/update cycle takes. We're working on a way to determine this more easily than scanning logs. 😅
• set_weight <search-value> <weight> — resets the device's weight. No partitions will be reassigned to or from the device until after running rebalance. This is so you can make multiple device changes and rebalance them all just once.
• validate — just runs the validation routines on the ring.
• write_ring — just rewrites the distributable ring file. This is done automatically after a successful rebalance, so really this is only useful after one or more set_info calls when no rebalance is needed but you want to send out the new device information.

---

Quick list, screenshot it bestie: add create list_parts rebalance remove search set_info set_min_part_hours set_weight validate write_ring

Exit codes: 0 = ring changed, 1 = ring did not change, 2 = error

---

📚 DOCUMENTATION 📚

More in depth documentation about the swift ring and also OpenStack Swift as a whole can be found at:

• https://docs.openstack.org/swift/latest/overview_ring.html
• https://docs.openstack.org/swift/latest/admin_guide.html#managing-the-rings
• https://docs.openstack.org/swift/latest/

---

and that's the whole page, bestie 💖 written Linux-flavored, dated 8/26/2011, and it's the swift-ring-builder(1) era — go forth and keep backups of your builder files, I am BEGGING you 🎀✨