docs(lvm-local-storage): document chunk size + expand tuning section#1083
Open
abonillabeeche wants to merge 10 commits into
Open
docs(lvm-local-storage): document chunk size + expand tuning section#1083abonillabeeche wants to merge 10 commits into
abonillabeeche wants to merge 10 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 <[email protected]>
Co-authored-by: Jillian Maroket <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
Co-authored-by: Jillian Maroket <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
Co-authored-by: Jillian Maroket <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
Co-authored-by: Jillian Maroket <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
Co-authored-by: Jillian Maroket <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
Co-authored-by: Jillian Maroket <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
Co-authored-by: Jillian Maroket <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
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 <[email protected]> Signed-off-by: Alejandro Bonilla <[email protected]>
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 <[email protected]>
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
1 participant
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:zeroBlocksStorageClass parameter (in addition to the existing post-creationlvchange --zero nworkflow).poolMetadataSizeStorageClass parameter (default16Gcovers 128 TB pools at 512K 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 512K chunks +
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 — where 512K comes from🤖 Generated with Claude Code