Document Tiered Storage v2 (26.2)#1813
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThe documentation introduces Tiered Storage v1 and v2 selection for Redpanda v26.2. It documents the cluster default and read-only topic implementation properties, version-specific compaction behavior, broker upgrade requirements, storage-mode conversion rules, Cloud Topic limitations, and updated topic configuration output. Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
modules/develop/pages/manage-topics/config-topics.adoc (1)
163-210: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy liftMake the local-to-Tiered example safe when the cluster default is v2.
The matrix marks
local→tiered (v2)as disallowed, but the example sets onlyredpanda.storage.mode=tiered; that alias resolves usingdefault_redpanda_storage_mode_tiered_impl. If the cluster default istiered_v2, the command attempts the prohibited transition. State that the example requires atiered_v1default, or document the supported migration path.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@modules/develop/pages/manage-topics/config-topics.adoc` around lines 163 - 210, Update the local-to-Tiered Storage example and surrounding guidance to state that it is valid only when default_redpanda_storage_mode_tiered_impl is set to tiered_v1, or provide the supported explicit migration path. Ensure the example cannot imply that redpanda.storage.mode=tiered is safe when the cluster default resolves to tiered_v2.
🧹 Nitpick comments (1)
modules/reference/partials/properties/cluster-properties.adoc (1)
5093-5095: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse an empty xref target.
Replace the hard-coded link text with
xref:manage:tiered-storage.adoc#tiered-storage-versions[]so the displayed title stays synchronized with the target heading.Suggested change
- * xref:manage:tiered-storage.adoc#tiered-storage-versions[Choose a Tiered Storage version] + * xref:manage:tiered-storage.adoc#tiered-storage-versions[]Based on learnings, AsciiDoc xrefs should use empty brackets when the target title can provide the link text.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@modules/reference/partials/properties/cluster-properties.adoc` around lines 5093 - 5095, Update the Related topics xref in the cluster properties documentation to use an empty link-text suffix, changing the hard-coded “Choose a Tiered Storage version” label to rely on the target heading while preserving the existing target anchor.Source: Learnings
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@modules/manage/partials/tiered-storage.adoc`:
- Around line 1006-1016: Scope all Tiered Storage compaction guidance by
version: in modules/manage/partials/tiered-storage.adoc lines 1006-1016 and the
later remote-compaction guidance at lines 1063-1065, label remote compaction,
full-partition compaction, and tombstone removal as Tiered Storage v2 behavior
while preserving v1 limitations. In
modules/manage/pages/cluster-maintenance/compaction-settings.adoc lines 113-117,
scope retention restrictions and tombstone-removal instructions to v1 and
document the supported v2 configuration.
---
Outside diff comments:
In `@modules/develop/pages/manage-topics/config-topics.adoc`:
- Around line 163-210: Update the local-to-Tiered Storage example and
surrounding guidance to state that it is valid only when
default_redpanda_storage_mode_tiered_impl is set to tiered_v1, or provide the
supported explicit migration path. Ensure the example cannot imply that
redpanda.storage.mode=tiered is safe when the cluster default resolves to
tiered_v2.
---
Nitpick comments:
In `@modules/reference/partials/properties/cluster-properties.adoc`:
- Around line 5093-5095: Update the Related topics xref in the cluster
properties documentation to use an empty link-text suffix, changing the
hard-coded “Choose a Tiered Storage version” label to rely on the target heading
while preserving the existing target anchor.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e0b06177-beab-4626-81c7-21f9b9245799
📒 Files selected for processing (7)
modules/develop/pages/manage-topics/config-topics.adocmodules/develop/partials/cloud-topics-limitations.adocmodules/manage/pages/cluster-maintenance/compaction-settings.adocmodules/manage/partials/tiered-storage.adocmodules/reference/partials/properties/cluster-properties.adocmodules/reference/partials/properties/topic-properties.adocmodules/reference/partials/properties/topic-property-mappings.adoc
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
PR Review: Document Tiered Storage v2 (26.2) (#1813)
Files reviewed: 7 (Tiered Storage partial, topic config guide, compaction page, Cloud Topics limitations partial, 3 property-reference partials)
Overall assessment: Technically strong, SME-authored content — the v1/v2 model, comparison table, and restrictions are clear and internally consistent. Two process-level blockers before merge, plus ticket coordination needed with the docs team.
Critical issues (must fix)
- Wrong base branch: targets
main, but every claim says "Starting in Redpanda v26.2." GA is July 28; 26.2 content in this repo goes tobeta(as with every other 26.2 docs PR in flight). Merged to main, the new properties and version guidance publish on the current 26.1 site a week early. Fix: retarget tobeta. - Hand-edits to autogenerated property partials will be clobbered or duplicated by the 26.2 regen. The PR body honestly discloses this — but disclosure isn't a gate:
cluster-properties.adoc,topic-properties.adoc, andtopic-property-mappings.adocregenerate from source via the auto-docs pipeline, and these polished descriptions currently live only in the partials. Fix: port the descriptions into the doc-tools property overrides (docs-data/property-overrides.json) so the regen preserves them — in this PR or as an explicit pre-GA gate. The team has been bitten by exactly this before.
Ticket coordination (docs team)
No Jira ticket is linked, and this PR delivers into the scope of two open DOC tickets, both In Review and assigned to Joyce Fee:
- DOC-2208 (ENG-1100, Tiered Storage v2) — this PR's core subject.
- DOC-2203 (ENG-1169, TS-v2/CT migration) — this PR rewrites exactly that territory (the storage-mode transitions table and the new
cloud↔tiered_v2conversions).
Both tickets are labeled 26.3-Feature while this PR documents 26.2 shipping — please confirm the version story (26.2 vocabulary/properties slice ahead of a fuller 26.3 feature?) and link the tickets so the docs team doesn't independently draft against the same pages. cc @Feediver1
CodeRabbit findings — both legitimate, please address
- The
local→ Tiered Storage example is unsafe under atiered_v2cluster default:redpanda.storage.mode=tieredresolves viadefault_redpanda_storage_mode_tiered_impl, and this PR's own matrix markslocal → tiered (v2)as prohibited. The example needs a "requirestiered_v1default" qualifier or the explicit-path alternative — it's a contradiction within the PR's own model. - Pre-existing unqualified compaction statements now contradict the v1/v2 split (tiered-storage.adoc remote-compaction guidance ~L1063; compaction-settings.adoc retention restriction ~L113). The PR scoped some sites but not all — the remaining ones need version qualifiers.
Minor
- "newly-created topics" → "newly created topics."
What works well
- The alias-resolution model, upgrade behavior, no-cross-version-conversion restrictions, and read-only
implsemantics are documented completely and consistently. - Convention fluency is impressive for an engineering-authored PR:
config_refmacros, anchor style matching generated IDs, the new cluster property correctly placed outside theredpanda-cloudtag region, env-gated Related-topics block, glossterm usage. - The autogeneration disclosure in the PR body is exactly the right instinct — it just needs to become the overrides fix rather than a note.
🤖 Generated with Claude Code
|
@Lazin one question from the docs side to settle ticket scope: which parts of Tiered Storage v2 ship in 26.2 vs 26.3? Context: the docs team has two open tickets for this feature area — DOC-2208 (TS v2 / CT-architecture low-latency topics, ENG-1100) and DOC-2203 (migration to TS-v2/CT based on latency needs, ENG-1169) — and both are labeled 26.3, while this PR documents the properties as shipping in 26.2 ( Our working assumption: the |
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Please update as suggested in the pr-review feedback. Also, it is critical to know which version this hits: 26.2? 26.3? thx
Cover the tiered_v1/tiered_v2 storage mode vocabulary introduced in Redpanda 26.2: - Add "Choose a Tiered Storage version" section to the Tiered Storage page: v1/v2 differences (compaction scope and window, tombstone removal), version selection, and upgrade/conversion restrictions. - Document the new default_redpanda_storage_mode_tiered_impl cluster property and the read-only redpanda.storage.mode.impl topic property. - Update storage mode selection and transition rules in the topic configuration guide, including the new cloud <-> tiered (v2) conversions. - Scope the tombstone-removal limitation and the Cloud Topics conversion limitation to Tiered Storage v1. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4f9659d to
4a076be
Compare
- Port the new property descriptions into docs-data/property-overrides.json (default_redpanda_storage_mode_tiered_impl, redpanda.storage.mode.impl, and the alias-resolution paragraph on redpanda.storage.mode) so the auto-docs regen preserves them. - Qualify the local-to-tiered example: it requires the cluster default to resolve to tiered_v1, since local -> tiered (v2) is not permitted. - Scope the remaining unqualified compaction and tombstone-retention statements to Tiered Storage v1 (restrictions are lifted for v2): tiered-storage partial, compaction-settings page, and the delete.retention.ms / tombstone_retention_ms property descriptions. - Use empty xref targets for the "Choose a Tiered Storage version" links in Related topics so the text tracks the heading. - Fix "newly-created topics" -> "newly created topics". Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
@Feediver1 To answer the version question: everything ships in 26.2 — there is no 26.3 remainder for this feature on the engineering side. The Review feedback addressed in c2dc207, and the PR is retargeted:
|
Setting redpanda.storage.mode.impl on its own is valid only when it matches the cluster default. To select a version that differs from default_redpanda_storage_mode_tiered_impl, redpanda.storage.mode=tiered must be specified together with it. Update the examples and prose in the Tiered Storage partial, the topic configuration guide, the topic property reference, and the property override. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2 participants
Description
Documents Tiered Storage v2, introduced in Redpanda v26.2 (redpanda-data/redpanda#30966):
Choose a Tiered Storage versionsection on the Tiered Storage page: differences between v1 and v2 (compaction scope and window, tombstone removal), how to select a version, and upgrade/conversion restrictions.default_redpanda_storage_mode_tiered_implcluster property and read-onlyredpanda.storage.mode.impltopic property in the property reference.cloud↔tiered(v2) conversions.Note: the property reference partials (
cluster-properties.adoc,topic-properties.adoc,topic-property-mappings.adoc) are marked as autogenerated. The new entries follow the generated format, but the descriptions should also be added to the doc-tools overrides so the next auto-docs run doesn't overwrite or duplicate them.Related Jira tickets: DOC-2208, DOC-2203
Review deadline:
Page previews
All links verified rendering the new content in this preview (2026-07-20):
redpanda.storage.mode.implproperty)Note: the PR now targets
beta, so the preview paths above use/streaming/26.2/….