Doc: storage.yaml

[masaori335]

Revive #11000 for the config project. Diffs from #11000 are

1. This deprecates storage.config and volume.config, but keeps them for compatibility, so we can merge to master branch.
2. Rename spans.id to spans.name for clarity
3. Add volumes.avg_obj_size and volumes.fragment_size support

If this looks good, I'll work on implementation.

[Copilot]

Pull request overview

Introduces documentation for the new unified storage.yaml cache configuration, and marks the legacy storage.config and volume.config formats as deprecated. It also updates the admin config index and documents per-volume avg_obj_size and fragment_size overrides.

Changes:

• Add comprehensive storage.yaml documentation including schema (spans, volumes, volumes.spans), allocation rules, and migration/backwards compatibility information.
• Mark storage.config and volume.config as deprecated in favor of storage.yaml and cross-link them appropriately.
• Update the admin “Configuration Files” index to include storage.yaml and to reflect the new deprecation status of storage.config and volume.config.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 11 comments.

File	Description
doc/admin-guide/files/storage.yaml.en.rst	New, full reference and examples for storage.yaml, covering storage spans, volume definitions (including avg_obj_size and fragment_size), allocation behavior, and compatibility with existing storage.config/volume.config.
doc/admin-guide/files/storage.config.en.rst	Adds an .. important:: block to mark storage.config as deprecated in favor of storage.yaml.
doc/admin-guide/files/volume.config.en.rst	Adds an .. important:: block to mark volume.config as deprecated in favor of storage.yaml.
doc/admin-guide/files/index.en.rst	Registers storage.yaml in the configuration files toctree and updates one-line descriptions for storage.config, storage.yaml, and volume.config to reflect the new deprecations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bryancall]

Feature comparison: storage.config + volume.config vs storage.yaml

I compared the documented features in the existing config files against the new storage.yaml docs and found a few gaps:

#	Missing from storage.yaml docs	Notes
1	Human-readable size suffixes (K, M, G, T)	storage.config documents these. The new YAML examples only show raw byte values (e.g., 134217728 instead of 128M). Should document whether YAML sizes support the same suffixes.
2	Fragment size maximum (4MB)	volume.config documents "this setting has a maximum value of 4MB". Not mentioned in storage.yaml fragment_size description.
3	Cache invalidation warning	Both storage.config and volume.config warn that changes effectively invalidate the cache. The new storage.yaml docs do not include this warning.
4	Minimum span/volume sizes	storage.config says "a formatted or raw disk must be at least 128 MB". volume.config says "128 MB is the smallest value" and sizes must be multiples of 128 MB. Not mentioned in storage.yaml.
5	Striping behavior	volume.config explains how volumes stripe across disks for parallel I/O. This is useful context missing from the new docs.

Items 1-3 are the most important -- users will hit these in practice. 4 and 5 are nice-to-have.

Otherwise the docs look thorough. The examples are clear, the backwards compatibility section is helpful, and the avg_obj_size / fragment_size per-volume overrides are well documented.