docs(lvm-local-storage): document chunk size + expand tuning section - #1083
Open
abonillabeeche wants to merge 11 commits into
Open
docs(lvm-local-storage): document chunk size + expand tuning section#1083abonillabeeche wants to merge 11 commits into
abonillabeeche wants to merge 11 commits into
Conversation
Add a brief comparison of the two volume group types to help operators pick the right StorageClass for their workload, and append a small "Additional Notes" section covering thin-pool tuning, VM disk-bus recommendation, and Longhorn v2 coexistence. Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Jillian moved the striped vs dm-thin explanation into the procedure step above (Volume Group Type), so the standalone section is now duplicate content. The "For more information, see [StorageClass]" link is kept. Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
Field investigation showed that Harvester's LVM CSI driver, when creating a new thin pool, was letting LVM auto-select the chunk_size, which for multi-TB pools produces 8-16 MiB chunks. On random 4K workloads this causes severe write amplification (up to 4096:1). A field customer measured DI_RANDOM = 326 IOPS on hardware capable of 10x that, traced to a 16 MiB chunk size. harvester/csi-driver-lvm PR harvester#57 (still in review) exposes three new StorageClass parameters (chunkSize, poolMetadataSize, zeroBlocks) and ships sensible defaults (512K/16G/false). This docs change explains the choice, when to override, the hard "cannot change after pool creation" constraint, and gives a full example StorageClass with all three parameters set. Also expands the existing chunk-zeroing and pool-metadata subsections to reference the new StorageClass parameters (in addition to the post-creation lvchange/lvextend workflows they already documented). Only edits the current-dev docs/ tree - not backported to versioned_docs/, since the StorageClass parameters ship in a CSI driver version that will target Harvester v1.9. The post-creation lvchange/lvextend commands work on older Harvester versions, but the chunkSize parameter itself does not. Base is docs-lvm-considerations (PR harvester#1075), which introduces the initial "Tuning the dm-thin Pool" section. Rebasing onto main once harvester#1075 merges. Signed-off-by: Alejandro Bonilla <abonilla@suse.com>
…stripe alignment Recommend 1M as the default dm-thin chunk size so it matches the full-stripe width of common hardware-RAID layouts. A sub-stripe chunk (e.g. 512K on a 1M stripe) forces partial-stripe read-modify-write and, on parity RAID (5/6), widens the write-hole window, risking parity inconsistency on unclean shutdown without a protected controller cache. Update the values table, metadata sizing note, and example StorageClass accordingly. Signed-off-by: Alejandro Bonilla <abonilla@suse.com> Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ibrokethecloud
approved these changes
Jul 30, 2026
|
Tick the box to add this pull request to the merge queue (same as
|
Contributor
Author
|
@jillian-maroket PING |
Contributor
|
@abonillabeeche I'll work on this next week. Too many release deliverables. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to csi-driver-lvm PR #57 — documents the new
chunkSize,poolMetadataSize, andzeroBlocksStorageClass parameters and expands the existing "Tuning thedm-thinPool" section (introduced in #1075) with:1M(aligns with the RAID full-stripe width common on Harvester hardware, avoiding partial-stripe read-modify-write and, on parity RAID, write-hole exposure), when to override (match your RAID full stripe;512K/128Konly for sub-stripe or non-RAID VGs, never >2M), the hard "cannot change after pool creation" constraint, and how to verify the effective chunk size of a live pool.zeroBlocksStorageClass parameter (in addition to the existing post-creationlvchange --zero nworkflow).poolMetadataSizeStorageClass parameter (default16Gcovers 256 TB pools at 1M chunks) and adds the metadata sizing formula.Motivation
A field customer running everything from our runbook ended up with a 16 MiB chunk_size on their thin pool. LVM's default auto-select scales chunk_size with pool size to keep metadata bounded, which for multi-TB pools produces 8-16 MiB chunks — appropriate for metadata sizing but disastrous for random-IOPS workloads (up to 4096:1 allocation write amplification on 4K writes to virgin regions).
Customer's measured DI_RANDOM: 326 IOPS. Our lab measurement on hardware in the same performance class with an explicit, stripe-aligned chunk size +
zero=n: 15,000+ QD1 4K IOPS. The gap is entirely explained by chunk size + zero-on-allocate.Test plan
npm start) — page renders, no broken linksBase branch note
This PR includes the "Tuning the
dm-thinPool" section from PR #1075 (APPROVED + MERGEABLE) because it builds on that section. Please merge #1075 first — this PR will show a clean diff (just the chunk-size additions) once it rebases against post-#1075 main.Scope
Only edits
docs/advanced/addons/lvm-local-storage.md(current-dev / v1.9 tree). Not backported toversioned_docs/because thechunkSizeStorageClass parameter ships in a CSI driver version targeting Harvester v1.9. Thelvchange/lvextendpost-creation workflows work on older versions but were already covered by #1075.References
performancepolicy — the 512 KiB general-purpose seed (Harvester defaults to1Mfor RAID full-stripe alignment)🤖 Generated with Claude Code