DOC-2335: Document Console UI for API-mode Schema Registry replication - #1843
DOC-2335: Document Console UI for API-mode Schema Registry replication#1843micheleRP wants to merge 7 commits into
Conversation
Console 3.9.0 added create, edit, and detail views for API-mode Schema Registry replication on shadow links. The page covered only the rpk and configuration-file path, so none of the UI was documented. Add to migrate-schemas-confluent.adoc: - Prerequisites: Redpanda Console v3.9.0, and the cluster version gate. The fields appear only when the shadow cluster reports Redpanda 26.2.0 or later; older clusters fall back to the legacy _schemas toggle. - A Console section with the create-wizard walkthrough in UI order. - A table mapping Console field names to configuration keys, so readers can move between the UI and the config file. - Edit constraints: no direct Redpanda <-> Other switch, discarded credentials on mode change, retained _schemas shadow topic, and password fields that stay empty to preserve the stored secret. - Console coverage in Verify the configuration, alongside rpk. All Console content is guarded with ifndef::env-cloud[] because Cloud UI is still feature-flagged pending Cloud API support (DOC-2336). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
✅ 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 adds non-cloud-specific Redpanda Console guidance for configuring and verifying Confluent Schema Registry replication. It documents Console version and cluster prerequisites, API-mode shadow link creation, field-to-configuration mappings, editing constraints, and the read-only Schema Registry details shown during verification. Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc (1)
346-355: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winKeep the
Use rpkconditional aligned with its content.In Cloud builds, lines 347-348 suppress the subsection heading while lines 350-355 still render the command and description. Either guard the entire subsection through line 355, or remove the conditional around the heading if
rpkguidance should remain in Cloud output.🤖 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/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc` around lines 346 - 355, Align the env-cloud conditional in the “Use rpk” subsection by wrapping the heading, command block, and descriptive text through the final reference sentence, or remove the conditional entirely if this guidance should appear in Cloud builds; keep the subsection content behavior consistent.
🧹 Nitpick comments (1)
modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc (1)
266-271: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse title-resolving xrefs for the new links.
Use empty xref brackets so published link text follows the target title automatically:
-xref:console:index.adoc[Redpanda Console] +xref:console:index.adoc[] ... -See xref:manage:disaster-recovery/shadowing/setup.adoc#create-a-shadow-link[Configure Shadowing]. +See xref:manage:disaster-recovery/shadowing/setup.adoc#create-a-shadow-link[].Based on learnings, AsciiDoc links should prefer empty brackets rather than hard-coded display 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/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc` around lines 266 - 271, Update the new xref links in the schema replication documentation to use empty link-text brackets, allowing each target page’s title to provide the published text automatically. Apply this to the Redpanda Console reference and the Configure Shadowing reference while preserving their existing targets.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/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc`:
- Around line 333-335: Revise the final bullet about the _schemas shadow topic
to warn that deleting it is destructive and can discard the shadow cluster’s
Schema Registry state. Instruct users to retain the topic unless they have an
intentional failover or backup plan and explicitly mean to discard the
replicated schemas.
---
Outside diff comments:
In
`@modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc`:
- Around line 346-355: Align the env-cloud conditional in the “Use rpk”
subsection by wrapping the heading, command block, and descriptive text through
the final reference sentence, or remove the conditional entirely if this
guidance should appear in Cloud builds; keep the subsection content behavior
consistent.
---
Nitpick comments:
In
`@modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc`:
- Around line 266-271: Update the new xref links in the schema replication
documentation to use empty link-text brackets, allowing each target page’s title
to provide the published text automatically. Apply this to the Redpanda Console
reference and the Configure Shadowing reference while preserving their existing
targets.
🪄 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: 0e868703-e05d-446a-b5df-4398c162c8af
📒 Files selected for processing (1)
modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc
Splitting "Verify the configuration" into rpk and Console subsections replaced the colon that introduced the rpk command with a period. In the Self-Managed build the new "Use rpk" heading sits between them, so a period reads correctly. The Cloud build excludes that heading, which would leave a sentence ending in a period followed directly by a code block. Make the lead-in conditional so the Cloud build keeps the colon. No Cloud stub includes this page yet, so this is a no-op today and matters when DOC-2336 adds one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Self-review of the Console procedure found three problems: The authentication and TLS steps contradicted each other. The authentication step read as mandatory HTTP basic, and the following TLS step then offered mTLS "instead" - so an mTLS reader had already entered basic credentials before learning not to. Make authentication a single step with both methods as explicit alternatives, and leave TLS as a separate step. Confirmed against schema-registry-request.ts at v3.9.0 that selecting None omits auth_options, which matches the mTLS guidance in the configuration reference. "Press Enter" was the only plain-text key name in the repo. Use the kbd:[Enter] macro, consistent with benchmark.adoc and local-guide.adoc. The TLS step claimed to be conditional on the source registry using HTTPS. That condition was unverified, so describe what the setting does instead of when to turn it on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Six strings that Redpanda Console displays were marked as code: Set, Not set, Custom CA, System trust store, Cluster defaults, and Entire Schema Registry. Monospace signals code, config keys, and commands, so bold is correct for UI text. This also removes two inconsistencies: one sentence in the TLS row switched markers mid-way (Enabled bold, Custom CA monospace), and Entire Schema Registry was bold in the procedure and mapping table but monospace in this one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The edit-constraints bullet mirrored Console's own warning text, which offers failover and topic deletion as equivalent ways to stop shadowing the _schemas topic. They are not equivalent: in topic mode the shadow _schemas topic backs the shadow cluster's Schema Registry, so deleting it discards the replicated schemas while failing over does not. Name the consequence and point readers at failover when they need to keep the schemas. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Yes, no auth is supported. SGTM to add it as an explicit authentication option in the docs. 🙏 |
|
|
||
| You can change the schema replication settings of an existing link in Redpanda Console, with the following constraints: | ||
|
|
||
| * You cannot switch directly between *Redpanda* and *Other*. To change between these modes, select *None*, save the link, then select the mode you want. Redpanda Console locks the unavailable tab. |
There was a problem hiding this comment.
Is better to not document this. Switching between modes is not allowed by Redpanda, and the API will fail if you do this.
There was a problem hiding this comment.
Removed the None round-trip in 2b6a258. The bullet now reads:
You cannot switch an existing link directly between Redpanda and Other. Redpanda Console locks the unavailable tab. To use a different Schema Registry replication mode, create a new shadow link.
I kept a one-line statement of the constraint because the locked tab is visible in the UI and readers will ask why it is locked. One thing to confirm: is "create a new shadow link" the right guidance to give here?
A small heads-up while you're in this code: the edit section in v3.9.0 still describes the round-trip as a supported route ("the link must go through None (and a save) first. From None both modes are reachable."), and the locked-tab hint reads "Switching between Redpanda and Other isn't supported." Might be worth aligning that comment and hint text with the actual behavior so the next reader of the file doesn't reach the same conclusion I did.
| * You cannot switch directly between *Redpanda* and *Other*. To change between these modes, select *None*, save the link, then select the mode you want. Redpanda Console locks the unavailable tab. | ||
| * Switching away from *Other* discards the stored Schema Registry connection settings, including credentials, scope, and sync behavior. Redpanda Console warns you before you save. | ||
| * Turning off *Redpanda* mode does not remove a `_schemas` shadow topic that the link already added. To stop shadowing that topic, fail over the link, or delete the shadow topic after you save. Deleting the topic also discards the schemas that the link replicated into it, so fail over instead if you need to keep them. | ||
| * Redpanda Console never populates a password field with the stored value. Leave the field empty to keep the existing credential, or enter a new value to replace it. |
There was a problem hiding this comment.
Right now, Console always asks for the Password on updates. So leaving the field empty will also ask for the credentials; I think we should remove this.
There was a problem hiding this comment.
Yes, replaced in 2b6a258. Verified: addSrBasicAuthIssues in create/model.ts at v3.9.0 raises "Password is required when HTTP Basic is enabled" for any api-mode form with HTTP Basic selected, and the edit page uses the same FormSchema (the password-exempt FormSchemaWithoutSchemaRegistryRules applies only while the feature gate is closed). The old bullet described rpk shadow update, which does accept an empty password to keep the stored one; Console does not share that behavior.
New wording:
When you edit a link that uses HTTP Basic, Redpanda Console requires you to re-enter the Password. It never populates the field with the stored value, and it does not accept an empty field.
While checking this I also corrected the read-only detail card in the verification section, which is a different code path: formatPasswordStatus has a third state, so Password is now documented as Set, Not set, or the date it last changed, and the card's "No authentication configured." case is covered now that no-auth is documented.
Yes.
It will come in a later release. |
Document unauthenticated access to the source Schema Registry, confirmed supported by the backend in review. Widen the Limitations bullet, add the rpk case (omit auth_options with no client certificate), make *None* a real authentication choice in the Console procedure, and map it to the omitted auth_options key. Correct two Console edit constraints. Drop the *None* round-trip as the way to change Schema Registry replication mode: switching modes on an existing link is not supported, so point readers at a new link instead. Replace the password bullet, since Console requires the password to be re-entered whenever an api-mode link uses HTTP Basic (addSrBasicAuthIssues in create/model.ts at v3.9.0) and rejects an empty field. Also correct the detail-card Authentication row: formatPasswordStatus has a third state (the date the password last changed), and the card reports that no authentication is configured when the link does not use HTTP Basic. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
@pgellert Thanks. Documented in 2b6a258:
|
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Docs team standards review (automated final pass)
Files reviewed: 1 .adoc file (+117 lines net, 6 commits)
Overall assessment: Excellent shape — the PR has already absorbed three reviewers' feedback with source-cited fixes, and independent verification passes clean. Nothing critical.
Independent verification
- Both build variants render structurally clean. Rendered the full page with asciidoctor in self-managed and cloud modes: the cloud variant collapses exactly to the original page shape — no orphaned headings, no empty Verify section, and the commit-2 colon fix does its job. This gating quality matters because DOC-2336's future stub will consume this page.
- Console 3.9.0 claim verified — console#2557 ("UX: New Schema Registry Sync options in Shadow Link (Create Only)") is merged.
- Cloud xref targets pre-verified for DOC-2336: cloud-docs has
rpk-shadowreference pages, so the cloud build'srpk shadow describexrefs will resolve once a stub exists.
Suggestion (non-blocking)
- [PR body, "What this adds"] The summary bullets still describe pre-review content: "No direct Redpanda <-> Other switch (route through None and save)" and "password fields stay empty to preserve the stored secret" — both reversed by 2b6a258. The "Review outcomes" section is correct, so the body currently contradicts itself; worth a quick edit so the squash commit doesn't preserve the stale claims.
Before merging
- Rogger's confirmation is still pending on the open question: is "create a new shadow link" the right guidance for changing replication mode?
Follow-ups
- Console repo: the v3.9.0 edit-page text still describes the unsupported None round-trip as a valid path (as noted on the thread) — worth confirming a console issue exists for that UI bug.
- DOC-2336: since Cloud UI is feature-flagged off pending Cloud API support, the Cloud slice waits on the flag — though wiring the cloud-docs stub for this page (whose rpk/config content is cloud-valid, with the Console sections self-gating) could land earlier as scoped work on that ticket.
What works well
- The review loop here is a model: every correction cites Console source at the shipped tag (
schema-registry-request.ts,addSrBasicAuthIssuesincreate/model.ts), and Console's own misleading warning text was caught rather than mirrored. - The cloud gating anticipates DOC-2336 precisely — commit 2 fixed a cloud-rendering artifact on a page no cloud build even consumes yet.
- The field-mapping table (UI labels → config keys) is exactly the artifact readers need to move between interfaces.
🤖 Generated with Claude Code
5 participants
Documents the Redpanda Console UI for API-mode Schema Registry replication on shadow links, shipped in Console 3.9.0 (2026-07-23) via console#2557, console#2564, and console#2569.
DOC-2254 documented the whole configuration surface, but only through
rpkand the configuration file. None of the Console UI was covered, and there is noRedpanda Consolepath anywhere in the shadowing docs today.Jira: https://redpandadata.atlassian.net/browse/DOC-2335
What this adds to
migrate-schemas-confluent.adoc_schemastoggle and API mode is unavailable. This is the likely "why can't I see this field?" support question.Configure schema replication in Redpanda Console: the create-wizard walkthrough in UI order, cross-referencing the existing configuration sections for the scope, context-mapping, and validation-policy semantics rather than restating them.Console fields and configuration keys: a mapping table, because the UI labels do not match the configuration keys (for example, the mode tabs are Redpanda / Other / None, notshadow_schema_registry_topic/shadow_schema_registry_api).Edit an existing shadow link: constraints that exist only in the UI and are not inferable from the configuration reference. No direct Redpanda <-> Other switch (route through None and save); switching away from Other discards stored credentials, scope, and sync behavior; turning off Redpanda mode leaves an already-added_schemasshadow topic in place; password fields stay empty to preserve the stored secret.Verify the configuration: split intoUse rpkandUse Redpanda Console, documenting the read-only Schema Registry detail card.Placement rationale
Extended the existing page rather than adding a new one. The reader's job is unchanged (replicate schemas from a Confluent registry); Console vs
rpkis a change of interface. A separate Console page would duplicate all four semantic blocks the page already owns, which is where drift starts.Used a dedicated section rather than
rpk::/Redpanda Console::tabs. The existing tab blocks in these pages are all insideifdef::env-cloud[], so there is no Self-Managed tab precedent to match, and tabs would restate the semantics four times. Happy to convert if reviewers prefer tabs for consistency withsetup.adoc.Single-sourcing
All Console content is wrapped in
ifndef::env-cloud[]. Cloud UI ships the same code but feature-flagged off pending Cloud API support, so this must not surface in cloud-docs yet. Tracked separately in DOC-2336. cloud-docsmainhas no copy of this page today, so there is nothing to verify on the Cloud side.Review outcomes
All three questions raised for review are answered. The resulting changes are in 2b6a258.
Backend contract - @pgellert
Fully unauthenticated access to the source Schema Registry is supported. The page now documents it in four places: None is a first-class authentication choice in the Console procedure (not just the route to mTLS), the configuration-file section covers the case (omit
auth_options, no client certificate), the field mapping table maps None to an omittedauth_options, and the Limitations bullet is widened accordingly.Console UI - @r-vasquez
Two further corrections came out of verifying the review feedback:
rpk shadow updatebehavior, which Console does not share.Verification
npm run buildis clean: no warnings or errors for this page.Preview pages
🤖 Generated with Claude Code