From 3c19d1690af948f0c35f024e5d61985745d463c3 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 6 Apr 2026 15:21:29 -0500 Subject: [PATCH 01/51] Create schema-reg-contexts.adoc First draft --- .../pages/schema-reg/schema-reg-contexts.adoc | 581 ++++++++++++++++++ 1 file changed, 581 insertions(+) create mode 100644 modules/manage/pages/schema-reg/schema-reg-contexts.adoc diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc new file mode 100644 index 0000000000..ae6b30b66f --- /dev/null +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -0,0 +1,581 @@ += Schema Registry Contexts +:description: Use Schema Registry contexts to create isolated namespaces for schemas, subjects, and configuration—enabling multi-tenant and multi-team deployments without separate Schema Registry instances. +:page-tags: [Schema Registry, contexts, multi-tenant, Serverless, Confluent compatibility] +// Learning objectives: +// - Understand what Schema Registry contexts are and when to use them. +// - Understand the qualified subject syntax (::). +// - Enable the feature using the cluster configuration property. +// - Configure contexts, including per-context mode and compatibility settings. +// - Apply ACLs to control access at the context level. +// - Identify updated metrics and the new cluster configuration property. +// - Resolve common issues related to upgrade and subject naming. + +// Single-sourcing tags: use ifdef/ifndef blocks for content that differs +// between self-managed and Redpanda Cloud. Cloud-only content is wrapped +// in ifdef::env-cloud[] ... endif::[] blocks. Self-managed-only content +// is wrapped in ifndef::env-cloud[] ... endif::[] blocks. + +Schema Registry contexts are namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance. +Each context maintains its own schema ID counter, mode, and compatibility settings. +Use contexts when you need to separate schema workloads by tenant, team, or environment—without deploying multiple Schema Registry instances. + +== When to use contexts + +Contexts are most useful in the following scenarios: + +* *Multi-tenant deployments* (including Serverless): Each tenant can have a dedicated context with its own schema ID space and configuration so that one tenant's schema activity cannot interfere with another's. +* *Multi-team deployments on a shared cluster*: Teams such as engineering, finance, and operations can register schemas independently under their own contexts without risking naming collisions or configuration drift. +* *Migrations from Confluent Schema Registry*: Confluent SR uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. +* *Disaster recovery and schema syncing*: Dedicated namespaces reduce collision risk when syncing schemas across clusters. + +== Prerequisites + +Before using Schema Registry contexts, ensure that: + +* You are running Redpanda *26.1 or later*. +* The `schema_registry_enable_qualified_subjects` cluster configuration property is set to `true`. ++ +ifndef::env-cloud[] +[NOTE] +==== +In 26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it for self-managed clusters or to test in a non-Serverless environment. In 26.2, the property defaults to `true`. +==== +endif::env-cloud[] ++ +ifdef::env-cloud[] +[NOTE] +==== +On Serverless, contexts are enabled by default. On BYOC and Dedicated clusters, `schema_registry_enable_qualified_subjects` defaults to `false` in 26.1 and `true` in 26.2. Enable it to start using contexts before 26.2. +==== +endif::env-cloud[] + +* If you use Schema Registry ACLs, the principal interacting with a context has the appropriate permissions. See <>. + +== Limitations + +* *Console, rpk, and Kubernetes Operator*: Support for contexts in the Redpanda Console UI, `rpk` CLI, and Kubernetes Operator is not available in 26.1. Use the Schema Registry HTTP API directly. Console, rpk, and Operator support will be delivered in a subsequent release. +* *Cross-context isolation*: Contexts provide organizational isolation (separate ID spaces, subject namespaces, and configuration), not full data isolation. Schemas in one context can reference schemas in another context. +* *Blocking cross-context references*: There is no mechanism to prevent cross-context schema references. +* *DR/RPCN syncing into specific contexts*: Syncing schemas from remote clusters directly into a named context is not yet supported. +* *WASM integration*: Context-aware schema IDs are not yet surfaced in WASM data transforms. +* *Breaking change on upgrade*: After enabling `schema_registry_enable_qualified_subjects`, any existing subject whose name matches the qualified subject pattern `::` (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging` rather than as a literal subject name in the default context. See <>. + +ifndef::env-cloud[] +[NOTE] +==== +No enterprise license is required to use contexts. Contexts are fully functional in the open-source Redpanda build. +==== +endif::env-cloud[] + +== How Schema Registry contexts work + +Redpanda Schema Registry previously maintained a flat namespace: all schemas shared a single global schema ID counter and a single set of mode and compatibility settings (with optional per-subject overrides). Contexts extend this model by introducing named namespaces. Each context has its own schema ID counter that increments independently of other contexts, plus its own mode and compatibility settings. + +Contexts are referenced in the API using a *qualified subject* syntax: + +---- +:: +---- + +For example, `:.production:user-events-value` identifies subject `user-events-value` in context `.production`. Context names begin with a dot (`.`). Unqualified subjects (for example, `user-events-value`) are unchanged and continue to belong to the *default context* (represented as `.:` or simply an absence of context prefix), ensuring full backward compatibility. + +A *global context* (`\__GLOBAL`) provides the lowest-priority fallback for mode and compatibility settings. The resolution order for configuration lookup is: subject → context → global → built-in defaults. Setting a global context mode to `READONLY`, for example, applies that mode to any subject or context that does not have its own explicit setting. + +Schema references within schema definitions follow the same rules: unqualified references resolve within the same context as the root schema; qualified references resolve in the explicitly named context. This enables patterns such as a shared `.shared` context that holds common types referenced by multiple team-specific contexts. + +== Enable Schema Registry contexts + +ifndef::env-cloud[] +To enable contexts on a self-managed cluster, set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`: + +[source,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +---- + +To verify the current setting: + +[source,bash] +---- +rpk cluster config get schema_registry_enable_qualified_subjects +---- +endif::env-cloud[] + +ifdef::env-cloud[] +[NOTE] +==== +On Serverless clusters, contexts are managed by Redpanda and enabled automatically per tenant. On BYOC and Dedicated clusters, contact Redpanda support or use the cluster configuration API to enable `schema_registry_enable_qualified_subjects`. +==== +endif::env-cloud[] + +== Configure Schema Registry contexts + +=== Qualified subject syntax + +Wherever the Schema Registry API accepts a subject—in path parameters, query parameters, or schema reference fields—you can supply a qualified subject instead of a bare subject name: + +[cols="1,2", options="header"] +|=== +| Syntax | Meaning + +| `::` | Subject `` in context ``. +| `:.production:user-events-value` | Subject `user-events-value` in context `.production`. +| `:.production:` | The context `.production` itself (empty subject name), used for context-level mode/config operations. +| `user-events-value` | Subject `user-events-value` in the default context (unchanged behavior). +|=== + +=== Register a schema in a context + +To register a schema in a named context, use the qualified subject form in the `POST /subjects/{subject}/versions` request: + +[source,bash] +---- +curl -s -X POST \ + http://localhost:8081/subjects/:.production:user-events-value/versions \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"schema": "{\"type\":\"record\",\"name\":\"UserEvent\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"action\",\"type\":\"string\"}]}"}' +---- + +The schema ID returned is unique within the `.production` context and independent of schema IDs in other contexts. + +=== List contexts + +To list all contexts that have been explicitly created (plus the default context), use the `GET /contexts` endpoint: + +[source,bash] +---- +curl -s http://localhost:8081/contexts +---- + +Example response: + +[source,json] +---- +[".","production","staging"] +---- + +NOTE: The default context is always included in the response, represented as `"."`. + +=== List subjects in a context + +To list all subjects within a specific context, use the `/contexts/{context}/subjects` endpoint or the `subjectPrefix` query parameter on `GET /subjects`: + +.List subjects within a context using the context path prefix +[source,bash] +---- +curl -s http://localhost:8081/contexts/.production/subjects +---- + +.List subjects using subjectPrefix (explicit context) +[source,bash] +---- +curl -s "http://localhost:8081/subjects?subjectPrefix=:.production:" +---- + +.List subjects across all contexts (wildcard) +[source,bash] +---- +curl -s "http://localhost:8081/subjects?subjectPrefix=:*:" +---- + +.List subjects in the default context only (default behavior without subjectPrefix) +[source,bash] +---- +curl -s http://localhost:8081/subjects +---- + +=== Set context-level mode + +Mode can be set at the context level by specifying a qualified subject with an empty subject name (`::`): + +[source,bash] +---- +# Set the .staging context to IMPORT mode +curl -s -X PUT \ + http://localhost:8081/mode/:.staging: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"mode": "IMPORT"}' +---- + +[source,bash] +---- +# Get the mode for the .staging context +curl -s http://localhost:8081/mode/:.staging: +---- + +=== Set context-level compatibility + +[source,bash] +---- +# Set compatibility for the .production context +curl -s -X PUT \ + http://localhost:8081/config/:.production: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"compatibility": "BACKWARD"}' +---- + +[source,bash] +---- +# Get compatibility for a specific subject within a context +curl -s http://localhost:8081/config/:.production:user-events-value +---- + +=== Set the global context fallback + +The `\__GLOBAL` context provides the lowest-priority fallback for all contexts and subjects that do not have their own explicit setting: + +[source,bash] +---- +# Set global default compatibility +curl -s -X PUT \ + http://localhost:8081/config/:__GLOBAL: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"compatibility": "FULL"}' +---- + +NOTE: `\__GLOBAL` and `\__EMPTY` are reserved names and cannot be used as regular context or subject names. + +=== Use a context as the base URL + +You can point a client at a specific context by setting the client's base URL to `${host}/contexts/{context}`. Redpanda rewrites requests under this path prefix to operate within the specified context automatically. For example: + +---- +# All requests to this base URL operate within the .production context +http://localhost:8081/contexts/.production +---- + +A client with this base URL making a `GET /schemas/ids/42` request would retrieve schema ID 42 from the `.production` context. + +=== Set a pre-configured mode on a non-existent context + +You can set mode or compatibility on a context before any schemas are registered in it. When the first schema is registered under that context, it immediately inherits the pre-configured settings: + +[source,bash] +---- +# Pre-configure a context that does not yet exist +curl -s -X PUT \ + http://localhost:8081/mode/:.new-team: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"mode": "READONLY"}' + +# Any attempt to register a schema in :.new-team: will now be rejected +# until the mode is changed to READWRITE +---- + +=== Delete a context + +A context can be deleted only when it has no subjects (or all subjects have been hard-deleted). Attempting to delete a non-empty context returns a `ContextNotEmpty` error. + +[source,bash] +---- +curl -s -X DELETE http://localhost:8081/contexts/.staging +---- + +=== Cross-context schema references + +Schemas can reference schemas in other contexts using qualified subject names in the `references` field: + +[source,json] +---- +{ + "schema": "...", + "references": [ + { + "name": "Address", + "subject": ":.shared:Address", + "version": 1 + } + ] +} +---- + +Unqualified references in schema definitions resolve to the same context as the root schema, not to the default context. + +== Cluster configuration property + +The following cluster configuration property controls whether qualified subject parsing is enabled. + +`schema_registry_enable_qualified_subjects`:: ++ +[cols="1,3"] +|=== +| Type | Boolean +| Default (26.1) | `false` +| Default (26.2+) | `true` +|=== ++ +When set to `false`, subjects are treated as literal strings (existing behavior). When set to `true`, subjects matching the `::` pattern are parsed as context-qualified subjects. ++ +ifndef::env-cloud[] +Configure using `rpk`: ++ +[source,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +---- +endif::env-cloud[] + +== rpk commands + +[NOTE] +==== +Native `rpk` commands for managing contexts (for example, listing, creating, or deleting contexts) are not available in 26.1. Use the Schema Registry HTTP API directly. rpk support for contexts will be delivered in a future release. +==== + +Existing `rpk registry` commands that accept a subject name already support qualified subject syntax once `schema_registry_enable_qualified_subjects` is enabled. Pass a qualified subject wherever a `--subject` flag is accepted: + +[source,bash] +---- +# Create a schema in a named context +rpk registry schema create \ + --subject ":.production:user-events-value" \ + --schema user-events.avsc \ + --type avro + +# List schemas for a subject in a named context +rpk registry schema list \ + --subject ":.production:user-events-value" + +# Get a specific schema version from a context +rpk registry schema get \ + --subject ":.production:user-events-value" \ + --version 1 + +# Check compatibility for a subject in a context +rpk registry schema check-compatibility \ + --subject ":.production:user-events-value" \ + --schema user-events-v2.avsc + +# Get the compatibility level for a context +rpk registry compatibility-level get \ + --subject ":.production:" + +# Set the compatibility level for a context +rpk registry compatibility-level set \ + --subject ":.production:" \ + --level BACKWARD + +# Get the mode for a context +rpk registry mode get \ + --subject ":.production:" + +# Set the mode for a context +rpk registry mode set \ + --subject ":.production:" \ + --mode READONLY + +# Delete a subject within a context +rpk registry subject delete \ + --subject ":.production:user-events-value" +---- + +For full reference documentation on these commands, see: + +* xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[rpk registry schema create] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-list.adoc[rpk registry schema list] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-get.adoc[rpk registry schema get] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc[rpk registry schema check-compatibility] +* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc[rpk registry compatibility-level get] +* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc[rpk registry compatibility-level set] +* xref:reference:rpk/rpk-registry/rpk-registry-mode-get.adoc[rpk registry mode get] +* xref:reference:rpk/rpk-registry/rpk-registry-mode-set.adoc[rpk registry mode set] +* xref:reference:rpk/rpk-registry/rpk-registry-subject-delete.adoc[rpk registry subject delete] +* xref:reference:rpk/rpk-registry/rpk-registry-subject-list.adoc[rpk registry subject list] + +== ACL authorization + +[#acl-authorization] + +Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. No new resource types are needed. + +=== Grant access to all subjects in a context + +Use a prefix ACL on `sr_subject` with the context prefix `::` to grant access to all subjects within a context: + +[source,bash] +---- +rpk security acl create \ + --allow-principal User:team-a \ + --operation read,write,describe \ + --registry-subject ":.team-a:" \ + --brokers +---- + +This ACL matches `:.team-a:*`, granting the principal access to every subject in the `.team-a` context. + +=== Context-level mode and config operations + +Context-level mode and compatibility (`PUT /mode/::` and `PUT /config/::`) require `sr_registry` permission with the `alter_configs` operation—consistent with global mode and config endpoints. + +Subject-level operations (`PUT /mode/::` and `PUT /config/::`) require `sr_subject` permission on the specific subject. + +=== Audit log format + +When Schema Registry ACLs are enabled, audit log entries include the fully qualified subject name for non-default context operations: + +[source,json] +---- +{ + "resources": [ + { + "name": ":.production:user-events-value", + "type": "subject" + } + ] +} +---- + +Default context subjects are logged with their unqualified name (no change from existing behavior). + +== Metrics + +The following Schema Registry metrics have been updated to include a `context` label, enabling per-context monitoring: + +[cols="2,2", options="header"] +|=== +| Metric | Change + +| `*_schema_registry_cache_schema_count` +| New `context` label added. + +| `*_schema_registry_cache_subject_count` +| New `context` label added. + +| `*_schema_registry_cache_subject_version_count` +| New `context` label added. +|=== + +For the full metrics reference, see xref:reference:public-metrics-reference.adoc[Public Metrics Reference]. + +== Upgrade considerations + +[#upgrade-considerations] + +[IMPORTANT] +==== +*Breaking change*: When `schema_registry_enable_qualified_subjects` is enabled, any existing subject whose name matches the qualified subject pattern—for example, `:.staging:user-value`—is reinterpreted as subject `user-value` in context `.staging`, rather than as a literal subject name in the default context. Subjects without a `:.` prefix are unaffected. +==== + +This edge case is expected to be rare. To audit your existing subjects for affected names before enabling the feature: + +ifndef::env-cloud[] +[source,bash] +---- +rpk registry subject list | grep '^:\.' +---- +endif::env-cloud[] + +ifdef::env-cloud[] +[source,bash] +---- +curl -s http://:8081/subjects | jq '.[] | select(startswith(":."))' +---- +endif::env-cloud[] + +If affected subjects are found, rename them before enabling the property, or plan to rename them after enabling and re-register any schemas under the reinterpreted context structure. + +In 26.2, if you need additional time to migrate, you can temporarily set `schema_registry_enable_qualified_subjects` to `false` to preserve the existing literal behavior while you complete the migration. This option is removed in 26.3. + +== Troubleshooting + +=== Schema registration fails after upgrading to 26.1 + +*Symptom*: A `POST /subjects/{subject}/versions` request returns an unexpected error after upgrading. + +*Cause*: The subject name may contain a `:.` prefix that is now parsed as a context-qualified subject. If the inferred context was pre-configured in `READONLY` mode, new registrations are rejected. + +*Resolution*: Check whether the subject name matches the qualified pattern: + +ifndef::env-cloud[] +[source,bash] +---- +rpk registry subject list | grep '^:\.' +---- +endif::env-cloud[] + +Rename affected subjects if needed, or change the context mode: + +[source,bash] +---- +curl -s -X PUT http://localhost:8081/mode/:: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"mode": "READWRITE"}' +---- + +=== `GET /contexts` returns an empty list or does not include my context + +*Symptom*: A context that you believe exists does not appear in `GET /contexts`. + +*Cause*: A context is only listed after at least one schema has been registered in it (creating the internal `CONTEXT` record). Pre-configuring a mode or compatibility setting alone does not create a listed context. + +*Resolution*: Register a schema in the context to materialize it, or verify that at least one subject exists under the context. + +=== Qualified subjects not recognized (subjects treated as literal names) + +*Symptom*: Subjects with the `:.` prefix are stored as literal subject names in the default context rather than being parsed as context-qualified subjects. + +*Cause*: `schema_registry_enable_qualified_subjects` is set to `false` (the 26.1 default for self-managed clusters). + +*Resolution*: + +ifndef::env-cloud[] +[source,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +---- +endif::env-cloud[] + +=== Cross-context reference resolution fails + +*Symptom*: A schema registration that includes references to subjects in another context fails with a subject-not-found error. + +*Cause*: Unqualified references in schema definitions resolve within the same context as the root schema, not in the default context. + +*Resolution*: Use a fully qualified reference in the schema definition: + +[source,json] +---- +{ + "references": [ + { + "name": "Address", + "subject": ":.shared:Address", + "version": 1 + } + ] +} +---- + +=== Context cannot be deleted + +*Symptom*: `DELETE /contexts/{context}` returns a `ContextNotEmpty` error. + +*Cause*: The context still has subjects that have not been fully deleted (hard-deleted). + +*Resolution*: Delete all subjects within the context before deleting the context itself. Use a soft delete followed by a permanent (hard) delete: + +[source,bash] +---- +# Soft-delete the subject +curl -s -X DELETE \ + "http://localhost:8081/subjects/::" + +# Hard-delete the subject (permanent) +curl -s -X DELETE \ + "http://localhost:8081/subjects/::?permanent=true" +---- + +Repeat for each subject in the context, then retry the `DELETE /contexts/{context}` request. + +== Related topics + +* xref:manage:schema-reg/schema-reg-overview.adoc[Redpanda Schema Registry] +* xref:manage:schema-reg/schema-reg-api.adoc[Use the Schema Registry API] +* xref:manage:schema-reg/schema-reg-authorization.adoc[Schema Registry Authorization] +* xref:reference:public-metrics-reference.adoc[Public Metrics Reference] +ifndef::env-cloud[] +* xref:reference:cluster-properties.adoc[Cluster Configuration Properties] +endif::env-cloud[] +ifdef::env-cloud[] +* xref:reference:properties/cluster-properties.adoc[Cluster Configuration Properties] +endif::env-cloud[] From 51f0e5aab0ac16c987e2f1be4b8cb5be2128549f Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 6 Apr 2026 16:50:09 -0400 Subject: [PATCH 02/51] docs(DOC-1658): add Schema Registry Contexts to site nav Co-Authored-By: Claude Sonnet 4.6 --- modules/ROOT/nav.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index f6cdd63007..36118d2ef7 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -205,6 +205,7 @@ **** xref:manage:schema-reg/schema-reg-api.adoc[API] **** xref:manage:kubernetes/k-schema-controller.adoc[Kubernetes] *** xref:manage:schema-reg/schema-reg-authorization.adoc[Schema Registry Authorization] +*** xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts] *** xref:manage:schema-reg/schema-id-validation.adoc[] *** xref:console:ui/schema-reg.adoc[Manage in Redpanda Console] ** xref:manage:high-availability.adoc[High Availability] From 49a620cc06b551b14a8f9baf5485f81ee751b2f5 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 6 Apr 2026 22:22:19 -0500 Subject: [PATCH 03/51] First draft grimness Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index ae6b30b66f..d1da4287d4 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -21,24 +21,24 @@ Use contexts when you need to separate schema workloads by tenant, team, or envi == When to use contexts -Contexts are most useful in the following scenarios: +Contexts are most useful for: * *Multi-tenant deployments* (including Serverless): Each tenant can have a dedicated context with its own schema ID space and configuration so that one tenant's schema activity cannot interfere with another's. * *Multi-team deployments on a shared cluster*: Teams such as engineering, finance, and operations can register schemas independently under their own contexts without risking naming collisions or configuration drift. -* *Migrations from Confluent Schema Registry*: Confluent SR uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. +* *Migrations from Confluent Schema Registry*: Confluent Schema Registry uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. * *Disaster recovery and schema syncing*: Dedicated namespaces reduce collision risk when syncing schemas across clusters. == Prerequisites Before using Schema Registry contexts, ensure that: -* You are running Redpanda *26.1 or later*. +* You are running Redpanda *v26.1 or later*. * The `schema_registry_enable_qualified_subjects` cluster configuration property is set to `true`. + ifndef::env-cloud[] [NOTE] ==== -In 26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it for self-managed clusters or to test in a non-Serverless environment. In 26.2, the property defaults to `true`. +In 26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it for self-managed clusters or to test in a non-Serverless environment. ==== endif::env-cloud[] + From 0657a067c7f58dae9253d0b810b99280368bb32e Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Tue, 7 Apr 2026 19:08:16 -0500 Subject: [PATCH 04/51] Update modules/manage/pages/schema-reg/schema-reg-contexts.adoc --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index d1da4287d4..828204b8e3 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -45,7 +45,7 @@ endif::env-cloud[] ifdef::env-cloud[] [NOTE] ==== -On Serverless, contexts are enabled by default. On BYOC and Dedicated clusters, `schema_registry_enable_qualified_subjects` defaults to `false` in 26.1 and `true` in 26.2. Enable it to start using contexts before 26.2. +On Serverless, contexts are enabled by default. On BYOC and Dedicated clusters, `schema_registry_enable_qualified_subjects` defaults to `false`. ==== endif::env-cloud[] From 7566a77dfc4a9532c720a8524417ec5afa914907 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Tue, 7 Apr 2026 19:09:37 -0500 Subject: [PATCH 05/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 828204b8e3..4171c96200 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -15,9 +15,9 @@ // in ifdef::env-cloud[] ... endif::[] blocks. Self-managed-only content // is wrapped in ifndef::env-cloud[] ... endif::[] blocks. -Schema Registry contexts are namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance. +Schema Registry contexts provide namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance, providing unique schema ID spaces per context. Each context maintains its own schema ID counter, mode, and compatibility settings. -Use contexts when you need to separate schema workloads by tenant, team, or environment—without deploying multiple Schema Registry instances. +Use contexts when you need to separate schema workloads by tenant, team, or environment, and avoid having to deploy multiple Schema Registry instances. == When to use contexts @@ -38,7 +38,7 @@ Before using Schema Registry contexts, ensure that: ifndef::env-cloud[] [NOTE] ==== -In 26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it for self-managed clusters or to test in a non-Serverless environment. +Starting in v26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it for self-managed clusters or to test in a non-Serverless environment. ==== endif::env-cloud[] + @@ -49,27 +49,27 @@ On Serverless, contexts are enabled by default. On BYOC and Dedicated clusters, ==== endif::env-cloud[] -* If you use Schema Registry ACLs, the principal interacting with a context has the appropriate permissions. See <>. +* If you use Schema Registry ACLs, ensure that the principal interacting with a context has the appropriate permissions. See <>. == Limitations -* *Console, rpk, and Kubernetes Operator*: Support for contexts in the Redpanda Console UI, `rpk` CLI, and Kubernetes Operator is not available in 26.1. Use the Schema Registry HTTP API directly. Console, rpk, and Operator support will be delivered in a subsequent release. +* *Console, rpk, and Kubernetes Operator*: Do not support contexts in Redpanda v26.1. Use the Schema Registry HTTP API directly. * *Cross-context isolation*: Contexts provide organizational isolation (separate ID spaces, subject namespaces, and configuration), not full data isolation. Schemas in one context can reference schemas in another context. * *Blocking cross-context references*: There is no mechanism to prevent cross-context schema references. -* *DR/RPCN syncing into specific contexts*: Syncing schemas from remote clusters directly into a named context is not yet supported. +* *DR/RPCN syncing into specific contexts*: Syncing schemas from remote clusters directly into a named context is not supported. * *WASM integration*: Context-aware schema IDs are not yet surfaced in WASM data transforms. * *Breaking change on upgrade*: After enabling `schema_registry_enable_qualified_subjects`, any existing subject whose name matches the qualified subject pattern `::` (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging` rather than as a literal subject name in the default context. See <>. ifndef::env-cloud[] [NOTE] ==== -No enterprise license is required to use contexts. Contexts are fully functional in the open-source Redpanda build. +Schema Registry contexts does not require an enterprise license. ==== endif::env-cloud[] == How Schema Registry contexts work -Redpanda Schema Registry previously maintained a flat namespace: all schemas shared a single global schema ID counter and a single set of mode and compatibility settings (with optional per-subject overrides). Contexts extend this model by introducing named namespaces. Each context has its own schema ID counter that increments independently of other contexts, plus its own mode and compatibility settings. +Prior to v26.1, Redpanda Schema Registry maintained a flat namespace: all schemas shared a single global schema ID counter and a single set of mode and compatibility settings (with optional per-subject overrides). Schema Registry contexts extend this model by introducing named namespaces. Each context has its own schema ID counter that increments independently of other contexts, in addition to its own mode and compatibility settings. Contexts are referenced in the API using a *qualified subject* syntax: @@ -121,7 +121,7 @@ Wherever the Schema Registry API accepts a subject—in path parameters, query p | `::` | Subject `` in context ``. | `:.production:user-events-value` | Subject `user-events-value` in context `.production`. | `:.production:` | The context `.production` itself (empty subject name), used for context-level mode/config operations. -| `user-events-value` | Subject `user-events-value` in the default context (unchanged behavior). +| `user-events-value` | Subject `user-events-value` in the default context. |=== === Register a schema in a context @@ -140,7 +140,7 @@ The schema ID returned is unique within the `.production` context and independen === List contexts -To list all contexts that have been explicitly created (plus the default context), use the `GET /contexts` endpoint: +To list all contexts that have been explicitly created (in addition to the default context), use the `GET /contexts` endpoint: [source,bash] ---- @@ -186,7 +186,7 @@ curl -s http://localhost:8081/subjects === Set context-level mode -Mode can be set at the context level by specifying a qualified subject with an empty subject name (`::`): +You can configure mode at the context level by specifying a qualified subject with an empty subject name (`::`): [source,bash] ---- @@ -205,6 +205,8 @@ curl -s http://localhost:8081/mode/:.staging: === Set context-level compatibility + To configure context-level compatibility: + [source,bash] ---- # Set compatibility for the .production context From 24eb29dca09fb7bf3e6f5bb782a55e54d1bf96e9 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Tue, 7 Apr 2026 19:25:28 -0500 Subject: [PATCH 06/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 4171c96200..889560c5de 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -57,7 +57,7 @@ endif::env-cloud[] * *Cross-context isolation*: Contexts provide organizational isolation (separate ID spaces, subject namespaces, and configuration), not full data isolation. Schemas in one context can reference schemas in another context. * *Blocking cross-context references*: There is no mechanism to prevent cross-context schema references. * *DR/RPCN syncing into specific contexts*: Syncing schemas from remote clusters directly into a named context is not supported. -* *WASM integration*: Context-aware schema IDs are not yet surfaced in WASM data transforms. +* *WASM integration*: Context-aware schema IDs are not surfaced in WASM data transforms. * *Breaking change on upgrade*: After enabling `schema_registry_enable_qualified_subjects`, any existing subject whose name matches the qualified subject pattern `::` (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging` rather than as a literal subject name in the default context. See <>. ifndef::env-cloud[] @@ -266,7 +266,7 @@ curl -s -X PUT \ === Delete a context -A context can be deleted only when it has no subjects (or all subjects have been hard-deleted). Attempting to delete a non-empty context returns a `ContextNotEmpty` error. +You can only delete a context when it has no subjects (or all subjects have been hard-deleted). Attempting to delete a non-empty context returns a `ContextNotEmpty` error. [source,bash] ---- @@ -306,7 +306,7 @@ The following cluster configuration property controls whether qualified subject | Default (26.2+) | `true` |=== + -When set to `false`, subjects are treated as literal strings (existing behavior). When set to `true`, subjects matching the `::` pattern are parsed as context-qualified subjects. +When set to `false`, subjects are treated as literal strings. When set to `true`, subjects matching the `::` pattern are parsed as context-qualified subjects. + ifndef::env-cloud[] Configure using `rpk`: @@ -321,7 +321,7 @@ endif::env-cloud[] [NOTE] ==== -Native `rpk` commands for managing contexts (for example, listing, creating, or deleting contexts) are not available in 26.1. Use the Schema Registry HTTP API directly. rpk support for contexts will be delivered in a future release. +Native `rpk` commands for managing contexts (for example, listing, creating, or deleting contexts) are not available in v26.1. Use the Schema Registry HTTP API directly. ==== Existing `rpk registry` commands that accept a subject name already support qualified subject syntax once `schema_registry_enable_qualified_subjects` is enabled. Pass a qualified subject wherever a `--subject` flag is accepted: @@ -388,7 +388,7 @@ For full reference documentation on these commands, see: [#acl-authorization] -Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. No new resource types are needed. +Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. === Grant access to all subjects in a context @@ -427,7 +427,7 @@ When Schema Registry ACLs are enabled, audit log entries include the fully quali } ---- -Default context subjects are logged with their unqualified name (no change from existing behavior). +Default context subjects are logged with their unqualified name. == Metrics @@ -435,7 +435,7 @@ The following Schema Registry metrics have been updated to include a `context` l [cols="2,2", options="header"] |=== -| Metric | Change +| Metric | Update | `*_schema_registry_cache_schema_count` | New `context` label added. @@ -458,7 +458,7 @@ For the full metrics reference, see xref:reference:public-metrics-reference.adoc *Breaking change*: When `schema_registry_enable_qualified_subjects` is enabled, any existing subject whose name matches the qualified subject pattern—for example, `:.staging:user-value`—is reinterpreted as subject `user-value` in context `.staging`, rather than as a literal subject name in the default context. Subjects without a `:.` prefix are unaffected. ==== -This edge case is expected to be rare. To audit your existing subjects for affected names before enabling the feature: +While the necessity of doing so is rare, you can audit your existing subjects for affected names before enabling contexts: ifndef::env-cloud[] [source,bash] @@ -476,11 +476,10 @@ endif::env-cloud[] If affected subjects are found, rename them before enabling the property, or plan to rename them after enabling and re-register any schemas under the reinterpreted context structure. -In 26.2, if you need additional time to migrate, you can temporarily set `schema_registry_enable_qualified_subjects` to `false` to preserve the existing literal behavior while you complete the migration. This option is removed in 26.3. == Troubleshooting -=== Schema registration fails after upgrading to 26.1 +=== Schema registration fails after upgrading to v26.1 *Symptom*: A `POST /subjects/{subject}/versions` request returns an unexpected error after upgrading. @@ -516,7 +515,7 @@ curl -s -X PUT http://localhost:8081/mode/:: \ *Symptom*: Subjects with the `:.` prefix are stored as literal subject names in the default context rather than being parsed as context-qualified subjects. -*Cause*: `schema_registry_enable_qualified_subjects` is set to `false` (the 26.1 default for self-managed clusters). +*Cause*: `schema_registry_enable_qualified_subjects` is set to `false`, which is the default for self-managed clusters). *Resolution*: @@ -552,9 +551,9 @@ endif::env-cloud[] *Symptom*: `DELETE /contexts/{context}` returns a `ContextNotEmpty` error. -*Cause*: The context still has subjects that have not been fully deleted (hard-deleted). +*Cause*: The context still has subjects that have not been fully deleted (hard-delete). -*Resolution*: Delete all subjects within the context before deleting the context itself. Use a soft delete followed by a permanent (hard) delete: +*Resolution*: Delete all subjects within the context before deleting the context itself. Use a soft delete followed by a hard delete, which is permanent: [source,bash] ---- From b8de5b2b616fec5d2064524f38a531ac9db98f9b Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 9 Apr 2026 11:46:54 -0500 Subject: [PATCH 07/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 595 +++++++++++------- 1 file changed, 380 insertions(+), 215 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 889560c5de..20fef2c8e0 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -1,87 +1,137 @@ = Schema Registry Contexts :description: Use Schema Registry contexts to create isolated namespaces for schemas, subjects, and configuration—enabling multi-tenant and multi-team deployments without separate Schema Registry instances. -:page-tags: [Schema Registry, contexts, multi-tenant, Serverless, Confluent compatibility] +:page-tags: [Schema Registry, contexts, multi-tenant, Confluent compatibility] // Learning objectives: // - Understand what Schema Registry contexts are and when to use them. // - Understand the qualified subject syntax (::). -// - Enable the feature using the cluster configuration property. +// - Enable the feature using the cluster configuration property (requires broker restart). // - Configure contexts, including per-context mode and compatibility settings. // - Apply ACLs to control access at the context level. // - Identify updated metrics and the new cluster configuration property. -// - Resolve common issues related to upgrade and subject naming. +// - Resolve common issues related to upgrade, schema ID lookups, and subject naming. -// Single-sourcing tags: use ifdef/ifndef blocks for content that differs -// between self-managed and Redpanda Cloud. Cloud-only content is wrapped -// in ifdef::env-cloud[] ... endif::[] blocks. Self-managed-only content -// is wrapped in ifndef::env-cloud[] ... endif::[] blocks. +// Single-sourcing tags: Cloud-only content is wrapped in ifdef::env-cloud[] ... endif::[] +// Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] -Schema Registry contexts provide namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance, providing unique schema ID spaces per context. -Each context maintains its own schema ID counter, mode, and compatibility settings. -Use contexts when you need to separate schema workloads by tenant, team, or environment, and avoid having to deploy multiple Schema Registry instances. +Schema Registry contexts are namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance. +Each context maintains its own schema ID counter, mode settings, and compatibility settings. +Unqualified subjects continue to work unchanged in the implicit default context. + +This feature is compatible with the Confluent Schema Registry Contexts API and requires no enterprise license. == When to use contexts -Contexts are most useful for: +Contexts are most useful in the following scenarios: + +* *Multi-team deployments on a shared cluster*: Teams can register schemas independently under their own contexts without risking naming collisions or configuration drift. +* *Schema migration from Confluent Schema Registry*: Confluent SR uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. +* *Multi-cluster schema syncing and disaster recovery*: Dedicated namespaces reduce schema ID collision risk when syncing schemas across clusters. -* *Multi-tenant deployments* (including Serverless): Each tenant can have a dedicated context with its own schema ID space and configuration so that one tenant's schema activity cannot interfere with another's. -* *Multi-team deployments on a shared cluster*: Teams such as engineering, finance, and operations can register schemas independently under their own contexts without risking naming collisions or configuration drift. -* *Migrations from Confluent Schema Registry*: Confluent Schema Registry uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. -* *Disaster recovery and schema syncing*: Dedicated namespaces reduce collision risk when syncing schemas across clusters. +ifdef::env-cloud[] +NOTE: On Serverless clusters, Redpanda uses contexts internally for per-tenant isolation. Contexts are not exposed to end users on Serverless. On BYOC and Dedicated clusters, contexts are available and user-configurable. +endif::env-cloud[] == Prerequisites Before using Schema Registry contexts, ensure that: -* You are running Redpanda *v26.1 or later*. +* You are running Redpanda *26.1 or later*. * The `schema_registry_enable_qualified_subjects` cluster configuration property is set to `true`. + -ifndef::env-cloud[] -[NOTE] +[IMPORTANT] ==== -Starting in v26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it for self-managed clusters or to test in a non-Serverless environment. +`schema_registry_enable_qualified_subjects` is *not a dynamic property*. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is the most likely missing step. ==== -endif::env-cloud[] + -ifdef::env-cloud[] +ifndef::env-cloud[] [NOTE] ==== -On Serverless, contexts are enabled by default. On BYOC and Dedicated clusters, `schema_registry_enable_qualified_subjects` defaults to `false`. +In 26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it. In 26.2, the default changes to `true`. In 26.3, the property is removed and contexts are always enabled. ==== endif::env-cloud[] -* If you use Schema Registry ACLs, ensure that the principal interacting with a context has the appropriate permissions. See <>. +* If you use Schema Registry ACLs, ensure the principal interacting with a context has the appropriate permissions. See <>. == Limitations -* *Console, rpk, and Kubernetes Operator*: Do not support contexts in Redpanda v26.1. Use the Schema Registry HTTP API directly. -* *Cross-context isolation*: Contexts provide organizational isolation (separate ID spaces, subject namespaces, and configuration), not full data isolation. Schemas in one context can reference schemas in another context. -* *Blocking cross-context references*: There is no mechanism to prevent cross-context schema references. -* *DR/RPCN syncing into specific contexts*: Syncing schemas from remote clusters directly into a named context is not supported. -* *WASM integration*: Context-aware schema IDs are not surfaced in WASM data transforms. -* *Breaking change on upgrade*: After enabling `schema_registry_enable_qualified_subjects`, any existing subject whose name matches the qualified subject pattern `::` (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging` rather than as a literal subject name in the default context. See <>. +* *Console and rpk*: Native support for context management operations (listing, creating, and deleting contexts) in the Redpanda Console UI and `rpk` CLI is in progress and not available in 26.1. Use the Schema Registry HTTP API directly. See <>. +* *Non-Java SerDe clients*: Non-Java serializer/deserializer clients do not yet natively support qualified subjects in 26.1. A fast-follow patch release in 26.1.x is planned. As a workaround, point these clients at the `/contexts/{context}/...` base URL path prefix. See <>. +* *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts and is out of scope for the current release. +* *Iceberg topics*: Context-aware schema IDs are not yet surfaced in Iceberg topic integration. +* *`referencedby` endpoint*: `GET /subjects/{subject}/versions/{version}/referencedby` returns a list of bare schema IDs with no context information. When references span contexts, it is not possible to determine which context each returned ID belongs to. +* *Cross-context isolation*: Contexts provide organizational and ID-space isolation, but do not prevent cross-context schema references. There is no mechanism to block schemas in one context from referencing schemas in another context. +* *Default context cannot be deleted*: The default context (`.`) cannot be deleted. +* *Breaking change on upgrade*: After enabling `schema_registry_enable_qualified_subjects`, any existing subject whose name matches the qualified subject pattern (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging` rather than as a literal subject name in the default context. See <>. ifndef::env-cloud[] -[NOTE] -==== -Schema Registry contexts does not require an enterprise license. -==== +NOTE: No enterprise license is required to use contexts. endif::env-cloud[] == How Schema Registry contexts work -Prior to v26.1, Redpanda Schema Registry maintained a flat namespace: all schemas shared a single global schema ID counter and a single set of mode and compatibility settings (with optional per-subject overrides). Schema Registry contexts extend this model by introducing named namespaces. Each context has its own schema ID counter that increments independently of other contexts, in addition to its own mode and compatibility settings. +=== Schema ID isolation + +Before contexts, the Schema Registry maintained a single global ID counter. All schemas shared one ID space, and a given schema ID pointed to exactly one schema across the entire registry. + +After enabling contexts, *each context has its own independent ID counter*. This means schema ID `1` in `.staging` and schema ID `1` in `.production` are different schemas. As a result, `GET /schemas/ids/{id}` searches the *default context only* by default. To retrieve a schema by ID from a non-default context, you must pass the `subject` query parameter to scope the lookup: + +[source,bash] +---- +GET /schemas/ids/1?subject=:.staging:my-topic +---- + +See also <>. + +=== Configuration resolution order + +Before contexts, mode and compatibility settings resolved as: + +---- +Subject → Global → Built-in defaults +---- -Contexts are referenced in the API using a *qualified subject* syntax: +After enabling contexts, a context layer sits between subject and global: ---- -:: +Subject → Context → Global (.:.__GLOBAL:) → Built-in defaults ---- -For example, `:.production:user-events-value` identifies subject `user-events-value` in context `.production`. Context names begin with a dot (`.`). Unqualified subjects (for example, `user-events-value`) are unchanged and continue to belong to the *default context* (represented as `.:` or simply an absence of context prefix), ensuring full backward compatibility. +For example, setting the `.staging` context to `IMPORT` mode means all subjects in `.staging` inherit `IMPORT` unless they have a subject-level override, even if the global mode is `READWRITE`. + +Use `defaultToGlobal=true` on `GET /config` and `GET /mode` requests to see the effective value after full fallback resolution. + +=== Qualified subject syntax + +Wherever the Schema Registry API accepts a subject, you can supply a qualified subject instead of a bare subject name: -A *global context* (`\__GLOBAL`) provides the lowest-priority fallback for mode and compatibility settings. The resolution order for configuration lookup is: subject → context → global → built-in defaults. Setting a global context mode to `READONLY`, for example, applies that mode to any subject or context that does not have its own explicit setting. +[cols="2,1,2", options="header"] +|=== +| Input | Context | Subject + +| `user-events-value` +| `.` (default) +| `user-events-value` + +| `:.staging:user-events-value` +| `.staging` +| `user-events-value` + +| `:.:user-events-value` +| `.` (default) +| `user-events-value` + +| `:.staging:` +| `.staging` +| (empty — used for context-level config/mode operations) +|=== -Schema references within schema definitions follow the same rules: unqualified references resolve within the same context as the root schema; qualified references resolve in the explicitly named context. This enables patterns such as a shared `.shared` context that holds common types referenced by multiple team-specific contexts. +=== `GET /subjects` behavior change + +After enabling the flag, `GET /subjects` (with no `subjectPrefix`) returns subjects across *all* contexts. Non-default context subjects appear with their qualified names — for example, `:.staging:my-topic`. This is a behavioral change from the previous flat list of bare subject names. + +=== Cross-context schema references + +Contexts do not enforce isolation of schema references. Schemas can reference schemas in any other context. Unqualified references in schema definitions resolve within the same context as the root schema, not the default context. Qualified references can reach any context explicitly (for example, `:.shared:CommonType`). == Enable Schema Registry contexts @@ -93,6 +143,11 @@ To enable contexts on a self-managed cluster, set the `schema_registry_enable_qu rpk cluster config set schema_registry_enable_qualified_subjects true ---- +[IMPORTANT] +==== +This property requires a broker restart. The change does not take effect until all brokers have restarted. +==== + To verify the current setting: [source,bash] @@ -102,28 +157,11 @@ rpk cluster config get schema_registry_enable_qualified_subjects endif::env-cloud[] ifdef::env-cloud[] -[NOTE] -==== -On Serverless clusters, contexts are managed by Redpanda and enabled automatically per tenant. On BYOC and Dedicated clusters, contact Redpanda support or use the cluster configuration API to enable `schema_registry_enable_qualified_subjects`. -==== +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. endif::env-cloud[] == Configure Schema Registry contexts -=== Qualified subject syntax - -Wherever the Schema Registry API accepts a subject—in path parameters, query parameters, or schema reference fields—you can supply a qualified subject instead of a bare subject name: - -[cols="1,2", options="header"] -|=== -| Syntax | Meaning - -| `::` | Subject `` in context ``. -| `:.production:user-events-value` | Subject `user-events-value` in context `.production`. -| `:.production:` | The context `.production` itself (empty subject name), used for context-level mode/config operations. -| `user-events-value` | Subject `user-events-value` in the default context. -|=== - === Register a schema in a context To register a schema in a named context, use the qualified subject form in the `POST /subjects/{subject}/versions` request: @@ -131,16 +169,16 @@ To register a schema in a named context, use the qualified subject form in the ` [source,bash] ---- curl -s -X POST \ - http://localhost:8081/subjects/:.production:user-events-value/versions \ + http://localhost:8081/subjects/:.staging:my-topic/versions \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ - -d '{"schema": "{\"type\":\"record\",\"name\":\"UserEvent\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"action\",\"type\":\"string\"}]}"}' + -d '{"schema": "{\"type\":\"string\"}"}' ---- -The schema ID returned is unique within the `.production` context and independent of schema IDs in other contexts. +The schema ID returned is unique within the `.staging` context and independent of schema IDs in other contexts. === List contexts -To list all contexts that have been explicitly created (in addition to the default context), use the `GET /contexts` endpoint: +To list all materialized contexts (those that have had at least one schema registered), use `GET /contexts`: [source,bash] ---- @@ -151,42 +189,54 @@ Example response: [source,json] ---- -[".","production","staging"] +[".","staging","production"] ---- -NOTE: The default context is always included in the response, represented as `"."`. +NOTE: A context is only listed after at least one schema has been registered in it. Pre-configuring mode or compatibility alone does not cause a context to appear in this list. The default context (`.`) is always included. -=== List subjects in a context +=== List subjects using subject prefix filtering -To list all subjects within a specific context, use the `/contexts/{context}/subjects` endpoint or the `subjectPrefix` query parameter on `GET /subjects`: +The `subjectPrefix` query parameter on `GET /subjects` lets you scope subject listings precisely. The following table shows supported patterns: -.List subjects within a context using the context path prefix -[source,bash] ----- -curl -s http://localhost:8081/contexts/.production/subjects ----- +[cols="2,3", options="header"] +|=== +| Prefix | Matches -.List subjects using subjectPrefix (explicit context) -[source,bash] ----- -curl -s "http://localhost:8081/subjects?subjectPrefix=:.production:" ----- +| `my-` +| Subjects starting with `my-` in the default context only + +| `:.staging:` +| All subjects in the `.staging` context + +| `:.staging:my-` +| Subjects starting with `my-` in the `.staging` context + +| `:*:` +| All subjects in all contexts + +| `:*:my-` +| Subjects starting with `my-` across all contexts +|=== -.List subjects across all contexts (wildcard) [source,bash] ---- +# All subjects in the .staging context +curl -s "http://localhost:8081/subjects?subjectPrefix=:.staging:" + +# All subjects across all contexts curl -s "http://localhost:8081/subjects?subjectPrefix=:*:" ---- -.List subjects in the default context only (default behavior without subjectPrefix) +You can also list subjects within a context using the `/contexts/{context}/subjects` path: + [source,bash] ---- -curl -s http://localhost:8081/subjects +curl -s http://localhost:8081/contexts/.staging/subjects ---- === Set context-level mode -You can configure mode at the context level by specifying a qualified subject with an empty subject name (`::`): +Mode can be set at the context level by specifying a qualified subject with an empty subject name (`::`): [source,bash] ---- @@ -195,84 +245,79 @@ curl -s -X PUT \ http://localhost:8081/mode/:.staging: \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"mode": "IMPORT"}' ----- -[source,bash] ----- # Get the mode for the .staging context -curl -s http://localhost:8081/mode/:.staging: +# Use defaultToGlobal=true to see the effective value after fallback resolution +curl -s "http://localhost:8081/mode/:.staging:?defaultToGlobal=true" ---- === Set context-level compatibility - To configure context-level compatibility: - [source,bash] ---- -# Set compatibility for the .production context +# Set compatibility for the .staging context curl -s -X PUT \ - http://localhost:8081/config/:.production: \ + http://localhost:8081/config/:.staging: \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"compatibility": "BACKWARD"}' ----- -[source,bash] ----- # Get compatibility for a specific subject within a context -curl -s http://localhost:8081/config/:.production:user-events-value +# Use defaultToGlobal=true to see the effective value after fallback +curl -s "http://localhost:8081/config/:.staging:my-topic?defaultToGlobal=true" ---- === Set the global context fallback -The `\__GLOBAL` context provides the lowest-priority fallback for all contexts and subjects that do not have their own explicit setting: +The `.:.__GLOBAL:` context provides the lowest-priority fallback for all contexts and subjects that do not have their own explicit setting: [source,bash] ---- +# Get the current global mode +curl -s http://localhost:8081/mode/:.__GLOBAL: + # Set global default compatibility curl -s -X PUT \ - http://localhost:8081/config/:__GLOBAL: \ + http://localhost:8081/config/:.__GLOBAL: \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"compatibility": "FULL"}' ---- -NOTE: `\__GLOBAL` and `\__EMPTY` are reserved names and cannot be used as regular context or subject names. +NOTE: `.__GLOBAL` is a reserved context name and cannot be used as a regular context name. -=== Use a context as the base URL +=== Retrieve schema references with qualified names -You can point a client at a specific context by setting the client's base URL to `${host}/contexts/{context}`. Redpanda rewrites requests under this path prefix to operate within the specified context automatically. For example: +Use `referenceFormat=qualified` on `GET /subjects/{subject}/versions/{version}` to return references with context-qualified subject names instead of bare names: +[source,bash] ---- -# All requests to this base URL operate within the .production context -http://localhost:8081/contexts/.production +curl -s "http://localhost:8081/subjects/:.staging:my-topic/versions/1?referenceFormat=qualified" ---- -A client with this base URL making a `GET /schemas/ids/42` request would retrieve schema ID 42 from the `.production` context. +This is useful when schemas span multiple contexts and you need to disambiguate reference targets. -=== Set a pre-configured mode on a non-existent context +=== Use a context as the client base URL -You can set mode or compatibility on a context before any schemas are registered in it. When the first schema is registered under that context, it immediately inherits the pre-configured settings: +You can point a Schema Registry client at a specific context by setting the client's Schema Registry URL to `${host}/contexts/{context}`. Redpanda rewrites requests under this path prefix to operate within the specified context. This is the recommended workaround for non-Java SerDe clients that do not yet support qualified subject syntax natively: -[source,bash] ---- -# Pre-configure a context that does not yet exist -curl -s -X PUT \ - http://localhost:8081/mode/:.new-team: \ - -H "Content-Type: application/vnd.schemaregistry.v1+json" \ - -d '{"mode": "READONLY"}' - -# Any attempt to register a schema in :.new-team: will now be rejected -# until the mode is changed to READWRITE +# All requests to this base URL operate within the .staging context +http://localhost:8081/contexts/.staging ---- -=== Delete a context +=== Pre-configure a context before registering schemas -You can only delete a context when it has no subjects (or all subjects have been hard-deleted). Attempting to delete a non-empty context returns a `ContextNotEmpty` error. +You can set mode or compatibility on a context before any schemas are registered in it: [source,bash] ---- -curl -s -X DELETE http://localhost:8081/contexts/.staging +curl -s -X PUT \ + http://localhost:8081/mode/:.new-team: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"mode": "READONLY"}' ---- +Schema registrations in `:.new-team:` will be rejected until the mode is changed to `READWRITE`. + === Cross-context schema references Schemas can reference schemas in other contexts using qualified subject names in the `references` field: @@ -283,19 +328,35 @@ Schemas can reference schemas in other contexts using qualified subject names in "schema": "...", "references": [ { - "name": "Address", - "subject": ":.shared:Address", + "name": "CommonType", + "subject": ":.shared:CommonType", "version": 1 } ] } ---- -Unqualified references in schema definitions resolve to the same context as the root schema, not to the default context. +Unqualified references in schema definitions resolve to the same context as the root schema, not the default context. -== Cluster configuration property +=== Delete a context + +A context can only be deleted when it contains no subjects. Soft-deleted subjects still count — you must hard-delete all subjects before the context can be removed. Attempting to delete a non-empty context returns a `context_not_empty` error. + +[NOTE] +==== +The default context (`.`) cannot be deleted. +==== + +[source,bash] +---- +# Hard-delete all subjects in the context first +curl -s -X DELETE "http://localhost:8081/subjects/:.staging:my-topic?permanent=true" -The following cluster configuration property controls whether qualified subject parsing is enabled. +# Then delete the empty context +curl -s -X DELETE http://localhost:8081/contexts/.staging +---- + +== Cluster configuration property `schema_registry_enable_qualified_subjects`:: + @@ -303,14 +364,19 @@ The following cluster configuration property controls whether qualified subject |=== | Type | Boolean | Default (26.1) | `false` -| Default (26.2+) | `true` +| Default (26.2) | `true` +| Removed in | 26.3 (always enabled) +| Restart required | Yes |=== + -When set to `false`, subjects are treated as literal strings. When set to `true`, subjects matching the `::` pattern are parsed as context-qualified subjects. +When `false`, subjects are treated as literal strings (existing behavior). When `true`, subjects matching the `::` pattern are parsed as context-qualified subjects. + -ifndef::env-cloud[] -Configure using `rpk`: +[IMPORTANT] +==== +This is not a dynamic property. Broker restart is required after changing this value. +==== + +ifndef::env-cloud[] [source,bash] ---- rpk cluster config set schema_registry_enable_qualified_subjects true @@ -321,96 +387,161 @@ endif::env-cloud[] [NOTE] ==== -Native `rpk` commands for managing contexts (for example, listing, creating, or deleting contexts) are not available in v26.1. Use the Schema Registry HTTP API directly. +Native `rpk` commands for context management operations (listing, creating, and deleting contexts) are not yet available. Use the Schema Registry HTTP API directly for context-level operations. See <>. ==== -Existing `rpk registry` commands that accept a subject name already support qualified subject syntax once `schema_registry_enable_qualified_subjects` is enabled. Pass a qualified subject wherever a `--subject` flag is accepted: +Existing `rpk registry` commands that accept a subject name support qualified subject syntax once `schema_registry_enable_qualified_subjects` is enabled. Pass a qualified subject wherever a `--subject` flag is accepted: [source,bash] ---- -# Create a schema in a named context +# Register a schema in a named context rpk registry schema create \ - --subject ":.production:user-events-value" \ - --schema user-events.avsc \ + --subject ":.staging:my-topic" \ + --schema my-schema.avsc \ --type avro # List schemas for a subject in a named context rpk registry schema list \ - --subject ":.production:user-events-value" + --subject ":.staging:my-topic" # Get a specific schema version from a context rpk registry schema get \ - --subject ":.production:user-events-value" \ + --subject ":.staging:my-topic" \ --version 1 # Check compatibility for a subject in a context rpk registry schema check-compatibility \ - --subject ":.production:user-events-value" \ - --schema user-events-v2.avsc + --subject ":.staging:my-topic" \ + --schema my-schema-v2.avsc # Get the compatibility level for a context rpk registry compatibility-level get \ - --subject ":.production:" + --subject ":.staging:" # Set the compatibility level for a context rpk registry compatibility-level set \ - --subject ":.production:" \ + --subject ":.staging:" \ --level BACKWARD # Get the mode for a context rpk registry mode get \ - --subject ":.production:" + --subject ":.staging:" # Set the mode for a context rpk registry mode set \ - --subject ":.production:" \ + --subject ":.staging:" \ --mode READONLY -# Delete a subject within a context +# Delete a subject within a context (soft delete) rpk registry subject delete \ - --subject ":.production:user-events-value" + --subject ":.staging:my-topic" + +# List all subjects (returns qualified names for non-default contexts) +rpk registry subject list + +# Grant read access to all subjects in a context (prefix ACL) +rpk security acl create \ + --registry-subject ":.staging:" \ + --resource-pattern-type prefixed \ + --operation read \ + --allow-principal User:alice ---- For full reference documentation on these commands, see: -* xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[rpk registry schema create] -* xref:reference:rpk/rpk-registry/rpk-registry-schema-list.adoc[rpk registry schema list] -* xref:reference:rpk/rpk-registry/rpk-registry-schema-get.adoc[rpk registry schema get] -* xref:reference:rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc[rpk registry schema check-compatibility] -* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc[rpk registry compatibility-level get] -* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc[rpk registry compatibility-level set] -* xref:reference:rpk/rpk-registry/rpk-registry-mode-get.adoc[rpk registry mode get] -* xref:reference:rpk/rpk-registry/rpk-registry-mode-set.adoc[rpk registry mode set] -* xref:reference:rpk/rpk-registry/rpk-registry-subject-delete.adoc[rpk registry subject delete] -* xref:reference:rpk/rpk-registry/rpk-registry-subject-list.adoc[rpk registry subject list] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-list.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-get.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-mode-get.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-mode-set.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-subject-delete.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-subject-list.adoc[] + +== Client integration status + +[#client-integration-status] + +[cols="2,1,3", options="header"] +|=== +| Client | Status | Notes + +| Schema Registry API (all operations) +| Full support +| Use qualified subjects directly in any endpoint. + +| Java SerDe (Confluent) +| Supported +| Requires a custom `ContextNameStrategy`. See the Confluent SerDe documentation for details. + +| Non-Java SerDe +| Not yet supported (26.1) +| Planned in a 26.1.x patch release. Workaround: set the client's Schema Registry base URL to `http://:8081/contexts/{context}`. + +| rpk +| In progress +| Context management commands not yet available. Qualified subjects work in existing `rpk registry` commands. + +| Redpanda Console +| In progress +| Not available in 26.1. + +| Server-side schema ID validation +| Not supported +| Out of scope for this release. +|=== == ACL authorization [#acl-authorization] -Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. +Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. No new resource types are needed. + +[cols="2,2,2", options="header"] +|=== +| Operation | ACL resource | Permission required + +| Context-level config/mode (`PUT /config/::`, `PUT /mode/::`) +| `sr_registry` +| `alter_configs` + +| Read context-level config/mode +| `sr_registry` +| `describe_configs` + +| List subjects / list contexts +| `sr_subject` (results filtered to accessible subjects) +| `describe` + +| Delete a context (`DELETE /contexts/{context}`) +| `sr_registry` +| `delete` + +| Schema CRUD on a subject +| `sr_subject` on the specific subject +| `read` / `write` / `delete` + +| Subject-level config/mode +| `sr_subject` on the specific subject +| `alter_configs` / `describe_configs` +|=== === Grant access to all subjects in a context -Use a prefix ACL on `sr_subject` with the context prefix `::` to grant access to all subjects within a context: +Use a prefix ACL on `sr_subject` with `--resource-pattern-type prefixed` to grant access to all current and future subjects within a context: [source,bash] ---- rpk security acl create \ - --allow-principal User:team-a \ - --operation read,write,describe \ - --registry-subject ":.team-a:" \ + --registry-subject ":.staging:" \ + --resource-pattern-type prefixed \ + --operation read \ + --allow-principal User:alice \ --brokers ---- -This ACL matches `:.team-a:*`, granting the principal access to every subject in the `.team-a` context. - -=== Context-level mode and config operations - -Context-level mode and compatibility (`PUT /mode/::` and `PUT /config/::`) require `sr_registry` permission with the `alter_configs` operation—consistent with global mode and config endpoints. - -Subject-level operations (`PUT /mode/::` and `PUT /config/::`) require `sr_subject` permission on the specific subject. - === Audit log format When Schema Registry ACLs are enabled, audit log entries include the fully qualified subject name for non-default context operations: @@ -420,14 +551,14 @@ When Schema Registry ACLs are enabled, audit log entries include the fully quali { "resources": [ { - "name": ":.production:user-events-value", + "name": ":.staging:my-topic", "type": "subject" } ] } ---- -Default context subjects are logged with their unqualified name. +Default context subjects are logged with their unqualified name (no change from existing behavior). == Metrics @@ -435,7 +566,7 @@ The following Schema Registry metrics have been updated to include a `context` l [cols="2,2", options="header"] |=== -| Metric | Update +| Metric | Change | `*_schema_registry_cache_schema_count` | New `context` label added. @@ -447,7 +578,9 @@ The following Schema Registry metrics have been updated to include a `context` l | New `context` label added. |=== -For the full metrics reference, see xref:reference:public-metrics-reference.adoc[Public Metrics Reference]. +The count of non-default contexts is also included in Redpanda's phone-home telemetry. + +For the full metrics reference, see xref:reference:public-metrics-reference.adoc[]. == Upgrade considerations @@ -455,15 +588,17 @@ For the full metrics reference, see xref:reference:public-metrics-reference.adoc [IMPORTANT] ==== -*Breaking change*: When `schema_registry_enable_qualified_subjects` is enabled, any existing subject whose name matches the qualified subject pattern—for example, `:.staging:user-value`—is reinterpreted as subject `user-value` in context `.staging`, rather than as a literal subject name in the default context. Subjects without a `:.` prefix are unaffected. +*Breaking change*: When `schema_registry_enable_qualified_subjects` is enabled, any existing subject whose name matches the qualified subject pattern — for example, `:.staging:user-value` — is reinterpreted as subject `user-value` in context `.staging`, rather than as a literal subject name in the default context. Subjects without a `:.` prefix are unaffected. + +This edge case is expected to be rare. No automatic migration is provided. ==== -While the necessity of doing so is rare, you can audit your existing subjects for affected names before enabling contexts: +To audit your existing subjects for affected names before enabling the feature: ifndef::env-cloud[] [source,bash] ---- -rpk registry subject list | grep '^:\.' +rpk registry subject list | grep '^\.' ---- endif::env-cloud[] @@ -474,57 +609,100 @@ curl -s http://:8081/subjects | jq '.[] | select(startswit ---- endif::env-cloud[] -If affected subjects are found, rename them before enabling the property, or plan to rename them after enabling and re-register any schemas under the reinterpreted context structure. +If affected subjects are found, rename them before enabling the property, or plan to re-register them under the reinterpreted context structure after enabling. +In 26.2, if you need additional time to migrate, you can temporarily set `schema_registry_enable_qualified_subjects` to `false` to restore literal behavior while you complete the migration. This option is removed in 26.3, after which contexts are always enabled. + +[IMPORTANT] +==== +Remember that changing `schema_registry_enable_qualified_subjects` requires a broker restart in both directions (enabling and disabling). +==== == Troubleshooting -=== Schema registration fails after upgrading to v26.1 +[#schema-id-lookup-fails] +=== Schema ID lookup returns 404 or wrong schema + +*Symptom*: `GET /schemas/ids/{id}` returns a 404 or returns the wrong schema after registering a schema in a non-default context. + +*Cause*: `GET /schemas/ids/{id}` searches the *default context only*. A schema registered in `:.staging:my-topic` (returning ID `1`) is not found by `GET /schemas/ids/1` without a context hint. + +*Resolution*: Pass the `subject` query parameter to scope the lookup to the correct context: + +[source,bash] +---- +curl -s "http://localhost:8081/schemas/ids/1?subject=:.staging:my-topic" +---- + +=== Qualified subjects not recognized (treated as literal names) + +*Symptom*: Subjects with the `:.` prefix are stored as literal subject names in the default context instead of being parsed as context-qualified subjects. + +*Cause 1*: `schema_registry_enable_qualified_subjects` is set to `false` (the 26.1 default for self-managed clusters). + +*Cause 2*: The property was set to `true` but the brokers have not yet been restarted. This property is not dynamic and requires a full broker restart to take effect. + +*Resolution*: + +ifndef::env-cloud[] +[source,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +# Then restart all brokers +---- +endif::env-cloud[] + +=== Schema registration fails after upgrading to 26.1 -*Symptom*: A `POST /subjects/{subject}/versions` request returns an unexpected error after upgrading. +*Symptom*: A `POST /subjects/{subject}/versions` request returns an unexpected error after upgrading and enabling the flag. -*Cause*: The subject name may contain a `:.` prefix that is now parsed as a context-qualified subject. If the inferred context was pre-configured in `READONLY` mode, new registrations are rejected. +*Cause*: An existing subject whose name begins with `:.` has been reinterpreted as a context-qualified subject. If the inferred context was pre-configured in `READONLY` mode, new registrations are rejected. -*Resolution*: Check whether the subject name matches the qualified pattern: +*Resolution*: Check for affected subject names: ifndef::env-cloud[] [source,bash] ---- -rpk registry subject list | grep '^:\.' +rpk registry subject list | grep '^\.' ---- endif::env-cloud[] -Rename affected subjects if needed, or change the context mode: +Rename affected subjects or change the inferred context's mode: [source,bash] ---- -curl -s -X PUT http://localhost:8081/mode/:: \ +curl -s -X PUT http://localhost:8081/mode/:.affected-context: \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"mode": "READWRITE"}' ---- -=== `GET /contexts` returns an empty list or does not include my context +=== Context cannot be deleted -*Symptom*: A context that you believe exists does not appear in `GET /contexts`. +*Symptom*: `DELETE /contexts/{context}` returns a `context_not_empty` error even though all subjects appear to have been deleted. -*Cause*: A context is only listed after at least one schema has been registered in it (creating the internal `CONTEXT` record). Pre-configuring a mode or compatibility setting alone does not create a listed context. +*Cause*: Soft-deleted subjects still count toward the non-empty check. Subjects must be hard-deleted (permanently deleted) before the context can be removed. Also note that the default context (`.`) cannot be deleted under any circumstances. -*Resolution*: Register a schema in the context to materialize it, or verify that at least one subject exists under the context. +*Resolution*: Hard-delete all subjects in the context, then retry: -=== Qualified subjects not recognized (subjects treated as literal names) +[source,bash] +---- +# Soft-delete (if not already done) +curl -s -X DELETE "http://localhost:8081/subjects/:.staging:my-topic" -*Symptom*: Subjects with the `:.` prefix are stored as literal subject names in the default context rather than being parsed as context-qualified subjects. +# Hard-delete (permanent) +curl -s -X DELETE "http://localhost:8081/subjects/:.staging:my-topic?permanent=true" -*Cause*: `schema_registry_enable_qualified_subjects` is set to `false`, which is the default for self-managed clusters). +# Retry context deletion +curl -s -X DELETE http://localhost:8081/contexts/.staging +---- -*Resolution*: +=== `GET /contexts` does not list my context -ifndef::env-cloud[] -[source,bash] ----- -rpk cluster config set schema_registry_enable_qualified_subjects true ----- -endif::env-cloud[] +*Symptom*: A context that you believe exists does not appear in `GET /contexts`. + +*Cause*: A context is only materialized (and returned by `GET /contexts`) after at least one schema has been registered in it. Pre-configuring mode or compatibility does not create a listed context. + +*Resolution*: Register at least one schema in the context to materialize it, or verify that at least one subject exists under the context. === Cross-context reference resolution fails @@ -532,51 +710,38 @@ endif::env-cloud[] *Cause*: Unqualified references in schema definitions resolve within the same context as the root schema, not in the default context. -*Resolution*: Use a fully qualified reference in the schema definition: +*Resolution*: Use fully qualified references in the schema definition: [source,json] ---- { "references": [ { - "name": "Address", - "subject": ":.shared:Address", + "name": "CommonType", + "subject": ":.shared:CommonType", "version": 1 } ] } ---- -=== Context cannot be deleted - -*Symptom*: `DELETE /contexts/{context}` returns a `ContextNotEmpty` error. +=== `referencedby` returns IDs with no context information -*Cause*: The context still has subjects that have not been fully deleted (hard-delete). +*Symptom*: `GET /subjects/{subject}/versions/{version}/referencedby` returns schema IDs, but you cannot determine which context each ID belongs to. -*Resolution*: Delete all subjects within the context before deleting the context itself. Use a soft delete followed by a hard delete, which is permanent: - -[source,bash] ----- -# Soft-delete the subject -curl -s -X DELETE \ - "http://localhost:8081/subjects/::" - -# Hard-delete the subject (permanent) -curl -s -X DELETE \ - "http://localhost:8081/subjects/::?permanent=true" ----- +*Cause*: This is a known limitation of the `referencedby` endpoint. It returns bare schema IDs with no context metadata. When references span contexts, the returned IDs are ambiguous. -Repeat for each subject in the context, then retry the `DELETE /contexts/{context}` request. +*Resolution*: There is no workaround in 26.1. To identify which schema an ID belongs to, try resolving the ID against each relevant context using `GET /schemas/ids/{id}?subject=::`. == Related topics -* xref:manage:schema-reg/schema-reg-overview.adoc[Redpanda Schema Registry] -* xref:manage:schema-reg/schema-reg-api.adoc[Use the Schema Registry API] -* xref:manage:schema-reg/schema-reg-authorization.adoc[Schema Registry Authorization] -* xref:reference:public-metrics-reference.adoc[Public Metrics Reference] +* xref:manage:schema-reg/schema-reg-overview.adoc[] +* xref:manage:schema-reg/schema-reg-api.adoc[] +* xref:manage:schema-reg/schema-reg-authorization.adoc[] +* xref:reference:public-metrics-reference.adoc[] ifndef::env-cloud[] -* xref:reference:cluster-properties.adoc[Cluster Configuration Properties] +* xref:reference:cluster-properties.adoc[] endif::env-cloud[] ifdef::env-cloud[] -* xref:reference:properties/cluster-properties.adoc[Cluster Configuration Properties] +* xref:reference:properties/cluster-properties.adoc[] endif::env-cloud[] From b7e87eaa513a136d941ed48fc5b0ddf73f9bafd5 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Fri, 10 Apr 2026 09:45:44 -0500 Subject: [PATCH 08/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 21 ++++++++----------- 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 20fef2c8e0..40fa6fcf1a 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -17,14 +17,14 @@ Schema Registry contexts are namespaces that isolate schemas, subjects, and conf Each context maintains its own schema ID counter, mode settings, and compatibility settings. Unqualified subjects continue to work unchanged in the implicit default context. -This feature is compatible with the Confluent Schema Registry Contexts API and requires no enterprise license. +Schema Registry contexts is compatible with the Confluent Schema Registry Contexts API and requires no enterprise license. == When to use contexts Contexts are most useful in the following scenarios: * *Multi-team deployments on a shared cluster*: Teams can register schemas independently under their own contexts without risking naming collisions or configuration drift. -* *Schema migration from Confluent Schema Registry*: Confluent SR uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. +* *Schema migration from Confluent Schema Registry*: Confluent Schema Registry uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. * *Multi-cluster schema syncing and disaster recovery*: Dedicated namespaces reduce schema ID collision risk when syncing schemas across clusters. ifdef::env-cloud[] @@ -40,13 +40,13 @@ Before using Schema Registry contexts, ensure that: + [IMPORTANT] ==== -`schema_registry_enable_qualified_subjects` is *not a dynamic property*. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is the most likely missing step. +`schema_registry_enable_qualified_subjects` is _not_ a dynamic property. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is the most likely cause. ==== + ifndef::env-cloud[] [NOTE] ==== -In 26.1, `schema_registry_enable_qualified_subjects` defaults to `false`. You must explicitly enable it. In 26.2, the default changes to `true`. In 26.3, the property is removed and contexts are always enabled. +The `schema_registry_enable_qualified_subjects` property defaults to `false`. You must explicitly enable it. ==== endif::env-cloud[] @@ -54,18 +54,15 @@ endif::env-cloud[] == Limitations -* *Console and rpk*: Native support for context management operations (listing, creating, and deleting contexts) in the Redpanda Console UI and `rpk` CLI is in progress and not available in 26.1. Use the Schema Registry HTTP API directly. See <>. -* *Non-Java SerDe clients*: Non-Java serializer/deserializer clients do not yet natively support qualified subjects in 26.1. A fast-follow patch release in 26.1.x is planned. As a workaround, point these clients at the `/contexts/{context}/...` base URL path prefix. See <>. -* *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts and is out of scope for the current release. -* *Iceberg topics*: Context-aware schema IDs are not yet surfaced in Iceberg topic integration. +* *Console and rpk*: Native support for context management operations (listing, creating, and deleting contexts) in the Redpanda Console UI and `rpk` CLI is not available. Use the Schema Registry HTTP API directly. See <>. +* *Non-Java SerDe clients*: Non-Java serializer/deserializer clients do not natively support qualified subjects. Instead, point these clients at the `/contexts/{context}/...` base URL path prefix. See <>. +* *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts. +* *Iceberg topics*: Context-aware schema IDs are not surfaced in Iceberg topic integration. * *`referencedby` endpoint*: `GET /subjects/{subject}/versions/{version}/referencedby` returns a list of bare schema IDs with no context information. When references span contexts, it is not possible to determine which context each returned ID belongs to. * *Cross-context isolation*: Contexts provide organizational and ID-space isolation, but do not prevent cross-context schema references. There is no mechanism to block schemas in one context from referencing schemas in another context. -* *Default context cannot be deleted*: The default context (`.`) cannot be deleted. +* *Default context cannot be deleted*: You cannot delete the default context (`.`). * *Breaking change on upgrade*: After enabling `schema_registry_enable_qualified_subjects`, any existing subject whose name matches the qualified subject pattern (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging` rather than as a literal subject name in the default context. See <>. -ifndef::env-cloud[] -NOTE: No enterprise license is required to use contexts. -endif::env-cloud[] == How Schema Registry contexts work From 1ac6b7e20461974c44c46bd4d3bf039183995e9a Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Fri, 10 Apr 2026 11:02:03 -0500 Subject: [PATCH 09/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../manage/pages/schema-reg/schema-reg-contexts.adoc | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 40fa6fcf1a..9ffc890841 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -35,21 +35,14 @@ endif::env-cloud[] Before using Schema Registry contexts, ensure that: -* You are running Redpanda *26.1 or later*. +* You are running Redpanda v26.1 or later. * The `schema_registry_enable_qualified_subjects` cluster configuration property is set to `true`. + [IMPORTANT] ==== -`schema_registry_enable_qualified_subjects` is _not_ a dynamic property. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is the most likely cause. +The `schema_registry_enable_qualified_subjects` property defaults to `false`, so you must explicitly enable it. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is the most likely cause. ==== + -ifndef::env-cloud[] -[NOTE] -==== -The `schema_registry_enable_qualified_subjects` property defaults to `false`. You must explicitly enable it. -==== -endif::env-cloud[] - * If you use Schema Registry ACLs, ensure the principal interacting with a context has the appropriate permissions. See <>. == Limitations From d0c13574a6013fc8580878b7d7334a791b7ef456 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Fri, 10 Apr 2026 14:27:55 -0600 Subject: [PATCH 10/51] docs: add single-source tags and cross-link cloud-docs playbook Add // tag::single-source[] and // end::single-source[] to schema-reg-contexts.adoc so cloud-docs can include the body content via the established single-sourcing pattern. Update local-antora-playbook.yml to reference the cloud-docs PR branch for Netlify preview. Must revert to 'main' before merge. Co-Authored-By: Claude Opus 4.6 (1M context) --- local-antora-playbook.yml | 2 +- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 0590286e59..9c61c888e5 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -18,7 +18,7 @@ content: - url: https://github.com/redpanda-data/docs branches: [v/*, shared, site-search,'!v-end-of-life/*'] - url: https://github.com/redpanda-data/cloud-docs - branches: 'main' + branches: DOC-1812-Document-Cloud-Feature-Schema-Registry-Contexts-Serverless-etc - url: https://github.com/redpanda-data/redpanda-labs branches: main start_paths: [docs,'*/docs'] diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 9ffc890841..8502d6c392 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -13,6 +13,7 @@ // Single-sourcing tags: Cloud-only content is wrapped in ifdef::env-cloud[] ... endif::[] // Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] +// tag::single-source[] Schema Registry contexts are namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings. Unqualified subjects continue to work unchanged in the implicit default context. @@ -735,3 +736,4 @@ endif::env-cloud[] ifdef::env-cloud[] * xref:reference:properties/cluster-properties.adoc[] endif::env-cloud[] +// end::single-source[] From c8d6312431c82a76ed1dc933cdd6abd23cc0d230 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 16 Apr 2026 09:11:29 -0500 Subject: [PATCH 11/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Co-authored-by: Michele Cyran --- .../manage/pages/schema-reg/schema-reg-contexts.adoc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 8502d6c392..ec35820719 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -14,11 +14,11 @@ // Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] // tag::single-source[] -Schema Registry contexts are namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance. +Schema Registry contexts are namespaces that isolate schemas, subjects, and configurations from one another within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings. -Unqualified subjects continue to work unchanged in the implicit default context. +Existing schemas will simply continue to work: unqualified subjects remain in the implicit default context -Schema Registry contexts is compatible with the Confluent Schema Registry Contexts API and requires no enterprise license. +Schema Registry contexts is compatible with the Confluent Schema Registry Contexts API. == When to use contexts @@ -573,9 +573,11 @@ The count of non-default contexts is also included in Redpanda's phone-home tele For the full metrics reference, see xref:reference:public-metrics-reference.adoc[]. +ifndef::env-cloud[] == Upgrade considerations [#upgrade-considerations] +endif::env-cloud[] [IMPORTANT] ==== @@ -602,7 +604,6 @@ endif::env-cloud[] If affected subjects are found, rename them before enabling the property, or plan to re-register them under the reinterpreted context structure after enabling. -In 26.2, if you need additional time to migrate, you can temporarily set `schema_registry_enable_qualified_subjects` to `false` to restore literal behavior while you complete the migration. This option is removed in 26.3, after which contexts are always enabled. [IMPORTANT] ==== @@ -722,7 +723,7 @@ curl -s -X DELETE http://localhost:8081/contexts/.staging *Cause*: This is a known limitation of the `referencedby` endpoint. It returns bare schema IDs with no context metadata. When references span contexts, the returned IDs are ambiguous. -*Resolution*: There is no workaround in 26.1. To identify which schema an ID belongs to, try resolving the ID against each relevant context using `GET /schemas/ids/{id}?subject=::`. +*Resolution*: There is no workaround. To identify which schema an ID belongs to, try resolving the ID against each relevant context using `GET /schemas/ids/{id}?subject=::`. == Related topics From c81afb04d52baff2afeab67a498259ba9f59feab Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 16 Apr 2026 09:12:17 -0500 Subject: [PATCH 12/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index ec35820719..b5a3263c43 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -354,9 +354,7 @@ curl -s -X DELETE http://localhost:8081/contexts/.staging [cols="1,3"] |=== | Type | Boolean -| Default (26.1) | `false` -| Default (26.2) | `true` -| Removed in | 26.3 (always enabled) +| Default (v26.1) | `false` | Restart required | Yes |=== + From c9987174f9437b0f1eefc707a80881c3a8803b61 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 16 Apr 2026 09:16:24 -0500 Subject: [PATCH 13/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index b5a3263c43..5b19da6263 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -64,7 +64,7 @@ The `schema_registry_enable_qualified_subjects` property defaults to `false`, so Before contexts, the Schema Registry maintained a single global ID counter. All schemas shared one ID space, and a given schema ID pointed to exactly one schema across the entire registry. -After enabling contexts, *each context has its own independent ID counter*. This means schema ID `1` in `.staging` and schema ID `1` in `.production` are different schemas. As a result, `GET /schemas/ids/{id}` searches the *default context only* by default. To retrieve a schema by ID from a non-default context, you must pass the `subject` query parameter to scope the lookup: +After enabling contexts, each context has its own independent ID counter. This means schema ID `1` in `.staging` and schema ID `1` in `.production` are different schemas. As a result (and by default), `GET /schemas/ids/{id}` searches the _default context only_. To retrieve a schema by ID from a non-default context, you must pass the `subject` query parameter to scope the lookup: [source,bash] ---- From 8613e3c0538d258a633b53f29bd8c279105c059a Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 16 Apr 2026 09:18:56 -0500 Subject: [PATCH 14/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 5b19da6263..69aa4a9fa9 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -227,7 +227,7 @@ curl -s http://localhost:8081/contexts/.staging/subjects === Set context-level mode -Mode can be set at the context level by specifying a qualified subject with an empty subject name (`::`): +You can configure mode at the context level by specifying a qualified subject with an empty subject name (`::`): [source,bash] ---- From d797a76496077744760d744e3ccd0196d2764f09 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 16 Apr 2026 09:25:13 -0500 Subject: [PATCH 15/51] Apply suggestion from @Feediver1 --- .../pages/schema-reg/schema-reg-contexts.adoc | 24 ------------------- 1 file changed, 24 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 69aa4a9fa9..a099b44dbc 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -347,30 +347,6 @@ curl -s -X DELETE "http://localhost:8081/subjects/:.staging:my-topic?permanent=t curl -s -X DELETE http://localhost:8081/contexts/.staging ---- -== Cluster configuration property - -`schema_registry_enable_qualified_subjects`:: -+ -[cols="1,3"] -|=== -| Type | Boolean -| Default (v26.1) | `false` -| Restart required | Yes -|=== -+ -When `false`, subjects are treated as literal strings (existing behavior). When `true`, subjects matching the `::` pattern are parsed as context-qualified subjects. -+ -[IMPORTANT] -==== -This is not a dynamic property. Broker restart is required after changing this value. -==== -+ -ifndef::env-cloud[] -[source,bash] ----- -rpk cluster config set schema_registry_enable_qualified_subjects true ----- -endif::env-cloud[] == rpk commands From 69243b9c1d3c79b8f62609708382d0342fe164c6 Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Fri, 17 Apr 2026 08:59:47 -0700 Subject: [PATCH 16/51] Add contexts to schema-reg-api.adoc and cross-references --- .../pages/schema-reg/schema-reg-api.adoc | 45 +++++++++++++++++++ .../pages/schema-reg/schema-reg-contexts.adoc | 1 + 2 files changed, 46 insertions(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 6a8f7546e6..6316c87124 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -240,6 +240,49 @@ Curl:: When you register an evolved schema for an existing subject, the version `id` is incremented by 1. +== Use Schema Registry contexts + +Starting in Redpanda version 26.1, you can use contexts to create isolated namespaces for schemas, subjects, and configuration within a single Schema Registry instance. + +ifndef::env-cloud[] +To use contexts, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the broker. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions. +endif::env-cloud[] +ifdef::env-cloud[] +To use contexts on BYOC and Dedicated clusters, xref:manage:cluster-maintenance/config-cluster.adoc[configure the cluster property] `schema_registry_enable_qualified_subjects`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for details. +endif::env-cloud[] + +Contexts are created implicitly when you register a schema using a context-qualified subject. For example, registering a schema with the subject `:.staging:sensor-value` creates the `.staging` context if it does not already exist: + +[source,bash] +---- +curl -s -X POST \ + http://localhost:8081/subjects/:.staging:sensor-value/versions \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"schema": "{\"type\":\"string\"}"}' +---- + +=== Scope API operations to a context + +You can scope any Schema Registry API operation to a specific context in two ways: + +* Qualified subjects: Use the `::` syntax wherever a subject is accepted. For example, to list subjects in the `.staging` context: ++ +[source,bash] +---- +curl -s "http://localhost:8081/subjects?subjectPrefix=:.staging:" +---- + +* Base URL prefix: Prefix any endpoint path with `/contexts/{context}/`. The server rewrites the request to operate within that context. This approach is recommended for non-Java SerDe clients that do not support qualified subject syntax: ++ +[source,bash] +---- +curl -s http://localhost:8081/contexts/.staging/subjects +---- + +Unqualified subjects continue to work and operate in the default context. + +For the complete endpoint reference, see the link:/api/doc/schema-registry/[Schema Registry API reference]. + == Retrieve a schema To retrieve a registered schema from the registry, make a GET request to the `/schemas/ids/\{id}` endpoint: @@ -1188,6 +1231,7 @@ endif::[] == Suggested reading ifndef::env-cloud[] * xref:manage:schema-reg/schema-reg-overview.adoc[] +* xref:manage:schema-reg/schema-reg-contexts.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry.adoc[rpk registry] * link:/api/doc/schema-registry/[Schema Registry API] * xref:reference:node-configuration-sample.adoc[] (search for `schema_registry`) @@ -1197,6 +1241,7 @@ ifndef::env-cloud[] endif::[] ifdef::env-cloud[] * xref:manage:schema-reg/schema-reg-overview.adoc[] +* xref:manage:schema-reg/schema-reg-contexts.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry.adoc[rpk registry] * link:/api/doc/schema-registry/[Schema Registry API] * xref:manage:monitoring.adoc#service-level-queries[Monitor Schema Registry service-level metrics] diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index a099b44dbc..90ed21dc35 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -704,6 +704,7 @@ curl -s -X DELETE http://localhost:8081/contexts/.staging * xref:manage:schema-reg/schema-reg-overview.adoc[] * xref:manage:schema-reg/schema-reg-api.adoc[] * xref:manage:schema-reg/schema-reg-authorization.adoc[] +* link:/api/doc/schema-registry/[Schema Registry API reference] * xref:reference:public-metrics-reference.adoc[] ifndef::env-cloud[] * xref:reference:cluster-properties.adoc[] From b04e90ed06835625200a86cc51baa6c59ed18ce5 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:26:18 -0500 Subject: [PATCH 17/51] Apply suggestion from @Feediver1 --- .../pages/schema-reg/schema-reg-contexts.adoc | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 90ed21dc35..517f4d5283 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -1,14 +1,13 @@ = Schema Registry Contexts :description: Use Schema Registry contexts to create isolated namespaces for schemas, subjects, and configuration—enabling multi-tenant and multi-team deployments without separate Schema Registry instances. :page-tags: [Schema Registry, contexts, multi-tenant, Confluent compatibility] -// Learning objectives: -// - Understand what Schema Registry contexts are and when to use them. -// - Understand the qualified subject syntax (::). -// - Enable the feature using the cluster configuration property (requires broker restart). -// - Configure contexts, including per-context mode and compatibility settings. -// - Apply ACLs to control access at the context level. -// - Identify updated metrics and the new cluster configuration property. -// - Resolve common issues related to upgrade, schema ID lookups, and subject naming. +Learning objectives: +:learning-objective-1: Understand what Schema Registry contexts are and when to use them. +:learning-objective-2: Understand the qualified subject syntax (::). +:learning-objective-3: Enable the feature using the cluster configuration property (requires broker restart), and configuring contexts, including per-context mode and compatibility settings. +:learning-objective-4: Apply ACLs to control access at the context level. +:learning-objective-5: Identify updated metrics and the new cluster configuration property. +:learning-objective-6: Resolve common issues related to upgrade, schema ID lookups, and subject naming. // Single-sourcing tags: Cloud-only content is wrapped in ifdef::env-cloud[] ... endif::[] // Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] From a5488968364d61b3b02359fd70b84fe31d750f10 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:28:16 -0500 Subject: [PATCH 18/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 +- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 6316c87124..5a58200f9b 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -242,7 +242,7 @@ When you register an evolved schema for an existing subject, the version `id` is == Use Schema Registry contexts -Starting in Redpanda version 26.1, you can use contexts to create isolated namespaces for schemas, subjects, and configuration within a single Schema Registry instance. +Starting in Redpanda v26.1, you can use contexts to create isolated namespaces for schemas, subjects, and configuration within a single Schema Registry instance. ifndef::env-cloud[] To use contexts, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the broker. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions. diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 517f4d5283..dceed30e80 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -13,6 +13,14 @@ Learning objectives: // Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] // tag::single-source[] + +After reading this page, you will be able to: +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} +* [ ] {learning-objective-4} +* [ ] {learning-objective-5} +* [ ] {learning-objective-6} Schema Registry contexts are namespaces that isolate schemas, subjects, and configurations from one another within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings. Existing schemas will simply continue to work: unqualified subjects remain in the implicit default context From e445bbaa891760031af247fd44d3db04b1e221fb Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 19:29:49 -0500 Subject: [PATCH 19/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index dceed30e80..685398c89b 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -15,6 +15,7 @@ Learning objectives: // tag::single-source[] After reading this page, you will be able to: + * [ ] {learning-objective-1} * [ ] {learning-objective-2} * [ ] {learning-objective-3} From d493995852ddc45878c794c48019768f1b4d94d6 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 19:30:34 -0500 Subject: [PATCH 20/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 685398c89b..93a3550e51 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -16,6 +16,7 @@ Learning objectives: After reading this page, you will be able to: + * [ ] {learning-objective-1} * [ ] {learning-objective-2} * [ ] {learning-objective-3} From 49e88e386029e9ed9a8fa9699ab84eaf3eda0029 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 19:31:42 -0500 Subject: [PATCH 21/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 93a3550e51..2e9b8e2549 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -16,13 +16,14 @@ Learning objectives: After reading this page, you will be able to: - * [ ] {learning-objective-1} * [ ] {learning-objective-2} * [ ] {learning-objective-3} * [ ] {learning-objective-4} * [ ] {learning-objective-5} * [ ] {learning-objective-6} +* [ ] + Schema Registry contexts are namespaces that isolate schemas, subjects, and configurations from one another within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings. Existing schemas will simply continue to work: unqualified subjects remain in the implicit default context From fbeee429ba74b041688e8dd0b18da07d58ac9ada Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 20 Apr 2026 22:09:12 -0400 Subject: [PATCH 22/51] docs(DOC-1658): add Schema Registry contexts to What's New Co-Authored-By: Claude Sonnet 4.6 --- modules/get-started/pages/release-notes/redpanda.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 951d538456..240eaea332 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -77,6 +77,12 @@ Key characteristics: See xref:manage:cluster-maintenance/continuous-data-balancing.adoc[] for configuration details. +== Schema Registry contexts + +Redpanda {page-component-version} introduces xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry contexts], namespaces that isolate schemas, subjects, and configurations within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings, so teams can share a Schema Registry without risking naming collisions or configuration drift. + +To enable contexts, set xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] to `true` and restart your brokers. Once enabled, you reference schemas using qualified subject syntax, for example `:.staging:my-topic-value`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for configuration examples and limitations. + == New configuration properties **Storage mode:** From 2f9d3df9e16f27b737b8a202d5cbe26d26c43bb7 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 21:11:53 -0500 Subject: [PATCH 23/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 61 ++++++++++--------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 2e9b8e2549..66495bc88d 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -3,7 +3,7 @@ :page-tags: [Schema Registry, contexts, multi-tenant, Confluent compatibility] Learning objectives: :learning-objective-1: Understand what Schema Registry contexts are and when to use them. -:learning-objective-2: Understand the qualified subject syntax (::). +:learning-objective-2: Understand the qualified subject syntax (`::`). :learning-objective-3: Enable the feature using the cluster configuration property (requires broker restart), and configuring contexts, including per-context mode and compatibility settings. :learning-objective-4: Apply ACLs to control access at the context level. :learning-objective-5: Identify updated metrics and the new cluster configuration property. @@ -22,7 +22,6 @@ After reading this page, you will be able to: * [ ] {learning-objective-4} * [ ] {learning-objective-5} * [ ] {learning-objective-6} -* [ ] Schema Registry contexts are namespaces that isolate schemas, subjects, and configurations from one another within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings. @@ -69,12 +68,13 @@ The `schema_registry_enable_qualified_subjects` property defaults to `false`, so == How Schema Registry contexts work +When you enable contexts, Schema Registry changes how it assigns schema IDs, resolves configuration, and interprets subject names. === Schema ID isolation -Before contexts, the Schema Registry maintained a single global ID counter. All schemas shared one ID space, and a given schema ID pointed to exactly one schema across the entire registry. +Prior to v26.1, the Schema Registry maintained a single global ID counter. All schemas shared one ID space, and a given schema ID pointed to exactly one schema across the entire registry. -After enabling contexts, each context has its own independent ID counter. This means schema ID `1` in `.staging` and schema ID `1` in `.production` are different schemas. As a result (and by default), `GET /schemas/ids/{id}` searches the _default context only_. To retrieve a schema by ID from a non-default context, you must pass the `subject` query parameter to scope the lookup: +With Schema Registry contexts, each context has its own independent ID counter. This means schema ID `1` in `.staging` and schema ID `1` in `.production` are different schemas. As a result (and by default), `GET /schemas/ids/{id}` searches the _default context only_. To retrieve a schema by ID from a non-default context, you must pass the `subject` query parameter to scope the lookup: [source,bash] ---- @@ -85,7 +85,7 @@ See also <>. === Configuration resolution order -Before contexts, mode and compatibility settings resolved as: +Prior to v26.1, mode and compatibility settings resolved as: ---- Subject → Global → Built-in defaults @@ -128,7 +128,7 @@ Wherever the Schema Registry API accepts a subject, you can supply a qualified s === `GET /subjects` behavior change -After enabling the flag, `GET /subjects` (with no `subjectPrefix`) returns subjects across *all* contexts. Non-default context subjects appear with their qualified names — for example, `:.staging:my-topic`. This is a behavioral change from the previous flat list of bare subject names. +After enabling the flag, `GET /subjects` (with no `subjectPrefix`) returns subjects across _all_ contexts. Non-default context subjects appear with their qualified names (for example, `:.staging:my-topic`). Note that this is differs from the previous flat lists of bare subject names. === Cross-context schema references @@ -137,7 +137,7 @@ Contexts do not enforce isolation of schema references. Schemas can reference sc == Enable Schema Registry contexts ifndef::env-cloud[] -To enable contexts on a self-managed cluster, set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`: +To enable contexts, set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`: [source,bash] ---- @@ -165,6 +165,7 @@ endif::env-cloud[] === Register a schema in a context +The following configuration examples show how to perform common context operations using the Schema Registry HTTP API and qualified subject syntax. To register a schema in a named context, use the qualified subject form in the `POST /subjects/{subject}/versions` request: [source,bash] @@ -341,7 +342,7 @@ Unqualified references in schema definitions resolve to the same context as the === Delete a context -A context can only be deleted when it contains no subjects. Soft-deleted subjects still count — you must hard-delete all subjects before the context can be removed. Attempting to delete a non-empty context returns a `context_not_empty` error. +You can only delete a context when it contains no subjects. Soft-deleted subjects still count; however, you must hard-delete all subjects before removing the context. Attempting to delete a non-empty context returns a `context_not_empty` error. [NOTE] ==== @@ -358,11 +359,11 @@ curl -s -X DELETE http://localhost:8081/contexts/.staging ---- -== rpk commands +== Configure Schema Registry contexts using rpk [NOTE] ==== -Native `rpk` commands for context management operations (listing, creating, and deleting contexts) are not yet available. Use the Schema Registry HTTP API directly for context-level operations. See <>. +Native `rpk` commands for context management operations (listing, creating, and deleting contexts) are not available. Use the Schema Registry HTTP API for context-level operations. See <>. ==== Existing `rpk registry` commands that accept a subject name support qualified subject syntax once `schema_registry_enable_qualified_subjects` is enabled. Pass a qualified subject wherever a `--subject` flag is accepted: @@ -422,7 +423,7 @@ rpk security acl create \ --allow-principal User:alice ---- -For full reference documentation on these commands, see: +For additional detail, refer to the full reference documentation for these commands: * xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry-schema-list.adoc[] @@ -437,6 +438,7 @@ For full reference documentation on these commands, see: == Client integration status +The following table identifies the support level of Schema Registry context client integrations. [#client-integration-status] [cols="2,1,3", options="header"] @@ -444,7 +446,7 @@ For full reference documentation on these commands, see: | Client | Status | Notes | Schema Registry API (all operations) -| Full support +| Supported | Use qualified subjects directly in any endpoint. | Java SerDe (Confluent) @@ -452,27 +454,27 @@ For full reference documentation on these commands, see: | Requires a custom `ContextNameStrategy`. See the Confluent SerDe documentation for details. | Non-Java SerDe -| Not yet supported (26.1) -| Planned in a 26.1.x patch release. Workaround: set the client's Schema Registry base URL to `http://:8081/contexts/{context}`. +| Not supported +| Workaround: set the client's Schema Registry base URL to `http://:8081/contexts/{context}`. | rpk -| In progress -| Context management commands not yet available. Qualified subjects work in existing `rpk registry` commands. +| Not supported +| Context management commands not available. Qualified subjects work in existing `rpk registry` commands. | Redpanda Console -| In progress -| Not available in 26.1. +| Not supported +| | Server-side schema ID validation | Not supported -| Out of scope for this release. +| |=== == ACL authorization [#acl-authorization] -Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. No new resource types are needed. +Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. [cols="2,2,2", options="header"] |=== @@ -519,7 +521,7 @@ rpk security acl create \ === Audit log format -When Schema Registry ACLs are enabled, audit log entries include the fully qualified subject name for non-default context operations: +When you enable Schema Registry ACLs, audit log entries include the fully qualified subject name for non-default context operations: [source,json] ---- @@ -533,11 +535,11 @@ When Schema Registry ACLs are enabled, audit log entries include the fully quali } ---- -Default context subjects are logged with their unqualified name (no change from existing behavior). +Default context subjects are logged with their unqualified name. == Metrics -The following Schema Registry metrics have been updated to include a `context` label, enabling per-context monitoring: +The following Schema Registry metrics include a `context` label, enabling per-context monitoring: [cols="2,2", options="header"] |=== @@ -565,12 +567,12 @@ endif::env-cloud[] [IMPORTANT] ==== -*Breaking change*: When `schema_registry_enable_qualified_subjects` is enabled, any existing subject whose name matches the qualified subject pattern — for example, `:.staging:user-value` — is reinterpreted as subject `user-value` in context `.staging`, rather than as a literal subject name in the default context. Subjects without a `:.` prefix are unaffected. +*Breaking change*: When `schema_registry_enable_qualified_subjects` is enabled, any existing subject whose name matches the qualified subject pattern (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging`, rather than as a literal subject name in the default context. Subjects without a `:.` prefix are unaffected. -This edge case is expected to be rare. No automatic migration is provided. +This edge case is rare. No automatic migration is provided. ==== -To audit your existing subjects for affected names before enabling the feature: +To audit your existing subjects for affected names before enabling Schema Registry contexts: ifndef::env-cloud[] [source,bash] @@ -586,7 +588,7 @@ curl -s http://:8081/subjects | jq '.[] | select(startswit ---- endif::env-cloud[] -If affected subjects are found, rename them before enabling the property, or plan to re-register them under the reinterpreted context structure after enabling. +If you find affected subjects, rename them before enabling the property, or plan to re-register them under the reinterpreted context structure after enabling. [IMPORTANT] @@ -596,6 +598,7 @@ Remember that changing `schema_registry_enable_qualified_subjects` requires a br == Troubleshooting +Following is troubleshooting guidance for Schema Registry contexts. [#schema-id-lookup-fails] === Schema ID lookup returns 404 or wrong schema @@ -614,7 +617,7 @@ curl -s "http://localhost:8081/schemas/ids/1?subject=:.staging:my-topic" *Symptom*: Subjects with the `:.` prefix are stored as literal subject names in the default context instead of being parsed as context-qualified subjects. -*Cause 1*: `schema_registry_enable_qualified_subjects` is set to `false` (the 26.1 default for self-managed clusters). +*Cause 1*: `schema_registry_enable_qualified_subjects` is set to `false` (the default). *Cause 2*: The property was set to `true` but the brokers have not yet been restarted. This property is not dynamic and requires a full broker restart to take effect. @@ -628,7 +631,7 @@ rpk cluster config set schema_registry_enable_qualified_subjects true ---- endif::env-cloud[] -=== Schema registration fails after upgrading to 26.1 +=== Schema registration fails after upgrading to v26.1 *Symptom*: A `POST /subjects/{subject}/versions` request returns an unexpected error after upgrading and enabling the flag. From 304d7ee894dca9852b7fa9b43239cc882f3f7444 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 20 Apr 2026 22:14:17 -0400 Subject: [PATCH 24/51] fix: restore cloud-docs branch to main in local-antora-playbook.yml Co-Authored-By: Claude Sonnet 4.6 --- local-antora-playbook.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 9c61c888e5..fe2fe8c63b 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -18,7 +18,7 @@ content: - url: https://github.com/redpanda-data/docs branches: [v/*, shared, site-search,'!v-end-of-life/*'] - url: https://github.com/redpanda-data/cloud-docs - branches: DOC-1812-Document-Cloud-Feature-Schema-Registry-Contexts-Serverless-etc + branches: main - url: https://github.com/redpanda-data/redpanda-labs branches: main start_paths: [docs,'*/docs'] From 915b5fe822fca957dd0309ccd59485588f2b1e30 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 20 Apr 2026 22:18:14 -0400 Subject: [PATCH 25/51] chore: trigger Netlify preview rebuild From b2a92111af93168670f8d4a4ebc0f8acd3a39b48 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 20 Apr 2026 22:21:15 -0400 Subject: [PATCH 26/51] docs(DOC-1658): reduce learning objectives to 3 Co-Authored-By: Claude Sonnet 4.6 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 6 ------ 1 file changed, 6 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 66495bc88d..04a64a3b5f 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -5,9 +5,6 @@ Learning objectives: :learning-objective-1: Understand what Schema Registry contexts are and when to use them. :learning-objective-2: Understand the qualified subject syntax (`::`). :learning-objective-3: Enable the feature using the cluster configuration property (requires broker restart), and configuring contexts, including per-context mode and compatibility settings. -:learning-objective-4: Apply ACLs to control access at the context level. -:learning-objective-5: Identify updated metrics and the new cluster configuration property. -:learning-objective-6: Resolve common issues related to upgrade, schema ID lookups, and subject naming. // Single-sourcing tags: Cloud-only content is wrapped in ifdef::env-cloud[] ... endif::[] // Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] @@ -19,9 +16,6 @@ After reading this page, you will be able to: * [ ] {learning-objective-1} * [ ] {learning-objective-2} * [ ] {learning-objective-3} -* [ ] {learning-objective-4} -* [ ] {learning-objective-5} -* [ ] {learning-objective-6} Schema Registry contexts are namespaces that isolate schemas, subjects, and configurations from one another within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings. From 9802088cbe73cf87675431366859ae17467e299b Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 21:50:58 -0500 Subject: [PATCH 27/51] Apply suggestion from @Feediver1 --- modules/get-started/pages/release-notes/redpanda.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 240eaea332..0d5b53ad62 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -79,7 +79,7 @@ See xref:manage:cluster-maintenance/continuous-data-balancing.adoc[] for configu == Schema Registry contexts -Redpanda {page-component-version} introduces xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry contexts], namespaces that isolate schemas, subjects, and configurations within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings, so teams can share a Schema Registry without risking naming collisions or configuration drift. +xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry contexts] are namespaces that isolate schemas, subjects, and configurations within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings, so teams can share a Schema Registry without risking naming collisions or configuration drift. To enable contexts, set xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] to `true` and restart your brokers. Once enabled, you reference schemas using qualified subject syntax, for example `:.staging:my-topic-value`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for configuration examples and limitations. From c84400aa85b1d42d1840ab6fa41605fc54bbbfaf Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Apr 2026 21:53:22 -0500 Subject: [PATCH 28/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 04a64a3b5f..4cc60be25f 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -3,7 +3,7 @@ :page-tags: [Schema Registry, contexts, multi-tenant, Confluent compatibility] Learning objectives: :learning-objective-1: Understand what Schema Registry contexts are and when to use them. -:learning-objective-2: Understand the qualified subject syntax (`::`). +:learning-objective-2: Understand the qualified subject syntax. :learning-objective-3: Enable the feature using the cluster configuration property (requires broker restart), and configuring contexts, including per-context mode and compatibility settings. // Single-sourcing tags: Cloud-only content is wrapped in ifdef::env-cloud[] ... endif::[] From ffa12f51956b9d28521ea08319f44f01aba618f0 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Tue, 21 Apr 2026 18:29:09 -0500 Subject: [PATCH 29/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 42 +++++++++++-------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 4cc60be25f..5f5481ad1f 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -1,27 +1,29 @@ = Schema Registry Contexts -:description: Use Schema Registry contexts to create isolated namespaces for schemas, subjects, and configuration—enabling multi-tenant and multi-team deployments without separate Schema Registry instances. +:description: Use Schema Registry contexts to create isolated namespaces for schemas, subjects, and configuration, enabling multi-tenant and multi-team deployments without separate Schema Registry instances. :page-tags: [Schema Registry, contexts, multi-tenant, Confluent compatibility] -Learning objectives: -:learning-objective-1: Understand what Schema Registry contexts are and when to use them. -:learning-objective-2: Understand the qualified subject syntax. -:learning-objective-3: Enable the feature using the cluster configuration property (requires broker restart), and configuring contexts, including per-context mode and compatibility settings. +:page-topic-type: how-to +:personas: app_developer, streaming_developer, platform_admin +:learning-objective-1: Identify when to use Schema Registry contexts for multi-team or multi-cluster deployments. +:learning-objective-2: Describe how qualified subject syntax maps subjects to contexts. +:learning-objective-3: Enable and configure Schema Registry contexts using the cluster property and HTTP API. // Single-sourcing tags: Cloud-only content is wrapped in ifdef::env-cloud[] ... endif::[] // Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] // tag::single-source[] +Schema Registry contexts are namespaces that isolate schemas, subjects, and configurations from one another within a single Schema Registry instance. +Each context maintains its own schema ID counter, mode settings, and compatibility settings. +Existing schemas will simply continue to work: unqualified subjects remain in the implicit default context + +Schema Registry contexts are compatible with the Confluent Schema Registry Contexts API. + After reading this page, you will be able to: * [ ] {learning-objective-1} * [ ] {learning-objective-2} * [ ] {learning-objective-3} -Schema Registry contexts are namespaces that isolate schemas, subjects, and configurations from one another within a single Schema Registry instance. -Each context maintains its own schema ID counter, mode settings, and compatibility settings. -Existing schemas will simply continue to work: unqualified subjects remain in the implicit default context - -Schema Registry contexts is compatible with the Confluent Schema Registry Contexts API. == When to use contexts @@ -39,8 +41,8 @@ endif::env-cloud[] Before using Schema Registry contexts, ensure that: -* You are running Redpanda v26.1 or later. -* The `schema_registry_enable_qualified_subjects` cluster configuration property is set to `true`. +* You are running xref:get-started:release-notes/redpanda.adoc[Redpanda v26.1] or later. +* The xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster configuration property is set to `true`. + [IMPORTANT] ==== @@ -122,7 +124,8 @@ Wherever the Schema Registry API accepts a subject, you can supply a qualified s === `GET /subjects` behavior change -After enabling the flag, `GET /subjects` (with no `subjectPrefix`) returns subjects across _all_ contexts. Non-default context subjects appear with their qualified names (for example, `:.staging:my-topic`). Note that this is differs from the previous flat lists of bare subject names. +After enabling the flag, `GET /subjects` (with no `subjectPrefix`) returns subjects across _all_ contexts. Non-default context subjects appear with their qualified names (for example, `:.staging:my-topic`). +Note that this differs from the previous flat lists of bare subject names. === Cross-context schema references @@ -157,6 +160,8 @@ endif::env-cloud[] == Configure Schema Registry contexts +Following are the various configuration options available for Schema Registry contexts. + === Register a schema in a context The following configuration examples show how to perform common context operations using the Schema Registry HTTP API and qualified subject syntax. @@ -295,6 +300,7 @@ This is useful when schemas span multiple contexts and you need to disambiguate You can point a Schema Registry client at a specific context by setting the client's Schema Registry URL to `${host}/contexts/{context}`. Redpanda rewrites requests under this path prefix to operate within the specified context. This is the recommended workaround for non-Java SerDe clients that do not yet support qualified subject syntax natively: +[source,text] ---- # All requests to this base URL operate within the .staging context http://localhost:8081/contexts/.staging @@ -430,10 +436,11 @@ For additional detail, refer to the full reference documentation for these comma * xref:reference:rpk/rpk-registry/rpk-registry-subject-delete.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry-subject-list.adoc[] +[#client-integration-status] == Client integration status The following table identifies the support level of Schema Registry context client integrations. -[#client-integration-status] + [cols="2,1,3", options="header"] |=== @@ -457,13 +464,14 @@ The following table identifies the support level of Schema Registry context clie | Redpanda Console | Not supported -| +| N/A | Server-side schema ID validation | Not supported -| +| N/A |=== +[#acl-authorization] == ACL authorization [#acl-authorization] @@ -706,7 +714,7 @@ curl -s -X DELETE http://localhost:8081/contexts/.staging *Resolution*: There is no workaround. To identify which schema an ID belongs to, try resolving the ID against each relevant context using `GET /schemas/ids/{id}?subject=::`. -== Related topics +== Suggested reading * xref:manage:schema-reg/schema-reg-overview.adoc[] * xref:manage:schema-reg/schema-reg-api.adoc[] From 14f8c6e62a38fdb564235acc61f7b838894ab696 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Tue, 21 Apr 2026 18:40:06 -0500 Subject: [PATCH 30/51] Update modules/manage/pages/schema-reg/schema-reg-contexts.adoc --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 5f5481ad1f..20a4b0da00 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -474,7 +474,6 @@ The following table identifies the support level of Schema Registry context clie [#acl-authorization] == ACL authorization -[#acl-authorization] Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. From 4e10c4292eda870c1b19bb8e09296ad65ce1ba59 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 22 Apr 2026 09:08:19 -0500 Subject: [PATCH 31/51] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gellért Peresztegi-Nagy Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 20a4b0da00..d812b85527 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -54,7 +54,7 @@ The `schema_registry_enable_qualified_subjects` property defaults to `false`, so == Limitations * *Console and rpk*: Native support for context management operations (listing, creating, and deleting contexts) in the Redpanda Console UI and `rpk` CLI is not available. Use the Schema Registry HTTP API directly. See <>. -* *Non-Java SerDe clients*: Non-Java serializer/deserializer clients do not natively support qualified subjects. Instead, point these clients at the `/contexts/{context}/...` base URL path prefix. See <>. +* *Non-Java SerDe clients*: Not supported in Schema Registry contexts. * *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts. * *Iceberg topics*: Context-aware schema IDs are not surfaced in Iceberg topic integration. * *`referencedby` endpoint*: `GET /subjects/{subject}/versions/{version}/referencedby` returns a list of bare schema IDs with no context information. When references span contexts, it is not possible to determine which context each returned ID belongs to. @@ -84,7 +84,7 @@ See also <>. Prior to v26.1, mode and compatibility settings resolved as: ---- -Subject → Global → Built-in defaults +Subject → (default) Context → Built-in defaults ---- After enabling contexts, a context layer sits between subject and global: @@ -340,9 +340,23 @@ Schemas can reference schemas in other contexts using qualified subject names in Unqualified references in schema definitions resolve to the same context as the root schema, not the default context. +[source,json] +---- +{ + "schema": "...", + "references": [ + { + "name": "CommonType", + "subject": "CommonType", // assumes CommonType is a subject is in the same context as the root schema + "version": 1 + } + ] +} +---- + === Delete a context -You can only delete a context when it contains no subjects. Soft-deleted subjects still count; however, you must hard-delete all subjects before removing the context. Attempting to delete a non-empty context returns a `context_not_empty` error. +You can only delete a context when it contains no subjects. Soft-deleted subjects still count; so, you must hard-delete all subjects before removing the context. Attempting to delete a non-empty context returns a `context_not_empty` error. [NOTE] ==== @@ -556,8 +570,6 @@ The following Schema Registry metrics include a `context` label, enabling per-co | New `context` label added. |=== -The count of non-default contexts is also included in Redpanda's phone-home telemetry. - For the full metrics reference, see xref:reference:public-metrics-reference.adoc[]. ifndef::env-cloud[] @@ -589,7 +601,7 @@ curl -s http://:8081/subjects | jq '.[] | select(startswit ---- endif::env-cloud[] -If you find affected subjects, rename them before enabling the property, or plan to re-register them under the reinterpreted context structure after enabling. +If you find affected subjects, rename them before enabling the property, or create a new cluster with contexts enabled and import the schemas into the new cluster, where they will be interpreted as context-aware subjects. [IMPORTANT] From 3d7c99676b7306b67858802f15fcf82303ad88a0 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 22 Apr 2026 09:22:12 -0500 Subject: [PATCH 32/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index d812b85527..98503e219b 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -53,7 +53,6 @@ The `schema_registry_enable_qualified_subjects` property defaults to `false`, so == Limitations -* *Console and rpk*: Native support for context management operations (listing, creating, and deleting contexts) in the Redpanda Console UI and `rpk` CLI is not available. Use the Schema Registry HTTP API directly. See <>. * *Non-Java SerDe clients*: Not supported in Schema Registry contexts. * *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts. * *Iceberg topics*: Context-aware schema IDs are not surfaced in Iceberg topic integration. From 37869ad44c8bd73cfa0c80b928f6ddcf8854f284 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 22 Apr 2026 09:29:02 -0500 Subject: [PATCH 33/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/schema-reg/schema-reg-contexts.adoc | 69 +++++++++---------- 1 file changed, 34 insertions(+), 35 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 98503e219b..50150e3ef9 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -130,6 +130,38 @@ Note that this differs from the previous flat lists of bare subject names. Contexts do not enforce isolation of schema references. Schemas can reference schemas in any other context. Unqualified references in schema definitions resolve within the same context as the root schema, not the default context. Qualified references can reach any context explicitly (for example, `:.shared:CommonType`). +Schemas can reference schemas in other contexts using qualified subject names in the `references` field: + +[source,json] +---- +{ + "schema": "...", + "references": [ + { + "name": "CommonType", + "subject": ":.shared:CommonType", + "version": 1 + } + ] +} +---- + +Unqualified references in schema definitions resolve to the same context as the root schema, not the default context. + +[source,json] +---- +{ + "schema": "...", + "references": [ + { + "name": "CommonType", + "subject": "CommonType", // assumes CommonType is a subject is in the same context as the root schema + "version": 1 + } + ] +} +---- + == Enable Schema Registry contexts ifndef::env-cloud[] @@ -159,7 +191,7 @@ endif::env-cloud[] == Configure Schema Registry contexts -Following are the various configuration options available for Schema Registry contexts. +The following configuration examples show how to perform common context operations. === Register a schema in a context @@ -319,39 +351,6 @@ curl -s -X PUT \ Schema registrations in `:.new-team:` will be rejected until the mode is changed to `READWRITE`. -=== Cross-context schema references - -Schemas can reference schemas in other contexts using qualified subject names in the `references` field: - -[source,json] ----- -{ - "schema": "...", - "references": [ - { - "name": "CommonType", - "subject": ":.shared:CommonType", - "version": 1 - } - ] -} ----- - -Unqualified references in schema definitions resolve to the same context as the root schema, not the default context. - -[source,json] ----- -{ - "schema": "...", - "references": [ - { - "name": "CommonType", - "subject": "CommonType", // assumes CommonType is a subject is in the same context as the root schema - "version": 1 - } - ] -} ----- === Delete a context @@ -452,7 +451,7 @@ For additional detail, refer to the full reference documentation for these comma [#client-integration-status] == Client integration status -The following table identifies the support level of Schema Registry context client integrations. +The following table identifies the status of Schema Registry context client integrations. [cols="2,1,3", options="header"] From fdd8cf8b427a48fe36d1e13fd0d7c11fec89cae6 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 22 Apr 2026 10:41:54 -0400 Subject: [PATCH 34/51] Add Schema Registry contexts section to Console schema-reg page --- modules/console/pages/ui/schema-reg.adoc | 31 +++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/modules/console/pages/ui/schema-reg.adoc b/modules/console/pages/ui/schema-reg.adoc index dbb4cc033e..9f90f66541 100644 --- a/modules/console/pages/ui/schema-reg.adoc +++ b/modules/console/pages/ui/schema-reg.adoc @@ -101,11 +101,40 @@ include::manage:partial$schema-compatibility.adoc[] Select a schema to soft-delete a version of it or all schemas of its subject. Schemas cannot be deleted if any other schemas reference it. A soft-deleted schema can be recovered, but a permanently-deleted schema cannot be recovered. Redpanda does not recommend permanently deleting schemas in a production environment. + +== Schema Registry contexts + +Schema Registry contexts are namespaces that group subjects and schemas within a single Schema Registry instance. For context configuration details and prerequisites, see xref:manage:schema-reg/schema-reg-contexts.adoc[]. + +ifdef::env-cloud[] +NOTE: On Serverless clusters, Redpanda manages contexts internally for per-tenant isolation and does not expose them to end users. On BYOC and Dedicated clusters, contexts are available and user-configurable. +endif::env-cloud[] + +=== How Console uses contexts + +When Schema Registry contexts are enabled in your cluster, Console provides context-aware subject browsing and management. + +Console lists subjects according to their context, using context-capable APIs to ensure subjects and their versions come from the correct namespace. + +When you open a subject, Console fetches its schema versions using both the subject name and its context. This avoids ambiguity when the same subject name exists in multiple contexts. + +Console surfaces Schema Registry mode and compatibility settings and, where supported, lets you adjust them at: + +* Global level (entire registry) +* Subject level (within a specific context) + +This lets you apply safe defaults globally while fine-tuning behavior for individual subjects in specific contexts. + +=== Automatic feature detection + +Console automatically detects whether Schema Registry contexts are available. If contexts are supported, Console shows context-aware UI and uses context-specific APIs. If contexts are not supported, Console falls back to a standard non-context view, so you can continue working with schemas without errors. + == Suggested reading ifndef::env-cloud[] * xref:console:config/deserialization.adoc[] endif::[] * xref:manage:schema-reg/schema-reg-overview.adoc[] +* xref:manage:schema-reg/schema-reg-contexts.adoc[] -// end::single-source[] +// end::single-source[] \ No newline at end of file From aa094ce3f56ed480f9fdbd8919a5fb434b3af247 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 22 Apr 2026 11:02:12 -0400 Subject: [PATCH 35/51] Add anchor and link to Cross-context schema references heading --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 50150e3ef9..e18d63b29b 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -126,6 +126,7 @@ Wherever the Schema Registry API accepts a subject, you can supply a qualified s After enabling the flag, `GET /subjects` (with no `subjectPrefix`) returns subjects across _all_ contexts. Non-default context subjects appear with their qualified names (for example, `:.staging:my-topic`). Note that this differs from the previous flat lists of bare subject names. +[#cross-context-schema-references] === Cross-context schema references Contexts do not enforce isolation of schema references. Schemas can reference schemas in any other context. Unqualified references in schema definitions resolve within the same context as the root schema, not the default context. Qualified references can reach any context explicitly (for example, `:.shared:CommonType`). @@ -325,7 +326,7 @@ Use `referenceFormat=qualified` on `GET /subjects/{subject}/versions/{version}` curl -s "http://localhost:8081/subjects/:.staging:my-topic/versions/1?referenceFormat=qualified" ---- -This is useful when schemas span multiple contexts and you need to disambiguate reference targets. +This is useful when schemas span multiple contexts and you need to disambiguate reference targets. See <>. === Use a context as the client base URL From ef3312c0248bb1415a30681cb5d1a1e1ca86ce2d Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 22 Apr 2026 10:57:17 -0500 Subject: [PATCH 36/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/console/pages/ui/schema-reg.adoc | 5 ++++- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/modules/console/pages/ui/schema-reg.adoc b/modules/console/pages/ui/schema-reg.adoc index 9f90f66541..755e544bce 100644 --- a/modules/console/pages/ui/schema-reg.adoc +++ b/modules/console/pages/ui/schema-reg.adoc @@ -127,7 +127,10 @@ This lets you apply safe defaults globally while fine-tuning behavior for indivi === Automatic feature detection -Console automatically detects whether Schema Registry contexts are available. If contexts are supported, Console shows context-aware UI and uses context-specific APIs. If contexts are not supported, Console falls back to a standard non-context view, so you can continue working with schemas without errors. +Console automatically detects whether Schema Registry contexts are available: + +* If contexts are supported, Console shows context-aware UI and uses context-specific APIs. +* If contexts are not supported, Console falls back to a standard non-context view, so you can continue working with schemas without errors. == Suggested reading diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index e18d63b29b..839e750b97 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -156,7 +156,7 @@ Unqualified references in schema definitions resolve to the same context as the "references": [ { "name": "CommonType", - "subject": "CommonType", // assumes CommonType is a subject is in the same context as the root schema + "subject": "CommonType", // Assumed that CommonType is a subject is in the same context as the root schema "version": 1 } ] From 22a29caf728908ec0a6239f3bf3dd5b0a71b6800 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 22 Apr 2026 11:43:44 -0500 Subject: [PATCH 37/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 839e750b97..a7825821cd 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -156,7 +156,7 @@ Unqualified references in schema definitions resolve to the same context as the "references": [ { "name": "CommonType", - "subject": "CommonType", // Assumed that CommonType is a subject is in the same context as the root schema + "subject": "CommonType", // Assumed that CommonType is a subject in the same context as the root schema "version": 1 } ] From 3b24e2bee0a09536890c825fb92753b4a8ea3002 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 23 Apr 2026 14:19:03 -0400 Subject: [PATCH 38/51] Add Key concepts section to schema-reg-contexts --- .../pages/schema-reg/schema-reg-contexts.adoc | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index a7825821cd..c7a85a746c 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -37,6 +37,28 @@ ifdef::env-cloud[] NOTE: On Serverless clusters, Redpanda uses contexts internally for per-tenant isolation. Contexts are not exposed to end users on Serverless. On BYOC and Dedicated clusters, contexts are available and user-configurable. endif::env-cloud[] +== Key concepts + +[cols="1,2",options="header"] +|=== +| Term | Definition + +| Context +| A namespace that isolates schemas, subjects, and configuration. Context names start with a dot, for example `.staging`, `.production`, or `.shared`. + +| Default context +| The implicit context (`.`) for unqualified subjects. All existing, unqualified subjects live here. + +| Global context +| `.__GLOBAL` is the lowest-priority fallback for mode and compatibility settings. + +| Qualified subject +| A subject name in the format `::`, for example `:.staging:user-events-value`. + +| Cross-context references +| Schemas can reference schemas in any other context. Contexts are not isolation boundaries and do not prevent cross-context dependencies. Unqualified references resolve within the parent schema's context. +|=== + == Prerequisites Before using Schema Registry contexts, ensure that: From b0a986d3868c156384bd90073d132f2af46db821 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 23 Apr 2026 14:30:43 -0400 Subject: [PATCH 39/51] Fix broken upgrade-considerations anchor on Cloud builds --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index c7a85a746c..a6b6041fac 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -593,10 +593,9 @@ The following Schema Registry metrics include a `context` label, enabling per-co For the full metrics reference, see xref:reference:public-metrics-reference.adoc[]. +[#upgrade-considerations] ifndef::env-cloud[] == Upgrade considerations - -[#upgrade-considerations] endif::env-cloud[] [IMPORTANT] From 7750e0378605cb7a4f94b655e886e46796517155 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Fri, 24 Apr 2026 14:23:59 -0500 Subject: [PATCH 40/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Co-authored-by: Trevor Blackford --- .../pages/schema-reg/schema-reg-api.adoc | 20 ---------------- .../pages/schema-reg/schema-reg-contexts.adoc | 24 ++++--------------- 2 files changed, 5 insertions(+), 39 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 5a58200f9b..06df33a442 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -261,27 +261,7 @@ curl -s -X POST \ -d '{"schema": "{\"type\":\"string\"}"}' ---- -=== Scope API operations to a context -You can scope any Schema Registry API operation to a specific context in two ways: - -* Qualified subjects: Use the `::` syntax wherever a subject is accepted. For example, to list subjects in the `.staging` context: -+ -[source,bash] ----- -curl -s "http://localhost:8081/subjects?subjectPrefix=:.staging:" ----- - -* Base URL prefix: Prefix any endpoint path with `/contexts/{context}/`. The server rewrites the request to operate within that context. This approach is recommended for non-Java SerDe clients that do not support qualified subject syntax: -+ -[source,bash] ----- -curl -s http://localhost:8081/contexts/.staging/subjects ----- - -Unqualified subjects continue to work and operate in the default context. - -For the complete endpoint reference, see the link:/api/doc/schema-registry/[Schema Registry API reference]. == Retrieve a schema diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index a6b6041fac..4ba5c9b8fb 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -31,7 +31,6 @@ Contexts are most useful in the following scenarios: * *Multi-team deployments on a shared cluster*: Teams can register schemas independently under their own contexts without risking naming collisions or configuration drift. * *Schema migration from Confluent Schema Registry*: Confluent Schema Registry uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. -* *Multi-cluster schema syncing and disaster recovery*: Dedicated namespaces reduce schema ID collision risk when syncing schemas across clusters. ifdef::env-cloud[] NOTE: On Serverless clusters, Redpanda uses contexts internally for per-tenant isolation. Contexts are not exposed to end users on Serverless. On BYOC and Dedicated clusters, contexts are available and user-configurable. @@ -44,7 +43,7 @@ endif::env-cloud[] | Term | Definition | Context -| A namespace that isolates schemas, subjects, and configuration. Context names start with a dot, for example `.staging`, `.production`, or `.shared`. +| A namespace that isolates schemas, subjects, and configuration. Context names start with a dot. For example: `.staging`, `.production`, or `.shared`. | Default context | The implicit context (`.`) for unqualified subjects. All existing, unqualified subjects live here. @@ -53,7 +52,7 @@ endif::env-cloud[] | `.__GLOBAL` is the lowest-priority fallback for mode and compatibility settings. | Qualified subject -| A subject name in the format `::`, for example `:.staging:user-events-value`. +| A subject name in the format `::`. For example: `:.staging:user-events-value`. | Cross-context references | Schemas can reference schemas in any other context. Contexts are not isolation boundaries and do not prevent cross-context dependencies. Unqualified references resolve within the parent schema's context. @@ -68,7 +67,7 @@ Before using Schema Registry contexts, ensure that: + [IMPORTANT] ==== -The `schema_registry_enable_qualified_subjects` property defaults to `false`, so you must explicitly enable it. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is the most likely cause. +The `schema_registry_enable_qualified_subjects` property defaults to `false`, so you must explicitly enable it. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is most likely still needed. ==== + * If you use Schema Registry ACLs, ensure the principal interacting with a context has the appropriate permissions. See <>. @@ -153,6 +152,8 @@ Note that this differs from the previous flat lists of bare subject names. Contexts do not enforce isolation of schema references. Schemas can reference schemas in any other context. Unqualified references in schema definitions resolve within the same context as the root schema, not the default context. Qualified references can reach any context explicitly (for example, `:.shared:CommonType`). +NOTE: The _root schema_ is the schema/subject that has the reference. For example, if you register version 1 of subject `:.prod:X` with a reference to `CommonSubject` version 1, then the root schema (to be more precise, the root _subject_) is `:.prox:X`. So in this case, this unqualified reference will resolve to `:.prod:CommonSubject`. + Schemas can reference schemas in other contexts using qualified subject names in the `references` field: [source,json] @@ -282,12 +283,6 @@ curl -s "http://localhost:8081/subjects?subjectPrefix=:.staging:" curl -s "http://localhost:8081/subjects?subjectPrefix=:*:" ---- -You can also list subjects within a context using the `/contexts/{context}/subjects` path: - -[source,bash] ----- -curl -s http://localhost:8081/contexts/.staging/subjects ----- === Set context-level mode @@ -350,15 +345,6 @@ curl -s "http://localhost:8081/subjects/:.staging:my-topic/versions/1?referenceF This is useful when schemas span multiple contexts and you need to disambiguate reference targets. See <>. -=== Use a context as the client base URL - -You can point a Schema Registry client at a specific context by setting the client's Schema Registry URL to `${host}/contexts/{context}`. Redpanda rewrites requests under this path prefix to operate within the specified context. This is the recommended workaround for non-Java SerDe clients that do not yet support qualified subject syntax natively: - -[source,text] ----- -# All requests to this base URL operate within the .staging context -http://localhost:8081/contexts/.staging ----- === Pre-configure a context before registering schemas From ca943dcfd150ca0295681f068413fb10de0ce2d4 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Sun, 26 Apr 2026 14:30:14 -0500 Subject: [PATCH 41/51] Update modules/manage/pages/schema-reg/schema-reg-contexts.adoc Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 4ba5c9b8fb..d1dc73daef 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -152,7 +152,7 @@ Note that this differs from the previous flat lists of bare subject names. Contexts do not enforce isolation of schema references. Schemas can reference schemas in any other context. Unqualified references in schema definitions resolve within the same context as the root schema, not the default context. Qualified references can reach any context explicitly (for example, `:.shared:CommonType`). -NOTE: The _root schema_ is the schema/subject that has the reference. For example, if you register version 1 of subject `:.prod:X` with a reference to `CommonSubject` version 1, then the root schema (to be more precise, the root _subject_) is `:.prox:X`. So in this case, this unqualified reference will resolve to `:.prod:CommonSubject`. +NOTE: The _root schema_ is the schema/subject that has the reference. For example, if you register version 1 of subject `:.prod:X` with a reference to `CommonSubject` version 1, then the root schema (to be more precise, the root _subject_) is `:.prod:X`. So in this case, this unqualified reference will resolve to `:.prod:CommonSubject`. Schemas can reference schemas in other contexts using qualified subject names in the `references` field: From d9c0cc7059cf6fabc60c4e42ade205560f0abf91 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Sun, 26 Apr 2026 14:52:54 -0500 Subject: [PATCH 42/51] Apply suggestion from @kbatuigas Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index d1dc73daef..adf654f58f 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -477,7 +477,7 @@ The following table identifies the status of Schema Registry context client inte | Non-Java SerDe | Not supported -| Workaround: set the client's Schema Registry base URL to `http://:8081/contexts/{context}`. +| Workaround: set the client's Schema Registry base URL to `\http://:8081/contexts/{context}`. | rpk | Not supported From 1b8fc8f64916f6b7186df81f871a698aba8344d9 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Sun, 26 Apr 2026 14:58:35 -0500 Subject: [PATCH 43/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index adf654f58f..0c30782447 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -75,8 +75,8 @@ The `schema_registry_enable_qualified_subjects` property defaults to `false`, so == Limitations * *Non-Java SerDe clients*: Not supported in Schema Registry contexts. -* *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts. -* *Iceberg topics*: Context-aware schema IDs are not surfaced in Iceberg topic integration. +* *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts. However, schema ID validation using magic byte and prefix are supported. +* *Iceberg topics*: You cannot use schemas within a context for Iceberg Topics. * *`referencedby` endpoint*: `GET /subjects/{subject}/versions/{version}/referencedby` returns a list of bare schema IDs with no context information. When references span contexts, it is not possible to determine which context each returned ID belongs to. * *Cross-context isolation*: Contexts provide organizational and ID-space isolation, but do not prevent cross-context schema references. There is no mechanism to block schemas in one context from referencing schemas in another context. * *Default context cannot be deleted*: You cannot delete the default context (`.`). From aa90292f55757af1cb90628b343ea5a9b848dbe1 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 10:59:55 -0500 Subject: [PATCH 44/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 -- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 5 ++--- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 06df33a442..8f026b295b 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -261,8 +261,6 @@ curl -s -X POST \ -d '{"schema": "{\"type\":\"string\"}"}' ---- - - == Retrieve a schema To retrieve a registered schema from the registry, make a GET request to the `/schemas/ids/\{id}` endpoint: diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 0c30782447..91f722844c 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -139,7 +139,7 @@ Wherever the Schema Registry API accepts a subject, you can supply a qualified s | `:.staging:` | `.staging` -| (empty — used for context-level config/mode operations) +| empty (used for context-level config/mode operations) |=== === `GET /subjects` behavior change @@ -215,11 +215,10 @@ endif::env-cloud[] == Configure Schema Registry contexts -The following configuration examples show how to perform common context operations. +The following configuration examples show how to perform common context operations using the Schema Registry HTTP API and qualified subject syntax. === Register a schema in a context -The following configuration examples show how to perform common context operations using the Schema Registry HTTP API and qualified subject syntax. To register a schema in a named context, use the qualified subject form in the `POST /subjects/{subject}/versions` request: [source,bash] From 1a9c6c09c1030b8730e4e5ab2e5492862f4c3a9c Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 12:34:26 -0400 Subject: [PATCH 45/51] Add --schema-context flag, context list/delete commands; update client integration table --- .../pages/schema-reg/schema-reg-contexts.adoc | 139 +++++++++++------- 1 file changed, 89 insertions(+), 50 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 91f722844c..1b63961818 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -381,58 +381,60 @@ curl -s -X DELETE http://localhost:8081/contexts/.staging == Configure Schema Registry contexts using rpk -[NOTE] -==== -Native `rpk` commands for context management operations (listing, creating, and deleting contexts) are not available. Use the Schema Registry HTTP API for context-level operations. See <>. -==== +`rpk registry` supports two equivalent approaches for scoping operations to a context. -Existing `rpk registry` commands that accept a subject name support qualified subject syntax once `schema_registry_enable_qualified_subjects` is enabled. Pass a qualified subject wherever a `--subject` flag is accepted: +=== Use the --schema-context flag + +The `--schema-context` flag is a persistent flag on the `rpk registry` command. Set it once and rpk qualifies all subject names for that context automatically. [source,bash] ---- -# Register a schema in a named context -rpk registry schema create \ - --subject ":.staging:my-topic" \ - --schema my-schema.avsc \ - --type avro - -# List schemas for a subject in a named context -rpk registry schema list \ - --subject ":.staging:my-topic" - -# Get a specific schema version from a context -rpk registry schema get \ - --subject ":.staging:my-topic" \ - --version 1 - -# Check compatibility for a subject in a context -rpk registry schema check-compatibility \ - --subject ":.staging:my-topic" \ - --schema my-schema-v2.avsc - -# Get the compatibility level for a context -rpk registry compatibility-level get \ - --subject ":.staging:" - -# Set the compatibility level for a context -rpk registry compatibility-level set \ - --subject ":.staging:" \ - --level BACKWARD - -# Get the mode for a context -rpk registry mode get \ - --subject ":.staging:" - -# Set the mode for a context -rpk registry mode set \ - --subject ":.staging:" \ - --mode READONLY - -# Delete a subject within a context (soft delete) -rpk registry subject delete \ - --subject ":.staging:my-topic" - -# List all subjects (returns qualified names for non-default contexts) +# Register a schema in the .staging context +rpk registry --schema-context .staging schema create \ + my-topic-value --schema my-schema.avsc + +# List all schemas in the .staging context +rpk registry --schema-context .staging schema list + +# Get a specific schema version from the .staging context +rpk registry --schema-context .staging schema get \ + my-topic-value --schema-version 1 + +# Check schema compatibility in the .staging context +rpk registry --schema-context .staging schema check-compatibility \ + my-topic-value --schema my-schema-v2.avsc + +# Get the compatibility level for the .staging context +rpk registry --schema-context .staging compatibility-level get + +# Set the compatibility level for the .staging context +rpk registry --schema-context .staging compatibility-level set --level BACKWARD + +# Get the mode for the .staging context +rpk registry --schema-context .staging mode get + +# Set the mode for the .staging context +rpk registry --schema-context .staging mode set --mode READONLY + +# Delete a subject within the .staging context (soft delete) +rpk registry --schema-context .staging subject delete my-topic-value + +# List all subjects scoped to the .staging context +rpk registry --schema-context .staging subject list +---- + +Use `--skip-context-check` to bypass the admin API verification of context support (useful when admin API access is unavailable). + +=== Use qualified subject names + +You can also pass context-qualified subject names directly in the `::` format. This is equivalent to using `--schema-context` and the two approaches can be used interchangeably: + +[source,bash] +---- +# Register a schema using a qualified subject +rpk registry schema create ":.staging:my-topic-value" --schema my-schema.avsc + +# List all subjects across all contexts (returns qualified names for non-default contexts) rpk registry subject list # Grant read access to all subjects in a context (prefix ACL) @@ -443,8 +445,45 @@ rpk security acl create \ --allow-principal User:alice ---- +=== Manage contexts + +Use `rpk registry context` to list and delete contexts. + +==== List contexts + +[source,bash] +---- +rpk registry context list +---- + +The output includes the context name and its mode and compatibility settings. + +==== Delete a context + +A context can only be deleted after all subjects within it have been hard-deleted. Soft-deleted subjects still block deletion. + +Before deleting the context, permanently delete all subjects within it: + +[source,bash] +---- +rpk registry --schema-context .staging subject delete --permanent my-topic-value +---- + +Then delete the context: + +[source,bash] +---- +rpk registry context delete .staging +---- + +Use `--no-confirm` to skip the confirmation prompt. + +NOTE: The default context (`.`) cannot be deleted. + For additional detail, refer to the full reference documentation for these commands: +* xref:reference:rpk/rpk-registry/rpk-registry-context-list.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-context-delete.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry-schema-list.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry-schema-get.adoc[] @@ -479,8 +518,8 @@ The following table identifies the status of Schema Registry context client inte | Workaround: set the client's Schema Registry base URL to `\http://:8081/contexts/{context}`. | rpk -| Not supported -| Context management commands not available. Qualified subjects work in existing `rpk registry` commands. +| Supported +| Use `--schema-context` on any `rpk registry` command to scope operations to a context, or pass qualified subjects directly. Use `rpk registry context list` and `rpk registry context delete` to manage contexts. | Redpanda Console | Not supported From 7012e14e22cdfa0a143c8601cee14a56485d8e15 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 11:39:51 -0500 Subject: [PATCH 46/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index 1b63961818..d1e244250a 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -423,7 +423,7 @@ rpk registry --schema-context .staging subject delete my-topic-value rpk registry --schema-context .staging subject list ---- -Use `--skip-context-check` to bypass the admin API verification of context support (useful when admin API access is unavailable). +Use `--skip-context-check` to bypass the admin API verification of context support (useful when Admin API access is unavailable). === Use qualified subject names @@ -618,9 +618,9 @@ The following Schema Registry metrics include a `context` label, enabling per-co For the full metrics reference, see xref:reference:public-metrics-reference.adoc[]. [#upgrade-considerations] -ifndef::env-cloud[] + == Upgrade considerations -endif::env-cloud[] + [IMPORTANT] ==== From 118f48c9c0e32cd9ea2ca06127334759538ffc0f Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 11:46:10 -0500 Subject: [PATCH 47/51] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index d1e244250a..d4b9ae7a26 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -522,7 +522,7 @@ The following table identifies the status of Schema Registry context client inte | Use `--schema-context` on any `rpk registry` command to scope operations to a context, or pass qualified subjects directly. Use `rpk registry context list` and `rpk registry context delete` to manage contexts. | Redpanda Console -| Not supported +| Supported | N/A | Server-side schema ID validation From b3566dc9bced48bc62ef68835c64b845dbf9e30c Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 11:47:46 -0500 Subject: [PATCH 48/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-contexts.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc index d4b9ae7a26..bccfdb82e0 100644 --- a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -526,7 +526,7 @@ The following table identifies the status of Schema Registry context client inte | N/A | Server-side schema ID validation -| Not supported +| Supported (supports schema ID validation in the default context) | N/A |=== From d06bdff986f13886eecfd461fbbe2e9985f77a59 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 11:49:13 -0500 Subject: [PATCH 49/51] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 8f026b295b..801ff228e3 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -245,7 +245,7 @@ When you register an evolved schema for an existing subject, the version `id` is Starting in Redpanda v26.1, you can use contexts to create isolated namespaces for schemas, subjects, and configuration within a single Schema Registry instance. ifndef::env-cloud[] -To use contexts, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the broker. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions. +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. endif::env-cloud[] ifdef::env-cloud[] To use contexts on BYOC and Dedicated clusters, xref:manage:cluster-maintenance/config-cluster.adoc[configure the cluster property] `schema_registry_enable_qualified_subjects`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for details. From 41aad7f913d91d19e2f166a1480f0fc5f89fa6fc Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 14:37:46 -0400 Subject: [PATCH 50/51] Add contexts page to Next steps in schema-reg-overview --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index c8a6485899..5349bc4ffe 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -162,6 +162,7 @@ endif::[] == Next steps * xref:manage:schema-reg/schema-reg-api.adoc[] +* xref:manage:schema-reg/schema-reg-contexts.adoc[] == Suggested reading ifndef::env-cloud[] From 863ae9cbd24c8e163bed6ba1ce6be3be40e4959a Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 27 Apr 2026 14:37:52 -0400 Subject: [PATCH 51/51] Add contexts page to Suggested reading in schema-reg-authorization --- modules/manage/pages/schema-reg/schema-reg-authorization.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-authorization.adoc b/modules/manage/pages/schema-reg/schema-reg-authorization.adoc index 74114f1e83..646bd043eb 100644 --- a/modules/manage/pages/schema-reg/schema-reg-authorization.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-authorization.adoc @@ -675,6 +675,7 @@ Pattern matching uses the string without the asterisk when using `prefixed` type ifndef::env-cloud[] * xref:manage:schema-reg/schema-reg-overview.adoc[] +* xref:manage:schema-reg/schema-reg-contexts.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry.adoc[rpk registry] * link:/api/doc/schema-registry/[Schema Registry API] * xref:reference:node-configuration-sample.adoc[] (search for `schema_registry`) @@ -684,6 +685,7 @@ ifndef::env-cloud[] endif::[] ifdef::env-cloud[] * xref:manage:schema-reg/schema-reg-overview.adoc[] +* xref:manage:schema-reg/schema-reg-contexts.adoc[] * xref:reference:rpk/rpk-registry/rpk-registry.adoc[rpk registry] * link:/api/doc/schema-registry/[Schema Registry API] * xref:manage:monitoring.adoc#service-level-queries[Monitor Schema Registry service-level metrics]