Skip to content

docs: extract storage related documentation as a dedicated guide#243

Open
arekborucki wants to merge 3 commits into
ClickHouse:mainfrom
arekborucki:docs/storage-guide
Open

docs: extract storage related documentation as a dedicated guide#243
arekborucki wants to merge 3 commits into
ClickHouse:mainfrom
arekborucki:docs/storage-guide

Conversation

@arekborucki

Copy link
Copy Markdown
Contributor

Why

The Configuration guide currently includes storage details inline, but storage has enough operational behavior and validation rules to deserve a dedicated guide. Users need one place that explains how dataVolumeClaimSpec, ephemeral/custom volumes, PVC expansion, and multi-disk JBOD behave, especially which storage layout changes are rejected after cluster creation.

What

Adds a dedicated Storage and volumes guide and links it from the Guides navigation. The new guide extracts and expands the existing storage documentation with primary PVC behavior, ephemeral storage warnings, expansion requirements, JBOD-generated storage_configuration, custom storage policy guidance, immutability rules, and a validation reference for common rejected configurations. The Configuration guide now keeps a short storage overview and links to the new dedicated page.

@GrigoryPervakov GrigoryPervakov changed the title Docs/storage guide docs: extract storage related documentation as a dedicated guide Jun 22, 2026

@GrigoryPervakov GrigoryPervakov left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accurate and reads well. One scope nit: a usage/behaviour guide should not pin internal details that can change without notice. Three to drop from storage.mdx:

  1. The rendered storage_configuration block in the JBOD section — the main volume name is an internal template detail, not a contract. The prose below it (round-robin across all disks, capacity = sum) is what users actually rely on.
  2. The generated filename 10-storage-jbod.yaml — internal config.d plumbing. "Generates the storage_configuration for you" is enough.
  3. The verbatim webhook warning string — describe the behaviour instead of quoting the message text, which is free to change.

Everything else — mount paths, the hyphen→underscore identifier rule, immutability rules, and the validation table — is the right level for a behaviour guide.

Note: this review was AI-generated.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants