Schema Registry contexts: SerDes client support via URL prefix (DOC-2397, DOC-2304) - #1850
Conversation
…ix (DOC-2397, DOC-2304) - Add "Use contexts with SerDes clients" section: URL-prefix pattern, endpoint coverage, automatic ID-lookup scoping, name normalization, ACL behavior, and the silent-failure gotcha when qualified parsing is inactive - Update client integration table: Non-Java SerDes now supported via URL prefix (was "Not supported / workaround"); Java no longer requires ContextNameStrategy - Cloud (DOC-2304): BYOC/Dedicated text updated from "contact support to enable" to enabled-by-default with opt-out - Fix subject audit grep: affected names start with ':.' not '.' - Version-condition the "set the property first" instruction on the API page (26.2 default is true) - Add 26.2 release-notes entry Co-Authored-By: Claude Fable 5 <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 now describes Schema Registry contexts as enabled by default in Redpanda v26.2 and env-cloud deployments, with version-specific configuration guidance for earlier or opted-out deployments. It documents context-scoped URL prefixes for Schema Registry and SerDes clients, updates Java and non-Java integration status, clarifies schema ID lookup behavior, and adds URL validation, troubleshooting, upgrade-audit, and cloud configuration guidance. Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
![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
🤖 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/schema-reg/schema-reg-contexts.adoc`:
- Around line 745-752: Revise the diagnostic guidance around the /contexts curl
check so a response of ["." ] is not presented as proof that qualified subject
parsing is disabled. In the schema-registry troubleshooting section, instruct
readers to verify the relevant configuration and restart state directly, or
register a probe schema in a non-default context before interpreting the result.
🪄 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: 2597342c-fed0-4b89-9525-526d65504e84
📒 Files selected for processing (3)
modules/get-started/pages/release-notes/redpanda.adocmodules/manage/pages/schema-reg/schema-reg-api.adocmodules/manage/pages/schema-reg/schema-reg-contexts.adoc
| To confirm, check whether the registry lists only the default context while clients are using qualified subjects or context URLs: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| curl -s http://localhost:8081/contexts | ||
| ---- | ||
|
|
||
| If the response is `["."]`, qualified subject parsing is not active. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Do not treat ["."] as proof that parsing is disabled.
Because contexts are listed only after a schema is registered, an enabled cluster with no non-default schemas also returns ["."]. Check the configuration and restart state directly, or register a probe schema in a non-default context before using this result diagnostically.
🤖 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/schema-reg/schema-reg-contexts.adoc` around lines 745 -
752, Revise the diagnostic guidance around the /contexts curl check so a
response of ["." ] is not presented as proof that qualified subject parsing is
disabled. In the schema-registry troubleshooting section, instruct readers to
verify the relevant configuration and restart state directly, or register a
probe schema in a non-default context before interpreting the result.
|
|
||
| ifndef::env-cloud[] | ||
| To use contexts, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the brokers. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions. | ||
| In Redpanda v26.2 and later, contexts are enabled by default. In earlier versions, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the brokers. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions. |
There was a problem hiding this comment.
@pgellert what is the behavior though on upgrade from 26.2. Does it flip to on, or in 26.2 it is only enabled by default in NEW cluster?
There was a problem hiding this comment.
It flips on in 26.2, existing clusters included, unless the flag was explicitly set to false pre-upgrade. It is planned to be deprecated in 26.3. This config was always a temporary feature flag to give customers more flexibility for when they opt into this necessary breaking change that we need to support contexts. It was off in 26.1 purely to ship contexts early for serverless and some customers that have opted in early. I've re-confirmed no RP Cloud clusters use that pattern, and for self-hosted it's going to be called out loudly in the release notes and upgrade docs.
|
|
||
| ifdef::env-cloud[] | ||
| NOTE: On BYOC and Dedicated clusters, contact Redpanda support or use the cluster configuration API to enable `schema_registry_enable_qualified_subjects`. This property requires a broker restart. | ||
| NOTE: On BYOC and Dedicated clusters, Schema Registry contexts are enabled by default. To opt out, use the cluster configuration API or contact Redpanda support to set `schema_registry_enable_qualified_subjects` to `false`. This property requires a broker restart. |
There was a problem hiding this comment.
Same question here @pgellert . cc @Feediver1
|
|
||
| ifndef::env-cloud[] | ||
| To use contexts, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the brokers. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions. | ||
| In Redpanda v26.2 and later, contexts are enabled by default. In earlier versions, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the brokers. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions. |
There was a problem hiding this comment.
It flips on in 26.2, existing clusters included, unless the flag was explicitly set to false pre-upgrade. It is planned to be deprecated in 26.3. This config was always a temporary feature flag to give customers more flexibility for when they opt into this necessary breaking change that we need to support contexts. It was off in 26.1 purely to ship contexts early for serverless and some customers that have opted in early. I've re-confirmed no RP Cloud clusters use that pattern, and for self-hosted it's going to be called out loudly in the release notes and upgrade docs.
Version references on the contexts page now consistently use the v-prefixed form (matching the applied review suggestions). The GET /contexts example response showed named contexts without the dot prefix. Verified on a live v26.2.1 cluster (docker, dev-container mode): named contexts are returned dot-prefixed, e.g. [".",".production",".staging"]. The same experiment confirmed the new SerDes section end to end: URL-prefix registration, prefix-scoped ID lookup, unscoped lookup 404, and ["."] on a cluster with no named contexts. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Per Gellert: the flag flips on at upgrade for existing clusters (unless explicitly set false pre-upgrade); state this in the upgrade-considerations breaking-change block, the release notes, and a new 26.2 entry in the incompatible-changes partial (rolling-upgrade + k-rolling-upgrade pages) - Note that opting out is a stopgap: the flag is planned for removal in a future release - Per CodeRabbit: ["."] from GET /contexts is not proof that parsing is off (an enabled registry with no named-context schemas returns the same); rework the troubleshooting check to confirm via property state or a test-schema probe, with cleanup guidance Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Review feedback addressed in 4d09fb9:
🤖 Generated with Claude Code |
ReviewNice work on this one. No critical issues — findings below are polish, plus one Cloud-path rendering regression worth fixing before merge. Also reviewed the companion cloud-docs#654; its findings are posted there. Jira alignmentDOC-2397 — fully addressed. Everything in the research report's recommendations landed: SerDes section with URL pattern, endpoint coverage, ID-lookup scoping, normalization, version availability; client table row corrected; silent-failure gotcha in troubleshooting; API page version-conditioned. DOC-2304 — fully addressed, and it honors Kat's DOC-2192 note: the self-managed default-flip wording from #1784 is untouched, only the cloud-gated path changed. Before mergingThe timing gate you flagged on cloud-docs#654 applies here too, not just to the What's New entry: the "enabled by default" claim reaches Cloud through this PR as well, via the Merge order in the PR body (this PR, then cloud-docs#654) is correct for the anchor dependency. Suggestions1. The text accepts Suggested: "Aside from these leading and trailing delimiters, a context name that contains a colon ( 2. Verified by rendering the block with Fix: move the label outside the conditional, or add an 3. Also verified by rendering: with no blank line after the 4. It reads "After enabling 5. "…property is set to 6. Zero other occurrences. The established pattern for key=value config here is 7. It says only that the default changed from Impact on other filesChecked the ripple targets — nothing blocks merge:
CodeRabbitOne actionable item: don't present What works well
|
Per Michele's review findings 2 and 3: the bolded label now sits outside the env-cloud conditional so the Cloud build keeps it, and the blank line inside the conditional splits the self-managed text into two paragraphs instead of a run-on. Verified by rendering both variants with asciidoctor 2.0.26. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
@micheleRP findings 2 and 3 are fixed in cc826ab: the
Findings 1, 4, and 5 are noted and pending a separate decision. 🤖 Generated with Claude Code |
- Colon rule reworded so it no longer contradicts the accepted URL forms (leading/trailing colons are delimiters, verified against the context_router normalization tests) - Limitations bullet now reflects the automatic default flip on upgrade instead of opt-in framing - Prerequisites bullet: "is set to true" -> "is enabled" - [source,properties] -> [source,ini], matching the repo's established pattern (4 existing uses, properties had zero) - Changed-property-defaults release-notes bullet now states the upgrade behavior and links the upgrade considerations Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
@micheleRP the remaining suggestions (1, 4, 5, 6, 7) are implemented in bff2c3a — each was verified before changing:
Also noted your impact finding about the stale 🤖 Generated with Claude Code |
4 participants
Summary
Documents the v26.2 SerDes support for Schema Registry contexts: any SerDes client, in any language, can target a context by pointing
schema.registry.urlat a/contexts/{context}URL prefix — no client-side context support needed.Covers both tickets in one PR since both affected pages are single-sourced into cloud-docs:
Changes
schema-reg-contexts.adoc(single-sourced)[#serdes-clients]section: URL-prefix pattern with client config example, endpoint families covered, automatic schema-ID-lookup scoping, prefix/qualified-subject equivalence example, context-name normalization rules, ACL behavior, and an IMPORTANT callout for the silent-failure mode (qualified parsing inactive →/contexts/requests silently store literal subjects)ContextNameStrategyGET /contextsquick checkgrep '^\.'→grep '^:\.'(both occurrences). Only names starting with:.are affected by the breaking change;.foostays literal. The old pattern missed affected subjects and false-positived unaffected ones.schema-reg-api.adoc(single-sourced)true); cloud variant updated to enabled-by-defaultrelease-notes/redpanda.adocCompanion cloud-docs PR (What's New entry): redpanda-data/cloud-docs#654 — merge this PR first (the What's New entry links the
#serdes-clientsanchor, which reaches cloud-docs through the single-source include).Verification
service.ccat v26.1.7, absent at v26.1.6 (hence the "26.1.7 and later" version note)🤖 Generated with Claude Code
Preview pages