From 64b977823e8b5689e60cba31431babe17db30503 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Thu, 2 Jul 2026 14:53:17 -0400 Subject: [PATCH 01/17] DOC-2254: Add Confluent Schema Registry schema migration via Shadowing Documents the new v26.2 Schema Registry API-mode replication (shadow_schema_registry_api) for shadow links: - New page: Migrate Schemas from Confluent Schema Registry (intro, use cases, prerequisites, limitations, config steps, filtering, context mapping, validation policy, monitoring, failover) - setup.adoc: present topic mode vs API mode in the Schema Registry synchronization section - overview.adoc: add Schema Registry Sync task tab and update the replication lists - monitor.adoc: add Schema Registry sync status bullet - nav.adoc: add nav entry under Shadowing Feature is unreleased (ENG-1171, targets 26.2). DRAFT-VERIFY comments mark items to re-check after redpanda#30999 and redpanda#30984 merge. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/ROOT/nav.adoc | 1 + .../shadowing/migrate-schemas-confluent.adoc | 272 ++++++++++++++++++ .../disaster-recovery/shadowing/monitor.adoc | 1 + .../disaster-recovery/shadowing/overview.adoc | 18 +- .../disaster-recovery/shadowing/setup.adoc | 11 +- 5 files changed, 298 insertions(+), 5 deletions(-) create mode 100644 modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 089097e22c..9706e2449e 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -220,6 +220,7 @@ *** xref:manage:disaster-recovery/shadowing/index.adoc[Shadowing] **** xref:manage:disaster-recovery/shadowing/overview.adoc[Overview] **** xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing] +**** xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent] **** xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing] **** xref:manage:disaster-recovery/shadowing/failover.adoc[Failover] **** xref:manage:disaster-recovery/shadowing/failover-runbook.adoc[Failover Runbook] diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc new file mode 100644 index 0000000000..7c3e49307d --- /dev/null +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -0,0 +1,272 @@ += Migrate Schemas from Confluent Schema Registry +:description: Replicate subjects, versions, and compatibility settings from a Confluent Schema Registry into a Redpanda shadow cluster. +:env-linux: true +:page-topic-type: how-to +:page-categories: Management, High Availability, Disaster Recovery +:learning-objective-1: Configure a shadow link that continuously replicates schemas from a Confluent Schema Registry +:learning-objective-2: Filter replication by context or subject and map source contexts to destination contexts +:learning-objective-3: Monitor schema replication status and resolve validation errors +// tag::single-source[] + +// DRAFT-VERIFY (DOC-2254): This page documents an unreleased v26.2 feature (ENG-1171). +// Engineering PRs redpanda#30999 (HTTP source reader) and redpanda#30984 (failover) were +// still open when this draft was written (2026-07-02). Re-verify every DRAFT-VERIFY item +// against merged code and a running 26.2 build before publishing. SME: @pgellert. + +ifndef::env-cloud[] +[NOTE] +==== +include::shared:partial$enterprise-license.adoc[] +==== +endif::[] + +Replicate glossterm:schema[,schemas] from a Confluent Schema Registry into a Redpanda glossterm:shadow cluster[] automatically and continuously. Schema replication through a glossterm:shadow link[] keeps subjects, versions, and compatibility settings synchronized with the source registry, so your applications keep working after a cutover without a separate schema migration step. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== How schema replication works + +When you configure a shadow link with the `shadow_schema_registry_api` option, the shadow cluster polls the source Schema Registry over HTTP and imports changes into its own glossterm:Schema Registry[]. Two sync cycles keep the registries in step: + +* *Tail syncs* run frequently (default: every 10 seconds) to pick up incremental changes. +* *Full syncs* scan all selected subjects (default: every 5 minutes) to catch anything a tail sync missed. + +Replicated schemas keep their original glossterm:subject[] names and version IDs, so producers and consumers that reference schemas by ID continue to work after failover. Schemas that reference other schemas import in dependency order. + +Before importing a schema, Redpanda validates it against the Redpanda Schema Registry implementation. If a schema uses features that Redpanda does not support, the sync either reports an error and skips the schema, or removes the unsupported fields and imports the rest, depending on the <> you choose. + +While the link is active, the destination contexts that the link replicates into are read-only: the shadow cluster rejects client writes to those contexts so that replicated schemas remain identical to the source. Contexts outside the link's filter remain writable. + +[NOTE] +==== +This API-based mode is an alternative to the byte-for-byte `_schemas` topic replication described in xref:manage:disaster-recovery/shadowing/setup.adoc#schema-registry-synchronization[Configure Shadowing]. A shadow link uses one Schema Registry sync mode or the other, not both. Use the API-based mode when the source is a Confluent Schema Registry, or when you need to replicate only selected contexts or subjects. + +Schema replication does not add any cluster configuration properties. All settings live in the shadow link configuration. +==== + +== Use cases + +* *Migrate from Confluent to Redpanda*: Replicate schemas continuously while xref:manage:disaster-recovery/shadowing/setup.adoc[Shadowing] replicates your topic data, then cut applications over to Redpanda once both are in sync. No separate schema migration tooling is required. +* *Phased migration*: Use context and subject filters to migrate one team, application, or environment at a time. +* *Registry reorganization*: Map source contexts to different destination contexts to restructure your Schema Registry as part of the migration. + +== Prerequisites + +* A shadow cluster running Redpanda version 26.2 or later. The schema replication feature activates after all brokers complete the upgrade. +* Network connectivity from the shadow cluster to the source Schema Registry HTTP endpoint. +* Credentials for the source registry with permission to read subjects, versions, and configuration. For Confluent Cloud, use a Schema Registry API key and secret. +* A shadow link to the source cluster, or a plan to create one. See xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing]. + +// DRAFT-VERIFY (DOC-2254): Confirm with @pgellert whether the destination Schema Registry +// (_schemas topic) must be empty before enabling API-mode sync, or whether the destination +// bootstrap in redpanda#30999 relaxes this. Topic mode requires it; API mode is unconfirmed. + +== Limitations + +* HTTP basic authentication is the only supported authentication method for the source registry. +* A shadow link replicates Schema Registry data in one mode only: either `shadow_schema_registry_topic` or `shadow_schema_registry_api`. +* Replication is one way, from the source registry to the shadow cluster. Destination contexts owned by the link are read-only until failover. +* Schemas that use Confluent features not supported by the Redpanda Schema Registry are not replicated as-is. Choose a <> to control whether these schemas are skipped or imported without the unsupported fields. + +// DRAFT-VERIFY (DOC-2254): Get the exact list of unsupported Confluent schema features +// (rule sets? metadata tags?) from @pgellert and document them here. +// DRAFT-VERIFY (DOC-2254): ENG-1171 mentions wildcard support in filters, but the rpk +// source shows plain string lists for contexts/subjects. Confirm whether wildcards or +// patterns are accepted before documenting either behavior. + +== Configure schema replication + +Add the `shadow_schema_registry_api` option to the `schema_registry_sync_options` section of your shadow link configuration file. + +=== Generate a configuration template + +Generate a configuration file template that includes all available fields with comments: + +[,bash] +---- +rpk shadow config generate --print-template -o shadow-config-template.yaml +---- + +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`]. + +=== Connect to the source registry + +Configure the connection to the source Schema Registry: + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + source_url: https://psrc-xxxxx.us-east-1.aws.confluent.cloud # Source Schema Registry endpoint + auth_options: + basic: + username: # Confluent Schema Registry API key + password: # Confluent Schema Registry API secret + tls_settings: + enabled: true # Use TLS for the connection + tls_file_settings: + ca_path: /path/to/ca.crt # Optional: CA certificate for custom trust + tail_interval: 10s # How often to poll for incremental changes + full_sync_interval: 5m # How often to run a full scan + max_source_requests_per_second: 30 # Rate limit for requests to the source registry +---- + +The intervals and rate limit are optional. If you omit them, Redpanda uses the defaults shown above. + +// DRAFT-VERIFY (DOC-2254): Defaults (10s / 5m / 30 rps) are from +// src/v/cluster_link/model/types.h on dev. Re-check at code-complete. + +=== Select contexts and subjects + +By default, the link replicates the entire source registry. To replicate a subset, add a `source_filter` with the contexts or subjects to include: + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings... + source_filter: + contexts: + - "." # The default context + - ".prod" # A named context + subjects: + - orders-value # A subject in the default context +---- + +Schema Registry contexts provide independent namespaces for subjects within one registry. The default context is named `.`. For more information, see xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts]. + +=== Map source contexts to destination contexts + +Choose how replicated contexts are named on the shadow cluster: + +* `identity`: Keep the source context names (default behavior for migrations). +* `exact`: Map each source context to a different destination context. + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings and filters... + destination: + identity: {} # Keep source context names +---- + +To rename contexts during replication: + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings and filters... + destination: + exact: + mappings: + - source: "." # Source context + destination: ".shadow" # Destination context on the shadow cluster +---- + +[[choose-a-validation-policy]] +=== Choose a validation policy + +The `unsupported_schema_feature_policy` setting controls what happens when a source schema uses features that the Redpanda Schema Registry does not support: + +[cols="1,3"] +|=== +| Policy | Behavior + +| `FAIL` (default) +| The schema is not replicated. The sync records an error, reports it in the link status, and continues with the remaining schemas. + +| `REMOVE` +| The unsupported fields are removed and the rest of the schema is imported. The sync counts each modification in the link status. +|=== + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings, filters, and destination... + unsupported_schema_feature_policy: FAIL +---- + +=== Create the shadow link + +Create the shadow link with your completed configuration file: + +[,bash] +---- +rpk shadow create --config-file shadow-config.yaml +---- + +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. + +To change the schema replication settings on an existing link, see xref:reference:rpk/rpk-shadow/rpk-shadow-update.adoc[`rpk shadow update`]. + +// DRAFT-VERIFY (DOC-2254): Confirm the exact `rpk shadow create` argument order +// (link name vs --config-file only) against the 26.2 rpk build. + +== Verify the configuration + +Confirm that the link is configured for API-based schema replication: + +[,bash] +---- +rpk shadow describe +---- + +The output includes the shadowing mode, source URL, sync intervals, validation policy, and your context and subject filters. For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`]. + +== Monitor replication status + +Check schema replication progress and errors for a link: + +[,bash] +---- +rpk shadow status +---- + +The Schema Registry section of the output reports: + +[cols="1,3"] +|=== +| Field | Description + +| Inventory +| The number of selected subjects and subject versions on the source, compared with the number of subjects and versions on the destination. The registries are synchronized when the destination counts match the selected source counts. A destination that is behind the source indicates that replication is still in progress. + +| Current sync +| The type of the sync in progress (`FULL` or `TAIL`) and the number of subject versions, compatibility configurations, and modes it has changed, including how many unsupported features were removed and how many errors occurred. + +| Last full sync +| Start time, finish time, and change counts for the most recent completed full sync. + +| Totals since task start +| Cumulative change and error counts since the schema replication task started. + +| Last error +| The most recent replication error. With the `FAIL` validation policy, schemas that fail validation appear here. +|=== + +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`]. For general link monitoring, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing]. + +== Fail over + +When you fail over a shadow link, schema replication from the source registry stops and the write-blocked destination contexts become writable, so your applications can register new schemas on the promoted cluster. + +// DRAFT-VERIFY (DOC-2254): Failover behavior (single `paused` field pauses the sync task +// and lifts per-context write blocks) is from open PR redpanda#30984. Confirm the final +// mechanism and whether any manual steps apply to schema replication during failover. + +For the complete failover procedure, see xref:manage:disaster-recovery/shadowing/failover.adoc[Failover]. + +== Next steps + +* xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing] to replicate topic data, consumer offsets, and ACLs alongside your schemas. +* xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing] +* xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts] + +// end::single-source[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index 88dd9be782..0908026350 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -158,6 +158,7 @@ endif::[] * **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`). * **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Shadow link tasks]. * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). +* **Schema Registry sync status**: For links that replicate schemas through the Schema Registry API, inventory counts for source and destination subjects, sync progress, and the most recent error. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc#monitor-replication-status[Monitor replication status]. include::manage:partial$shadowing/shadow-link-metrics.adoc[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 66f6178920..2d0b5fcf9d 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -28,7 +28,7 @@ Shadowing replicates: * **Topic configurations**: Partition counts, retention policies, and other topic properties * **Consumer group offsets**: Enables seamless consumer resumption after failover * **Access control lists (ACLs)**: User permissions and security policies -* **Schema Registry data**: Schema definitions and compatibility settings +* **Schema Registry data**: Schema definitions, versions, and compatibility settings, replicated from another Redpanda cluster or from a Confluent Schema Registry == How Shadowing fits into disaster recovery @@ -109,6 +109,20 @@ The task is controlled by the `security_sync_options` section in the configurati By default, all ACLs replicate to ensure your shadow cluster maintains the same security posture as your source cluster. -- + +Schema Registry Sync:: ++ +-- +[#schema-registry-sync-task] +The **Schema Registry Sync task** replicates Schema Registry content so that applications that depend on schemas keep working after failover. + +The task is controlled by the `schema_registry_sync_options` section in the configuration file. It supports two modes: + +* **Topic mode** (`shadow_schema_registry_topic`): Shadows the `_schemas` system topic for byte-for-byte replication from another Redpanda cluster. +* **API mode** (`shadow_schema_registry_api`): Polls the source Schema Registry over HTTP and imports selected contexts and subjects, with validation. Use this mode to replicate schemas from a Confluent Schema Registry. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent Schema Registry]. + +A shadow link uses one mode or the other, not both. +-- ==== === Task status and monitoring @@ -129,7 +143,7 @@ For monitoring task health and troubleshooting task issues, see xref:manage:disa Shadowing replicates your topic data with complete fidelity, preserving all message records with their original offsets, timestamps, headers, and metadata. The partition structure remains identical between source and shadow clusters, ensuring applications can resume processing from the exact same position after failover. -Consumer group data flows according to your group filters, replicating offsets and membership information for matched groups. ACLs replicate based on your security filters. Schema Registry data synchronizes schema definitions, versions, and compatibility settings. +Consumer group data flows according to your group filters, replicating offsets and membership information for matched groups. ACLs replicate based on your security filters. Schema Registry data synchronizes schema definitions, versions, and compatibility settings, either by shadowing the `_schemas` topic or through the xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Schema Registry API]. Partition count is always replicated to ensure the shadow topic matches the source topic's partition structure. diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index f7d5d0ebc4..dd476821f6 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -487,9 +487,14 @@ consumer_offset_sync_options: ==== Schema Registry synchronization -Shadowing can replicate Schema Registry data by shadowing the `_schemas` system topic. When enabled, this provides byte-for-byte replication of schema definitions, versions, and compatibility settings. +Shadowing can replicate Schema Registry data in one of two modes: -To enable Schema Registry synchronization, add the following to your shadow link configuration: +* **Topic mode** (`shadow_schema_registry_topic`): Shadows the `_schemas` system topic for byte-for-byte replication of schema definitions, versions, and compatibility settings from another Redpanda cluster. +* **API mode** (`shadow_schema_registry_api`): Polls the source Schema Registry over HTTP and imports selected contexts and subjects, with validation. Use this mode to replicate schemas from a Confluent Schema Registry, or to replicate only part of the source registry. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent Schema Registry]. + +A shadow link uses one mode or the other, not both. + +To enable topic mode, add the following to your shadow link configuration: [,yaml] ---- @@ -497,7 +502,7 @@ schema_registry_sync_options: shadow_schema_registry_topic: {} ---- -Requirements: +Topic mode requirements: - The `_schemas` topic must exist on the source cluster - The `_schemas` topic must not exist on the shadow cluster, or must be empty From 07de649c2911c23611284d09b51198bfa6ac0a56 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 8 Jul 2026 16:28:37 -0500 Subject: [PATCH 02/17] Apply suggestion from @Feediver1 --- .../disaster-recovery/shadowing/migrate-schemas-confluent.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 7c3e49307d..3b1951bc5f 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -20,7 +20,7 @@ include::shared:partial$enterprise-license.adoc[] ==== endif::[] -Replicate glossterm:schema[,schemas] from a Confluent Schema Registry into a Redpanda glossterm:shadow cluster[] automatically and continuously. Schema replication through a glossterm:shadow link[] keeps subjects, versions, and compatibility settings synchronized with the source registry, so your applications keep working after a cutover without a separate schema migration step. +Redpanda allows you to replicate glossterm:schema[,schemas] from a Confluent Schema Registry into a Redpanda glossterm:shadow cluster[] automatically and continuously. Schema replication through a glossterm:shadow link[] keeps subjects, versions, and compatibility settings synchronized with the source registry, so your applications keep working after a cutover without a separate schema migration step. After reading this page, you will be able to: From 41a6da39a158d3f1075cf09de8046fe585927d79 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Wed, 8 Jul 2026 17:44:37 -0400 Subject: [PATCH 03/17] DOC-2254: Rework intro to contextualize the feature Intro now follows what-it-does / how-it-works / benefit / when-to-use instead of opening with an imperative. Duplicate glossterms downgraded now that first mentions moved into the intro. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../shadowing/migrate-schemas-confluent.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 3b1951bc5f..810b60d4a3 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -20,7 +20,7 @@ include::shared:partial$enterprise-license.adoc[] ==== endif::[] -Redpanda allows you to replicate glossterm:schema[,schemas] from a Confluent Schema Registry into a Redpanda glossterm:shadow cluster[] automatically and continuously. Schema replication through a glossterm:shadow link[] keeps subjects, versions, and compatibility settings synchronized with the source registry, so your applications keep working after a cutover without a separate schema migration step. +When you migrate to Redpanda from a deployment that uses a Confluent Schema Registry, your producers and consumers depend on the glossterm:schema[,schemas] stored in that registry. Shadowing removes this migration obstacle: a glossterm:shadow link[] continuously replicates schemas from the source Confluent Schema Registry into the glossterm:Schema Registry[] built into the Redpanda glossterm:shadow cluster[], preserving glossterm:subject[] names, versions, and compatibility settings. Because both registries stay synchronized until cutover, your applications keep working on Redpanda without a separate schema migration step. Use this approach when you migrate from Confluent to Redpanda, or when you maintain a Redpanda disaster recovery cluster for a system that keeps its schemas in a Confluent Schema Registry. After reading this page, you will be able to: @@ -30,12 +30,12 @@ After reading this page, you will be able to: == How schema replication works -When you configure a shadow link with the `shadow_schema_registry_api` option, the shadow cluster polls the source Schema Registry over HTTP and imports changes into its own glossterm:Schema Registry[]. Two sync cycles keep the registries in step: +When you configure a shadow link with the `shadow_schema_registry_api` option, the shadow cluster polls the source Schema Registry over HTTP and imports changes into its own Schema Registry. Two sync cycles keep the registries in step: * *Tail syncs* run frequently (default: every 10 seconds) to pick up incremental changes. * *Full syncs* scan all selected subjects (default: every 5 minutes) to catch anything a tail sync missed. -Replicated schemas keep their original glossterm:subject[] names and version IDs, so producers and consumers that reference schemas by ID continue to work after failover. Schemas that reference other schemas import in dependency order. +Replicated schemas keep their original subject names and version IDs, so producers and consumers that reference schemas by ID continue to work after failover. Schemas that reference other schemas import in dependency order. Before importing a schema, Redpanda validates it against the Redpanda Schema Registry implementation. If a schema uses features that Redpanda does not support, the sync either reports an error and skips the schema, or removes the unsupported fields and imports the rest, depending on the <> you choose. From 7e707eab4d19a37c60f09d37684a01e1631055eb Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Wed, 8 Jul 2026 17:56:11 -0400 Subject: [PATCH 04/17] DOC-2254: Add complete sample shadow link config with API-mode SR replication Full-file example anchors the per-setting fragments that follow: name + client_options + topic sync (from the canonical setup.adoc sample) plus the complete shadow_schema_registry_api section (field names verified against rpk types_test.go). Links to Configure Shadowing for the full connection/auth reference. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../shadowing/migrate-schemas-confluent.adoc | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 810b60d4a3..0d8bf809dd 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -82,6 +82,52 @@ Schema replication does not add any cluster configuration properties. All settin Add the `shadow_schema_registry_api` option to the `schema_registry_sync_options` section of your shadow link configuration file. +The following sample configuration file creates a shadow link that shadows all source topics and replicates schemas from a Confluent Schema Registry. The sections that follow explain each schema replication setting. + +[,yaml] +---- +# Sample shadow link configuration with API-mode Schema Registry replication + +name: confluent-migration # Unique name for this shadow link + +client_options: + bootstrap_servers: # Source Kafka cluster brokers + - : # Example: "pkc-xxxxx.us-east-1.aws.confluent.cloud:9092" + - : + # For the TLS and authentication settings that the shadow cluster uses to + # connect to the source Kafka cluster, see the complete configuration file + # reference in Configure Shadowing. + +topic_metadata_sync_options: + interval: 30s # How often to sync topic metadata + auto_create_shadow_topic_filters: + - pattern_type: LITERAL + filter_type: INCLUDE + name: '*' # Shadow all source topics + +schema_registry_sync_options: + shadow_schema_registry_api: # API mode: replicate from a Confluent Schema Registry + source_url: https://psrc-xxxxx.us-east-1.aws.confluent.cloud # Source Schema Registry endpoint + auth_options: + basic: + username: # Confluent Schema Registry API key + password: # Confluent Schema Registry API secret + tls_settings: + enabled: true # Use TLS for the connection + tail_interval: 10s # Optional: poll for incremental changes (default: 10s) + full_sync_interval: 5m # Optional: full source scan interval (default: 5m) + max_source_requests_per_second: 30 # Optional: rate limit for source requests (default: 30) + source_filter: + contexts: + - "." # The default context + subjects: [] # Empty: all subjects in the selected contexts + destination: + identity: {} # Keep source context names + unsupported_schema_feature_policy: FAIL # FAIL (default) or REMOVE +---- + +For the complete configuration file, including consumer offset and security synchronization options, see xref:manage:disaster-recovery/shadowing/setup.adoc#create-a-shadow-link[Configure Shadowing]. + === Generate a configuration template Generate a configuration file template that includes all available fields with comments: From d79407a597226a807bda9f649f8982e9aa863548 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Wed, 8 Jul 2026 17:58:03 -0400 Subject: [PATCH 05/17] DOC-2254: Highlight the schema replication settings in the sample config Adds lines=20-38 highlighting to the sample shadow link configuration so the shadow_schema_registry_api block stands out from the framing sections, and points to it from the lead-in. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../shadowing/migrate-schemas-confluent.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 0d8bf809dd..9a59ace9fb 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -82,9 +82,11 @@ Schema replication does not add any cluster configuration properties. All settin Add the `shadow_schema_registry_api` option to the `schema_registry_sync_options` section of your shadow link configuration file. -The following sample configuration file creates a shadow link that shadows all source topics and replicates schemas from a Confluent Schema Registry. The sections that follow explain each schema replication setting. +The following sample configuration file creates a shadow link that shadows all source topics and replicates schemas from a Confluent Schema Registry. The highlighted lines show the schema replication settings, which the sections that follow explain. -[,yaml] +// NOTE: keep the lines= range pointing at the schema_registry_sync_options block +// if you edit this sample. +[,yaml,lines=20-38] ---- # Sample shadow link configuration with API-mode Schema Registry replication From 4db8652730f896ed5510dd1b7b39aff1c1d30273 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Wed, 8 Jul 2026 19:47:29 -0400 Subject: [PATCH 06/17] DOC-2292/DOC-2015: Document shadow link role synchronization (26.2) Documents the Roles Migrator task (ENG-1233 rpk + ENG-898 core): - setup.adoc: role_sync_options in the sample config file + new Role filtering section (empty-default gotcha, full-mirror semantics, credentials deliberately excluded, ACL sync required for end-to-end authorization, permissions/network notes) - overview.adoc: Roles Migrator task tab + RBAC roles in the replication list - rbac.adoc: cross-link TIP to role filtering All content gated ifndef::env-cloud (rpk rejects role_sync_options for Cloud in 26.2). Field names verified against rpk types.go and PR #30909; behavior from roles_migrator.cc and ducktape e2e tests. DRAFT-VERIFY comments mark SME questions for Andrew Nguyen and Rogger Vasquez. Stacked on the DOC-2254 branch to avoid conflicts in shared files. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../disaster-recovery/shadowing/overview.adoc | 19 +++++++ .../disaster-recovery/shadowing/setup.adoc | 56 +++++++++++++++++++ .../pages/security/authorization/rbac.adoc | 6 +- 3 files changed, 80 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 2d0b5fcf9d..bee32b3919 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -28,6 +28,9 @@ Shadowing replicates: * **Topic configurations**: Partition counts, retention policies, and other topic properties * **Consumer group offsets**: Enables seamless consumer resumption after failover * **Access control lists (ACLs)**: User permissions and security policies +ifndef::env-cloud[] +* **RBAC roles**: Role definitions and memberships, for the roles you select with filters +endif::[] * **Schema Registry data**: Schema definitions, versions, and compatibility settings, replicated from another Redpanda cluster or from a Confluent Schema Registry == How Shadowing fits into disaster recovery @@ -123,6 +126,22 @@ The task is controlled by the `schema_registry_sync_options` section in the conf A shadow link uses one mode or the other, not both. -- + +ifndef::env-cloud[] +Roles Migrator:: ++ +-- +[#roles-migrator-task] +The **Roles Migrator task** replicates RBAC role definitions and role memberships from the source cluster, so that role-based permissions authorize the same operations on the shadow cluster after failover. + +The task is controlled by the `role_sync_options` section in the configuration file. It includes: + +* **Role name filters**: Determines which roles replicate. No roles replicate until you add at least one include filter. +* **Sync interval**: How frequently to synchronize roles + +Within the configured filters, the task keeps the shadow cluster's roles as a full mirror of the source, creating, updating, and deleting roles to match. It does not replicate user credentials or the ACLs bound to roles; the Security Migrator task replicates ACLs. +-- +endif::[] ==== === Task status and monitoring diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index dd476821f6..c783afa358 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -257,6 +257,16 @@ security_sync_options: schema_registry_sync_options: # Schema Registry synchronization options shadow_schema_registry_topic: {} # Enable byte-for-byte _schemas topic replication + +ifndef::env-cloud[] +role_sync_options: # RBAC role synchronization options + interval: 30s # How often to sync roles + paused: false # Enable role synchronization + role_name_filters: # Default empty: no roles sync until you add an INCLUDE filter + - pattern_type: LITERAL # Pattern type: "LITERAL", "PREFIX" + filter_type: INCLUDE # Filter type: "INCLUDE", "EXCLUDE" + name: '*' # Include all roles ('*' must be the only character, LITERAL only) +endif::[] ---- ==== @@ -550,6 +560,52 @@ security_sync_options: host: '*' # Any host ---- +// DRAFT-VERIFY (DOC-2292/DOC-2015): Role sync documents ENG-1233/ENG-898 (v26.2; all +// engineering PRs merged to dev; feature flag shadow_link_role_sync). Confirm with +// Andrew Nguyen (core) and Rogger Vasquez (rpk): (1) no special failover step for roles, +// (2) behavior when the source is Apache Kafka (DescribeRedpandaRoles is Redpanda-specific), +// (3) whether role sync counters (created/updated/deleted/failures) surface in +// rpk shadow status or metrics, (4) exact source-cluster version requirement. +ifndef::env-cloud[] +==== Role filtering + +After a failover, your users and applications need the same permissions on the shadow cluster that they had on the source. Role synchronization prepares the shadow cluster for that moment: the xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Roles Migrator task] periodically reads xref:manage:security/authorization/rbac.adoc[RBAC] role definitions and role memberships from the source cluster and mirrors them to the shadow cluster. Use role synchronization together with <> whenever your authorization model uses roles, so that role-based permissions keep working after failover. + +[IMPORTANT] +==== +No roles are replicated by default. The `role_name_filters` list defaults to empty, which synchronizes nothing. Add at least one `INCLUDE` filter to start replicating roles. +==== + +To replicate all roles: + +[,yaml] +---- +role_sync_options: + interval: 30s # How often to sync roles + role_name_filters: + - pattern_type: LITERAL + filter_type: INCLUDE + name: '*' # '*' must be the only character and requires LITERAL +---- + +Role filters use the same pattern and filter types as topic filters: `pattern_type` is `LITERAL` or `PREFIX`, and `filter_type` is `INCLUDE` or `EXCLUDE`. + +Within the configured filters, the Roles Migrator task keeps the shadow cluster's roles as a full mirror of the source: + +* The task creates roles that exist on the source but not on the shadow. +* The task updates roles whose membership changed on the source. +* The task deletes roles that were deleted on the source. + +The task does not modify roles on the shadow cluster that fall outside your filters. + +Role synchronization replicates role definitions and memberships only: + +* **Shadowing does not replicate user credentials.** Replicating SCRAM credentials between clusters would create a security vulnerability, so Shadowing deliberately excludes them. Manage and distribute credentials outside of Shadowing, and provision users on the shadow cluster before failover. +* **Role synchronization does not replicate the ACLs bound to roles.** Configure <> as well, so that both the roles and the permissions granted to them exist on the shadow cluster. + +Role synchronization uses the same connection and service account as the rest of the shadow link. The cluster `describe` permission already required for ACL replication also covers role reads, and no additional network configuration is required. Both the source and shadow clusters must be running Redpanda 26.2 or later; the capability activates after the upgrade completes on all brokers. +endif::[] + ==== Consumer group filtering and behavior Consumer group filters determine which consumer groups have their offsets replicated to the shadow cluster by the xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Consumer Group Shadowing task]. diff --git a/modules/manage/pages/security/authorization/rbac.adoc b/modules/manage/pages/security/authorization/rbac.adoc index fc9d98ee3c..dfc4b83be4 100644 --- a/modules/manage/pages/security/authorization/rbac.adoc +++ b/modules/manage/pages/security/authorization/rbac.adoc @@ -12,4 +12,8 @@ Role-based access control (RBAC) provides a way to configure permissions for pro endif::[] -include::manage:partial$rbac-dp.adoc[] \ No newline at end of file +include::manage:partial$rbac-dp.adoc[] + +ifndef::env-cloud[] +TIP: If you use xref:manage:disaster-recovery/shadowing/index.adoc[Shadowing] for disaster recovery, you can replicate roles to the shadow cluster so that role-based permissions keep working after failover. See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering]. +endif::[] \ No newline at end of file From e5da0deab46efe3cc78fd5542ed1fb2edc87420e Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Fri, 10 Jul 2026 11:33:10 -0400 Subject: [PATCH 07/17] DOC-2254: State when to use topic mode vs API mode in the sync-mode note Addresses review feedback asking for explicit guidance on choosing between the two Schema Registry sync modes. Co-Authored-By: Claude Fable 5 --- .../shadowing/migrate-schemas-confluent.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 9a59ace9fb..a1b70f2fa3 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -43,7 +43,10 @@ While the link is active, the destination contexts that the link replicates into [NOTE] ==== -This API-based mode is an alternative to the byte-for-byte `_schemas` topic replication described in xref:manage:disaster-recovery/shadowing/setup.adoc#schema-registry-synchronization[Configure Shadowing]. A shadow link uses one Schema Registry sync mode or the other, not both. Use the API-based mode when the source is a Confluent Schema Registry, or when you need to replicate only selected contexts or subjects. +This API-based mode is an alternative to the byte-for-byte `_schemas` topic replication described in xref:manage:disaster-recovery/shadowing/setup.adoc#schema-registry-synchronization[Configure Shadowing]. A shadow link uses one Schema Registry sync mode or the other, not both: + +* Use *topic mode* (`shadow_schema_registry_topic`) when the source is another Redpanda cluster and you want an exact, complete replica of its Schema Registry. Topic mode shadows the `_schemas` topic byte for byte, so it does not filter, remap, or validate schemas. +* Use *API mode* (`shadow_schema_registry_api`) when the source is a Confluent Schema Registry, or when you need to replicate only selected contexts or subjects, map source contexts to different destination contexts, or control how schemas that use unsupported features are handled with a validation policy. Schema replication does not add any cluster configuration properties. All settings live in the shadow link configuration. ==== From 6f6e95a6e56f4b40c97594dba8ec983359474363 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Thu, 16 Jul 2026 11:48:31 -0400 Subject: [PATCH 08/17] Apply SME review feedback from Andrew Nguyen (PR #1780) - Drop the "security vulnerability" rationale for excluding SCRAM credentials; state only that Shadowing does not replicate them - Document that failover acts on topic data only: sync tasks keep running until paused per-task or the link is deleted - Document Apache Kafka source behavior: Roles Migrator enters LINK_UNAVAILABLE without affecting other tasks - Document role sync counts in the rpk shadow status Reason field (latest cycle only), in setup.adoc and the monitor.adoc status list - Remove the DRAFT-VERIFY comment block: all four questions answered in review Co-Authored-By: Claude Fable 5 --- .../pages/disaster-recovery/shadowing/monitor.adoc | 3 +++ .../pages/disaster-recovery/shadowing/setup.adoc | 14 ++++++-------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index 0908026350..37958d8957 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -159,6 +159,9 @@ endif::[] * **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Shadow link tasks]. * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). * **Schema Registry sync status**: For links that replicate schemas through the Schema Registry API, inventory counts for source and destination subjects, sync progress, and the most recent error. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc#monitor-replication-status[Monitor replication status]. +ifndef::env-cloud[] +* **Role sync counts**: For links that replicate RBAC roles, the Roles Migrator task's `Reason` field reports the counts from the most recent sync cycle (roles created, updated, deleted, and failures). See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering]. +endif::[] include::manage:partial$shadowing/shadow-link-metrics.adoc[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index c783afa358..f252300bb2 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -560,12 +560,6 @@ security_sync_options: host: '*' # Any host ---- -// DRAFT-VERIFY (DOC-2292/DOC-2015): Role sync documents ENG-1233/ENG-898 (v26.2; all -// engineering PRs merged to dev; feature flag shadow_link_role_sync). Confirm with -// Andrew Nguyen (core) and Rogger Vasquez (rpk): (1) no special failover step for roles, -// (2) behavior when the source is Apache Kafka (DescribeRedpandaRoles is Redpanda-specific), -// (3) whether role sync counters (created/updated/deleted/failures) surface in -// rpk shadow status or metrics, (4) exact source-cluster version requirement. ifndef::env-cloud[] ==== Role filtering @@ -600,10 +594,14 @@ The task does not modify roles on the shadow cluster that fall outside your filt Role synchronization replicates role definitions and memberships only: -* **Shadowing does not replicate user credentials.** Replicating SCRAM credentials between clusters would create a security vulnerability, so Shadowing deliberately excludes them. Manage and distribute credentials outside of Shadowing, and provision users on the shadow cluster before failover. +* **Shadowing does not replicate user credentials.** Manage and distribute credentials outside of Shadowing, and provision users on the shadow cluster before failover. * **Role synchronization does not replicate the ACLs bound to roles.** Configure <> as well, so that both the roles and the permissions granted to them exist on the shadow cluster. -Role synchronization uses the same connection and service account as the rest of the shadow link. The cluster `describe` permission already required for ACL replication also covers role reads, and no additional network configuration is required. Both the source and shadow clusters must be running Redpanda 26.2 or later; the capability activates after the upgrade completes on all brokers. +Role synchronization uses the same connection and service account as the rest of the shadow link. The cluster `describe` permission already required for ACL replication also covers role reads, and no additional network configuration is required. Both the source and shadow clusters must be running Redpanda 26.2 or later; the capability activates after the upgrade completes on all brokers. Role synchronization requires a Redpanda source cluster: if the source is an Apache Kafka cluster, the Roles Migrator task enters the `LINK_UNAVAILABLE` state, without affecting the other tasks on the link. + +Role synchronization continues to run after a xref:manage:disaster-recovery/shadowing/failover.adoc[failover]. Failover acts on topic data only: it stops topic replication and makes shadow topics writable, but the sync tasks, including the Roles Migrator, keep running on their intervals. To stop role synchronization, set `paused: true` in `role_sync_options`, or delete the shadow link. + +To monitor role synchronization, run xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`]. The Roles Migrator task's `Reason` field reports the counts from the most recent sync cycle, for example: `Synced roles: 2 created, 0 updated, 0 deleted, 0 failures`. endif::[] ==== Consumer group filtering and behavior From 78a30393c286a99b19a712d3c83d2d2858cd1fda Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Thu, 16 Jul 2026 13:10:03 -0400 Subject: [PATCH 09/17] Link first Roles Migrator mentions to task anchor and Role filtering Co-Authored-By: Claude Fable 5 --- modules/manage/pages/disaster-recovery/shadowing/monitor.adoc | 2 +- modules/manage/pages/disaster-recovery/shadowing/overview.adoc | 2 +- modules/manage/pages/disaster-recovery/shadowing/setup.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index 37958d8957..290e2fb9eb 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -160,7 +160,7 @@ endif::[] * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). * **Schema Registry sync status**: For links that replicate schemas through the Schema Registry API, inventory counts for source and destination subjects, sync progress, and the most recent error. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc#monitor-replication-status[Monitor replication status]. ifndef::env-cloud[] -* **Role sync counts**: For links that replicate RBAC roles, the Roles Migrator task's `Reason` field reports the counts from the most recent sync cycle (roles created, updated, deleted, and failures). See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering]. +* **Role sync counts**: For links that replicate RBAC roles, the `Reason` field of the xref:manage:disaster-recovery/shadowing/overview.adoc#roles-migrator-task[Roles Migrator task] reports the counts from the most recent sync cycle (roles created, updated, deleted, and failures). See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering]. endif::[] include::manage:partial$shadowing/shadow-link-metrics.adoc[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index bee32b3919..a9b0164182 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -139,7 +139,7 @@ The task is controlled by the `role_sync_options` section in the configuration f * **Role name filters**: Determines which roles replicate. No roles replicate until you add at least one include filter. * **Sync interval**: How frequently to synchronize roles -Within the configured filters, the task keeps the shadow cluster's roles as a full mirror of the source, creating, updating, and deleting roles to match. It does not replicate user credentials or the ACLs bound to roles; the Security Migrator task replicates ACLs. +Within the configured filters, the task keeps the shadow cluster's roles as a full mirror of the source, creating, updating, and deleting roles to match. It does not replicate user credentials or the ACLs bound to roles; the Security Migrator task replicates ACLs. See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering]. -- endif::[] ==== diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index f252300bb2..b1ebf2f63a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -563,7 +563,7 @@ security_sync_options: ifndef::env-cloud[] ==== Role filtering -After a failover, your users and applications need the same permissions on the shadow cluster that they had on the source. Role synchronization prepares the shadow cluster for that moment: the xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Roles Migrator task] periodically reads xref:manage:security/authorization/rbac.adoc[RBAC] role definitions and role memberships from the source cluster and mirrors them to the shadow cluster. Use role synchronization together with <> whenever your authorization model uses roles, so that role-based permissions keep working after failover. +After a failover, your users and applications need the same permissions on the shadow cluster that they had on the source. Role synchronization prepares the shadow cluster for that moment: the xref:manage:disaster-recovery/shadowing/overview.adoc#roles-migrator-task[Roles Migrator task] periodically reads xref:manage:security/authorization/rbac.adoc[RBAC] role definitions and role memberships from the source cluster and mirrors them to the shadow cluster. Use role synchronization together with <> whenever your authorization model uses roles, so that role-based permissions keep working after failover. [IMPORTANT] ==== From 568d68e9d0e0c2f9d8b32867101929bb9014656f Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 16 Jul 2026 12:17:20 -0500 Subject: [PATCH 10/17] Update modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gellért Peresztegi-Nagy --- .../shadowing/migrate-schemas-confluent.adoc | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index a1b70f2fa3..e7d5b0e0a2 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -250,16 +250,13 @@ Create the shadow link with your completed configuration file: [,bash] ---- -rpk shadow create --config-file shadow-config.yaml +rpk shadow create --config-file shadow-config.yaml ---- For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. To change the schema replication settings on an existing link, see xref:reference:rpk/rpk-shadow/rpk-shadow-update.adoc[`rpk shadow update`]. -// DRAFT-VERIFY (DOC-2254): Confirm the exact `rpk shadow create` argument order -// (link name vs --config-file only) against the 26.2 rpk build. - == Verify the configuration Confirm that the link is configured for API-based schema replication: From be45498695ad58afba77547b5f3d5de28156f0c7 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Thu, 16 Jul 2026 13:28:37 -0400 Subject: [PATCH 11/17] Apply SME review feedback from Gellert (PR #1776) Corrections and additions from pgellert's review: - Two cluster tunables do exist (schema_registry_sync_memory_bytes, schema_registry_sync_parallelism); replace the "no cluster configuration properties" claim - mTLS is supported alongside HTTP basic auth for the source registry - Prerequisites: destination contexts owned by the link must be empty (rest of the registry need not be); qualified subjects config required for non-default contexts - Limitations: topic data and schema replication are not coordinated (SerDes records can reference not-yet-replicated schema IDs) - Remove topic_metadata_sync_options from the sample config and fix the highlight range - Filters accept literal names only (no wildcards/prefixes) - exact context mappings must be exhaustive: unmapped source contexts fail the task; recommend scoping source_filter - List the unsupported Confluent features (rule sets, metadata tags, override/default metadata and rule sets, compatibility groups) - Monitoring: task runs on the _schemas partition leader; counters are ephemeral and reset on restart or leadership movement - Failover: pausing the SR sync task (paused: true) is a required step; failover alone does not stop schema replication - overview.adoc: only API mode runs as a separate task in link status Resolves all DRAFT-VERIFY items except the sync-defaults re-check. Co-Authored-By: Claude Fable 5 --- .../shadowing/migrate-schemas-confluent.adoc | 57 +++++++++---------- .../disaster-recovery/shadowing/overview.adoc | 2 +- 2 files changed, 28 insertions(+), 31 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index e7d5b0e0a2..e3e62e740b 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -9,9 +9,8 @@ // tag::single-source[] // DRAFT-VERIFY (DOC-2254): This page documents an unreleased v26.2 feature (ENG-1171). -// Engineering PRs redpanda#30999 (HTTP source reader) and redpanda#30984 (failover) were -// still open when this draft was written (2026-07-02). Re-verify every DRAFT-VERIFY item -// against merged code and a running 26.2 build before publishing. SME: @pgellert. +// SME review feedback from @pgellert applied 2026-07-16 (PR #1776). One DRAFT-VERIFY item +// remains (sync defaults); re-check it against a running 26.2 build before publishing. ifndef::env-cloud[] [NOTE] @@ -48,7 +47,7 @@ This API-based mode is an alternative to the byte-for-byte `_schemas` topic repl * Use *topic mode* (`shadow_schema_registry_topic`) when the source is another Redpanda cluster and you want an exact, complete replica of its Schema Registry. Topic mode shadows the `_schemas` topic byte for byte, so it does not filter, remap, or validate schemas. * Use *API mode* (`shadow_schema_registry_api`) when the source is a Confluent Schema Registry, or when you need to replicate only selected contexts or subjects, map source contexts to different destination contexts, or control how schemas that use unsupported features are handled with a validation policy. -Schema replication does not add any cluster configuration properties. All settings live in the shadow link configuration. +Schema replication settings live in the shadow link configuration. Two cluster properties, `schema_registry_sync_memory_bytes` and `schema_registry_sync_parallelism`, tune how much memory and concurrency the shadow cluster uses while importing schemas. The defaults suit most deployments. ==== == Use cases @@ -63,33 +62,26 @@ Schema replication does not add any cluster configuration properties. All settin * Network connectivity from the shadow cluster to the source Schema Registry HTTP endpoint. * Credentials for the source registry with permission to read subjects, versions, and configuration. For Confluent Cloud, use a Schema Registry API key and secret. * A shadow link to the source cluster, or a plan to create one. See xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing]. - -// DRAFT-VERIFY (DOC-2254): Confirm with @pgellert whether the destination Schema Registry -// (_schemas topic) must be empty before enabling API-mode sync, or whether the destination -// bootstrap in redpanda#30999 relaxes this. Topic mode requires it; API mode is unconfirmed. +* The destination contexts that the link replicates into, as determined by your `source_filter` and `destination` mapping, must be empty on the shadow cluster. The rest of the shadow cluster's Schema Registry does not need to be empty: contexts outside the link's mappings are unaffected. +* To replicate contexts other than the default context, the xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster property must be enabled on the shadow cluster (the default). See xref:manage:schema-reg/schema-reg-contexts.adoc#prerequisites[Schema Registry Contexts]. == Limitations -* HTTP basic authentication is the only supported authentication method for the source registry. +* HTTP basic authentication and mTLS are the supported authentication methods for the source registry. * A shadow link replicates Schema Registry data in one mode only: either `shadow_schema_registry_topic` or `shadow_schema_registry_api`. * Replication is one way, from the source registry to the shadow cluster. Destination contexts owned by the link are read-only until failover. * Schemas that use Confluent features not supported by the Redpanda Schema Registry are not replicated as-is. Choose a <> to control whether these schemas are skipped or imported without the unsupported fields. - -// DRAFT-VERIFY (DOC-2254): Get the exact list of unsupported Confluent schema features -// (rule sets? metadata tags?) from @pgellert and document them here. -// DRAFT-VERIFY (DOC-2254): ENG-1171 mentions wildcard support in filters, but the rpk -// source shows plain string lists for contexts/subjects. Confirm whether wildcards or -// patterns are accepted before documenting either behavior. +* Topic data replication and schema replication are not coordinated with each other. Records serialized in the Confluent SerDes wire format can arrive on the shadow cluster before the schema IDs they contain have been replicated. == Configure schema replication Add the `shadow_schema_registry_api` option to the `schema_registry_sync_options` section of your shadow link configuration file. -The following sample configuration file creates a shadow link that shadows all source topics and replicates schemas from a Confluent Schema Registry. The highlighted lines show the schema replication settings, which the sections that follow explain. +The following sample configuration file creates a shadow link that replicates schemas from a Confluent Schema Registry. The highlighted lines show the schema replication settings, which the sections that follow explain. // NOTE: keep the lines= range pointing at the schema_registry_sync_options block // if you edit this sample. -[,yaml,lines=20-38] +[,yaml,lines=13-31] ---- # Sample shadow link configuration with API-mode Schema Registry replication @@ -103,13 +95,6 @@ client_options: # connect to the source Kafka cluster, see the complete configuration file # reference in Configure Shadowing. -topic_metadata_sync_options: - interval: 30s # How often to sync topic metadata - auto_create_shadow_topic_filters: - - pattern_type: LITERAL - filter_type: INCLUDE - name: '*' # Shadow all source topics - schema_registry_sync_options: shadow_schema_registry_api: # API mode: replicate from a Confluent Schema Registry source_url: https://psrc-xxxxx.us-east-1.aws.confluent.cloud # Source Schema Registry endpoint @@ -168,6 +153,8 @@ schema_registry_sync_options: The intervals and rate limit are optional. If you omit them, Redpanda uses the defaults shown above. +To authenticate to the source registry with mTLS instead of HTTP basic authentication, omit `auth_options` and provide a client certificate and key in `tls_settings`. + // DRAFT-VERIFY (DOC-2254): Defaults (10s / 5m / 30 rps) are from // src/v/cluster_link/model/types.h on dev. Re-check at code-complete. @@ -188,6 +175,8 @@ schema_registry_sync_options: - orders-value # A subject in the default context ---- +The `contexts` and `subjects` lists accept literal names only. Wildcard and prefix patterns are not supported. + Schema Registry contexts provide independent namespaces for subjects within one registry. The default context is named `.`. For more information, see xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts]. === Map source contexts to destination contexts @@ -220,10 +209,20 @@ schema_registry_sync_options: destination: ".shadow" # Destination context on the shadow cluster ---- +[IMPORTANT] +==== +With `exact` mapping, the mappings must cover every context that the link replicates. If the link encounters a source context that has no mapping, the schema replication task fails. If new contexts might be created on the source registry after you set up the link, scope the `source_filter` `contexts` list to the mapped contexts so that an unexpected context cannot stop replication. +==== + [[choose-a-validation-policy]] === Choose a validation policy -The `unsupported_schema_feature_policy` setting controls what happens when a source schema uses features that the Redpanda Schema Registry does not support: +The `unsupported_schema_feature_policy` setting controls what happens when a source schema uses features that the Redpanda Schema Registry does not support. The unsupported Confluent Schema Registry features are: + +* In schema definitions: rule sets and metadata tags. +* In subject configurations: override metadata, override rule sets, default metadata, default rule sets, and compatibility groups. Compatibility groups are not the same as compatibility levels, which do replicate. + +The policy determines how the sync handles a schema or configuration that uses these features: [cols="1,3"] |=== @@ -299,15 +298,13 @@ The Schema Registry section of the output reports: | The most recent replication error. With the `FAIL` validation policy, schemas that fail validation appear here. |=== +The schema replication task runs on the broker and shard that hosts the leader of the `_schemas` topic's partition. The counters in the status output are not persisted: expect them to reset to zero when that broker restarts or when leadership of the `_schemas` partition moves to another broker. + For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`]. For general link monitoring, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing]. == Fail over -When you fail over a shadow link, schema replication from the source registry stops and the write-blocked destination contexts become writable, so your applications can register new schemas on the promoted cluster. - -// DRAFT-VERIFY (DOC-2254): Failover behavior (single `paused` field pauses the sync task -// and lifts per-context write blocks) is from open PR redpanda#30984. Confirm the final -// mechanism and whether any manual steps apply to schema replication during failover. +Failing over shadow topics does not stop schema replication. As part of failover, pause the schema replication task by setting `paused: true` in the `schema_registry_sync_options` section of the link configuration. Pausing the task stops further syncing from the source registry and makes the write-blocked destination contexts writable, so your applications can register new schemas on the promoted cluster. For the complete failover procedure, see xref:manage:disaster-recovery/shadowing/failover.adoc[Failover]. diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 2d0b5fcf9d..29848ed008 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -121,7 +121,7 @@ The task is controlled by the `schema_registry_sync_options` section in the conf * **Topic mode** (`shadow_schema_registry_topic`): Shadows the `_schemas` system topic for byte-for-byte replication from another Redpanda cluster. * **API mode** (`shadow_schema_registry_api`): Polls the source Schema Registry over HTTP and imports selected contexts and subjects, with validation. Use this mode to replicate schemas from a Confluent Schema Registry. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent Schema Registry]. -A shadow link uses one mode or the other, not both. +A shadow link uses one mode or the other, not both. Only API mode runs as a separate task that appears in the shadow link status. Topic mode adds the `_schemas` topic to the set of shadowed topics, so it is monitored like any other shadow topic rather than as a separate task. -- ==== From bf6098e0033519854fda0d652a5a862342bf37dc Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Thu, 16 Jul 2026 13:40:41 -0400 Subject: [PATCH 12/17] Clear last DRAFT-VERIFY: sync defaults verified at v26.2.1-rc3 default_tail_interval=10s, default_full_sync_interval=5m, default_max_source_requests_per_second=30 confirmed in src/v/cluster_link/model/types.h at the v26.2.1-rc3 tag, matching the documented values. Co-Authored-By: Claude Fable 5 --- .../shadowing/migrate-schemas-confluent.adoc | 7 ------- 1 file changed, 7 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index e3e62e740b..8301795922 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -8,10 +8,6 @@ :learning-objective-3: Monitor schema replication status and resolve validation errors // tag::single-source[] -// DRAFT-VERIFY (DOC-2254): This page documents an unreleased v26.2 feature (ENG-1171). -// SME review feedback from @pgellert applied 2026-07-16 (PR #1776). One DRAFT-VERIFY item -// remains (sync defaults); re-check it against a running 26.2 build before publishing. - ifndef::env-cloud[] [NOTE] ==== @@ -155,9 +151,6 @@ The intervals and rate limit are optional. If you omit them, Redpanda uses the d To authenticate to the source registry with mTLS instead of HTTP basic authentication, omit `auth_options` and provide a client certificate and key in `tls_settings`. -// DRAFT-VERIFY (DOC-2254): Defaults (10s / 5m / 30 rps) are from -// src/v/cluster_link/model/types.h on dev. Re-check at code-complete. - === Select contexts and subjects By default, the link replicates the entire source registry. To replicate a subset, add a `source_filter` with the contexts or subjects to include: From b4152794eff47f0cc6021233a8e42beb200c485b Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Thu, 16 Jul 2026 17:59:17 -0500 Subject: [PATCH 13/17] Apply suggestions from code review by PM - Trevor Blackford Co-authored-by: Trevor Blackford --- .../shadowing/migrate-schemas-confluent.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 8301795922..63043f1e00 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -23,7 +23,7 @@ After reading this page, you will be able to: * [ ] {learning-objective-2} * [ ] {learning-objective-3} -== How schema replication works +== How HTTP API schema replication works When you configure a shadow link with the `shadow_schema_registry_api` option, the shadow cluster polls the source Schema Registry over HTTP and imports changes into its own Schema Registry. Two sync cycles keep the registries in step: @@ -54,10 +54,10 @@ Schema replication settings live in the shadow link configuration. Two cluster p == Prerequisites -* A shadow cluster running Redpanda version 26.2 or later. The schema replication feature activates after all brokers complete the upgrade. +* A cluster running Redpanda version 26.2 or later. The schema replication feature activates after all brokers complete the upgrade. * Network connectivity from the shadow cluster to the source Schema Registry HTTP endpoint. * Credentials for the source registry with permission to read subjects, versions, and configuration. For Confluent Cloud, use a Schema Registry API key and secret. -* A shadow link to the source cluster, or a plan to create one. See xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing]. +* Basic Shadow link settings. See xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing]. * The destination contexts that the link replicates into, as determined by your `source_filter` and `destination` mapping, must be empty on the shadow cluster. The rest of the shadow cluster's Schema Registry does not need to be empty: contexts outside the link's mappings are unaffected. * To replicate contexts other than the default context, the xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster property must be enabled on the shadow cluster (the default). See xref:manage:schema-reg/schema-reg-contexts.adoc#prerequisites[Schema Registry Contexts]. @@ -225,7 +225,7 @@ The policy determines how the sync handles a schema or configuration that uses t | The schema is not replicated. The sync records an error, reports it in the link status, and continues with the remaining schemas. | `REMOVE` -| The unsupported fields are removed and the rest of the schema is imported. The sync counts each modification in the link status. +| The unsupported fields are removed and the rest of the schema is imported. The sync records each modification in the link status. |=== [,yaml] @@ -297,7 +297,7 @@ For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-statu == Fail over -Failing over shadow topics does not stop schema replication. As part of failover, pause the schema replication task by setting `paused: true` in the `schema_registry_sync_options` section of the link configuration. Pausing the task stops further syncing from the source registry and makes the write-blocked destination contexts writable, so your applications can register new schemas on the promoted cluster. +For best results, shadow links should be failed over as a single unit, which prevents partial failover scenarios and unexpected results. Selective failover, such as topics only, does not stop schema replication. As part of failover, pause the schema replication task by setting `paused: true` in the `schema_registry_sync_options` section of the link configuration. Pausing the task stops further syncing from the source registry and makes the write-blocked destination contexts writable, so your applications can register new schemas on the promoted cluster. For the complete failover procedure, see xref:manage:disaster-recovery/shadowing/failover.adoc[Failover]. From d6512f326f996cf8c510226bf91c9c741366ccc0 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 20 Jul 2026 10:52:42 -0500 Subject: [PATCH 14/17] Update modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gellért Peresztegi-Nagy --- .../shadowing/migrate-schemas-confluent.adoc | 611 +++++++++--------- 1 file changed, 306 insertions(+), 305 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 63043f1e00..9a2fa9bb13 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -1,310 +1,311 @@ -= Migrate Schemas from Confluent Schema Registry -:description: Replicate subjects, versions, and compatibility settings from a Confluent Schema Registry into a Redpanda shadow cluster. -:env-linux: true -:page-topic-type: how-to -:page-categories: Management, High Availability, Disaster Recovery -:learning-objective-1: Configure a shadow link that continuously replicates schemas from a Confluent Schema Registry -:learning-objective-2: Filter replication by context or subject and map source contexts to destination contexts -:learning-objective-3: Monitor schema replication status and resolve validation errors -// tag::single-source[] - -ifndef::env-cloud[] -[NOTE] -==== -include::shared:partial$enterprise-license.adoc[] -==== -endif::[] - -When you migrate to Redpanda from a deployment that uses a Confluent Schema Registry, your producers and consumers depend on the glossterm:schema[,schemas] stored in that registry. Shadowing removes this migration obstacle: a glossterm:shadow link[] continuously replicates schemas from the source Confluent Schema Registry into the glossterm:Schema Registry[] built into the Redpanda glossterm:shadow cluster[], preserving glossterm:subject[] names, versions, and compatibility settings. Because both registries stay synchronized until cutover, your applications keep working on Redpanda without a separate schema migration step. Use this approach when you migrate from Confluent to Redpanda, or when you maintain a Redpanda disaster recovery cluster for a system that keeps its schemas in a Confluent Schema Registry. - -After reading this page, you will be able to: - -* [ ] {learning-objective-1} -* [ ] {learning-objective-2} -* [ ] {learning-objective-3} - += Migrate Schemas from Confluent Schema Registry +:description: Replicate subjects, versions, and compatibility settings from a Confluent Schema Registry into a Redpanda shadow cluster. +:env-linux: true +:page-topic-type: how-to +:page-categories: Management, High Availability, Disaster Recovery +:learning-objective-1: Configure a shadow link that continuously replicates schemas from a Confluent Schema Registry +:learning-objective-2: Filter replication by context or subject and map source contexts to destination contexts +:learning-objective-3: Monitor schema replication status and resolve validation errors +// tag::single-source[] + +ifndef::env-cloud[] +[NOTE] +==== +include::shared:partial$enterprise-license.adoc[] +==== +endif::[] + +When you migrate to Redpanda from a deployment that uses a Confluent Schema Registry, your producers and consumers depend on the glossterm:schema[,schemas] stored in that registry. Shadowing removes this migration obstacle: a glossterm:shadow link[] continuously replicates schemas from the source Confluent Schema Registry into the glossterm:Schema Registry[] built into the Redpanda glossterm:shadow cluster[], preserving glossterm:subject[] names, versions, and compatibility settings. Because both registries stay synchronized until cutover, your applications keep working on Redpanda without a separate schema migration step. Use this approach when you migrate from Confluent to Redpanda, or when you maintain a Redpanda disaster recovery cluster for a system that keeps its schemas in a Confluent Schema Registry. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + == How HTTP API schema replication works - -When you configure a shadow link with the `shadow_schema_registry_api` option, the shadow cluster polls the source Schema Registry over HTTP and imports changes into its own Schema Registry. Two sync cycles keep the registries in step: - -* *Tail syncs* run frequently (default: every 10 seconds) to pick up incremental changes. -* *Full syncs* scan all selected subjects (default: every 5 minutes) to catch anything a tail sync missed. - -Replicated schemas keep their original subject names and version IDs, so producers and consumers that reference schemas by ID continue to work after failover. Schemas that reference other schemas import in dependency order. - -Before importing a schema, Redpanda validates it against the Redpanda Schema Registry implementation. If a schema uses features that Redpanda does not support, the sync either reports an error and skips the schema, or removes the unsupported fields and imports the rest, depending on the <> you choose. - -While the link is active, the destination contexts that the link replicates into are read-only: the shadow cluster rejects client writes to those contexts so that replicated schemas remain identical to the source. Contexts outside the link's filter remain writable. - -[NOTE] -==== -This API-based mode is an alternative to the byte-for-byte `_schemas` topic replication described in xref:manage:disaster-recovery/shadowing/setup.adoc#schema-registry-synchronization[Configure Shadowing]. A shadow link uses one Schema Registry sync mode or the other, not both: - -* Use *topic mode* (`shadow_schema_registry_topic`) when the source is another Redpanda cluster and you want an exact, complete replica of its Schema Registry. Topic mode shadows the `_schemas` topic byte for byte, so it does not filter, remap, or validate schemas. -* Use *API mode* (`shadow_schema_registry_api`) when the source is a Confluent Schema Registry, or when you need to replicate only selected contexts or subjects, map source contexts to different destination contexts, or control how schemas that use unsupported features are handled with a validation policy. - -Schema replication settings live in the shadow link configuration. Two cluster properties, `schema_registry_sync_memory_bytes` and `schema_registry_sync_parallelism`, tune how much memory and concurrency the shadow cluster uses while importing schemas. The defaults suit most deployments. -==== - -== Use cases - -* *Migrate from Confluent to Redpanda*: Replicate schemas continuously while xref:manage:disaster-recovery/shadowing/setup.adoc[Shadowing] replicates your topic data, then cut applications over to Redpanda once both are in sync. No separate schema migration tooling is required. -* *Phased migration*: Use context and subject filters to migrate one team, application, or environment at a time. -* *Registry reorganization*: Map source contexts to different destination contexts to restructure your Schema Registry as part of the migration. - -== Prerequisites - + +When you configure a shadow link with the `shadow_schema_registry_api` option, the shadow cluster polls the source Schema Registry over HTTP and imports changes into its own Schema Registry. Two sync cycles keep the registries in step: + +* *Tail syncs* run frequently (default: every 10 seconds) to pick up incremental changes. +* *Full syncs* scan all selected subjects (default: every 5 minutes) to catch anything a tail sync missed. + +Replicated schemas keep their original subject names and version IDs, so producers and consumers that reference schemas by ID continue to work after failover. Schemas that reference other schemas import in dependency order. + +Before importing a schema, Redpanda validates it against the Redpanda Schema Registry implementation. If a schema uses features that Redpanda does not support, the sync either reports an error and skips the schema, or removes the unsupported fields and imports the rest, depending on the <> you choose. + +While the link is active, the destination contexts that the link replicates into are read-only: the shadow cluster rejects client writes to those contexts so that replicated schemas remain identical to the source. Contexts outside the link's filter remain writable. + +[NOTE] +==== +This API-based mode is an alternative to the byte-for-byte `_schemas` topic replication described in xref:manage:disaster-recovery/shadowing/setup.adoc#schema-registry-synchronization[Configure Shadowing]. A shadow link uses one Schema Registry sync mode or the other, not both: + +* Use *topic mode* (`shadow_schema_registry_topic`) when the source is another Redpanda cluster and you want an exact, complete replica of its Schema Registry. Topic mode shadows the `_schemas` topic byte for byte, so it does not filter, remap, or validate schemas. +* Use *API mode* (`shadow_schema_registry_api`) when the source is a Confluent Schema Registry, or when you need to replicate only selected contexts or subjects, map source contexts to different destination contexts, or control how schemas that use unsupported features are handled with a validation policy. + +Schema replication settings live in the shadow link configuration. Two cluster properties, `schema_registry_sync_memory_bytes` and `schema_registry_sync_parallelism`, tune how much memory and concurrency the shadow cluster uses while importing schemas. The defaults suit most deployments. +==== + +== Use cases + +* *Migrate from Confluent to Redpanda*: Replicate schemas continuously while xref:manage:disaster-recovery/shadowing/setup.adoc[Shadowing] replicates your topic data, then cut applications over to Redpanda once both are in sync. No separate schema migration tooling is required. +* *Phased migration*: Use context and subject filters to migrate one team, application, or environment at a time. +* *Registry reorganization*: Map source contexts to different destination contexts to restructure your Schema Registry as part of the migration. + +== Prerequisites + * A cluster running Redpanda version 26.2 or later. The schema replication feature activates after all brokers complete the upgrade. -* Network connectivity from the shadow cluster to the source Schema Registry HTTP endpoint. -* Credentials for the source registry with permission to read subjects, versions, and configuration. For Confluent Cloud, use a Schema Registry API key and secret. +* Network connectivity from the shadow cluster to the source Schema Registry HTTP endpoint. +* Credentials for the source registry with permission to read subjects, versions, and configuration. For Confluent Cloud, use a Schema Registry API key and secret. * Basic Shadow link settings. See xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing]. -* The destination contexts that the link replicates into, as determined by your `source_filter` and `destination` mapping, must be empty on the shadow cluster. The rest of the shadow cluster's Schema Registry does not need to be empty: contexts outside the link's mappings are unaffected. -* To replicate contexts other than the default context, the xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster property must be enabled on the shadow cluster (the default). See xref:manage:schema-reg/schema-reg-contexts.adoc#prerequisites[Schema Registry Contexts]. - -== Limitations - -* HTTP basic authentication and mTLS are the supported authentication methods for the source registry. -* A shadow link replicates Schema Registry data in one mode only: either `shadow_schema_registry_topic` or `shadow_schema_registry_api`. -* Replication is one way, from the source registry to the shadow cluster. Destination contexts owned by the link are read-only until failover. -* Schemas that use Confluent features not supported by the Redpanda Schema Registry are not replicated as-is. Choose a <> to control whether these schemas are skipped or imported without the unsupported fields. -* Topic data replication and schema replication are not coordinated with each other. Records serialized in the Confluent SerDes wire format can arrive on the shadow cluster before the schema IDs they contain have been replicated. - -== Configure schema replication - -Add the `shadow_schema_registry_api` option to the `schema_registry_sync_options` section of your shadow link configuration file. - -The following sample configuration file creates a shadow link that replicates schemas from a Confluent Schema Registry. The highlighted lines show the schema replication settings, which the sections that follow explain. - -// NOTE: keep the lines= range pointing at the schema_registry_sync_options block -// if you edit this sample. -[,yaml,lines=13-31] ----- -# Sample shadow link configuration with API-mode Schema Registry replication - -name: confluent-migration # Unique name for this shadow link - -client_options: - bootstrap_servers: # Source Kafka cluster brokers - - : # Example: "pkc-xxxxx.us-east-1.aws.confluent.cloud:9092" - - : - # For the TLS and authentication settings that the shadow cluster uses to - # connect to the source Kafka cluster, see the complete configuration file - # reference in Configure Shadowing. - -schema_registry_sync_options: - shadow_schema_registry_api: # API mode: replicate from a Confluent Schema Registry - source_url: https://psrc-xxxxx.us-east-1.aws.confluent.cloud # Source Schema Registry endpoint - auth_options: - basic: - username: # Confluent Schema Registry API key - password: # Confluent Schema Registry API secret - tls_settings: - enabled: true # Use TLS for the connection - tail_interval: 10s # Optional: poll for incremental changes (default: 10s) - full_sync_interval: 5m # Optional: full source scan interval (default: 5m) - max_source_requests_per_second: 30 # Optional: rate limit for source requests (default: 30) - source_filter: - contexts: - - "." # The default context - subjects: [] # Empty: all subjects in the selected contexts - destination: - identity: {} # Keep source context names - unsupported_schema_feature_policy: FAIL # FAIL (default) or REMOVE ----- - -For the complete configuration file, including consumer offset and security synchronization options, see xref:manage:disaster-recovery/shadowing/setup.adoc#create-a-shadow-link[Configure Shadowing]. - -=== Generate a configuration template - -Generate a configuration file template that includes all available fields with comments: - -[,bash] ----- -rpk shadow config generate --print-template -o shadow-config-template.yaml ----- - -For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`]. - -=== Connect to the source registry - -Configure the connection to the source Schema Registry: - -[,yaml] ----- -schema_registry_sync_options: - shadow_schema_registry_api: - source_url: https://psrc-xxxxx.us-east-1.aws.confluent.cloud # Source Schema Registry endpoint - auth_options: - basic: - username: # Confluent Schema Registry API key - password: # Confluent Schema Registry API secret - tls_settings: - enabled: true # Use TLS for the connection - tls_file_settings: - ca_path: /path/to/ca.crt # Optional: CA certificate for custom trust - tail_interval: 10s # How often to poll for incremental changes - full_sync_interval: 5m # How often to run a full scan - max_source_requests_per_second: 30 # Rate limit for requests to the source registry ----- - -The intervals and rate limit are optional. If you omit them, Redpanda uses the defaults shown above. - -To authenticate to the source registry with mTLS instead of HTTP basic authentication, omit `auth_options` and provide a client certificate and key in `tls_settings`. - -=== Select contexts and subjects - -By default, the link replicates the entire source registry. To replicate a subset, add a `source_filter` with the contexts or subjects to include: - -[,yaml] ----- -schema_registry_sync_options: - shadow_schema_registry_api: - # ...connection settings... - source_filter: - contexts: - - "." # The default context - - ".prod" # A named context - subjects: - - orders-value # A subject in the default context ----- - -The `contexts` and `subjects` lists accept literal names only. Wildcard and prefix patterns are not supported. - -Schema Registry contexts provide independent namespaces for subjects within one registry. The default context is named `.`. For more information, see xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts]. - -=== Map source contexts to destination contexts - -Choose how replicated contexts are named on the shadow cluster: - -* `identity`: Keep the source context names (default behavior for migrations). -* `exact`: Map each source context to a different destination context. - -[,yaml] ----- -schema_registry_sync_options: - shadow_schema_registry_api: - # ...connection settings and filters... - destination: - identity: {} # Keep source context names ----- - -To rename contexts during replication: - -[,yaml] ----- -schema_registry_sync_options: - shadow_schema_registry_api: - # ...connection settings and filters... - destination: - exact: - mappings: - - source: "." # Source context - destination: ".shadow" # Destination context on the shadow cluster ----- - -[IMPORTANT] -==== -With `exact` mapping, the mappings must cover every context that the link replicates. If the link encounters a source context that has no mapping, the schema replication task fails. If new contexts might be created on the source registry after you set up the link, scope the `source_filter` `contexts` list to the mapped contexts so that an unexpected context cannot stop replication. -==== - -[[choose-a-validation-policy]] -=== Choose a validation policy - -The `unsupported_schema_feature_policy` setting controls what happens when a source schema uses features that the Redpanda Schema Registry does not support. The unsupported Confluent Schema Registry features are: - -* In schema definitions: rule sets and metadata tags. -* In subject configurations: override metadata, override rule sets, default metadata, default rule sets, and compatibility groups. Compatibility groups are not the same as compatibility levels, which do replicate. - -The policy determines how the sync handles a schema or configuration that uses these features: - -[cols="1,3"] -|=== -| Policy | Behavior - -| `FAIL` (default) -| The schema is not replicated. The sync records an error, reports it in the link status, and continues with the remaining schemas. - -| `REMOVE` +* The destination contexts that the link replicates into, as determined by your `source_filter` and `destination` mapping, must be empty on the shadow cluster. The rest of the shadow cluster's Schema Registry does not need to be empty: contexts outside the link's mappings are unaffected. +* To replicate contexts other than the default context, the xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster property must be enabled on the shadow cluster (the default). See xref:manage:schema-reg/schema-reg-contexts.adoc#prerequisites[Schema Registry Contexts]. + +== Limitations + +* HTTP basic authentication and mTLS are the supported authentication methods for the source registry. +* A shadow link replicates Schema Registry data in one mode only: either `shadow_schema_registry_topic` or `shadow_schema_registry_api`. +* Replication is one way, from the source registry to the shadow cluster. Destination contexts owned by the link are read-only until failover. +* Schemas that use Confluent features not supported by the Redpanda Schema Registry are not replicated as-is. Choose a <> to control whether these schemas are skipped or imported without the unsupported fields. +* Topic data replication and schema replication are not coordinated with each other. Records serialized in the Confluent SerDes wire format can arrive on the shadow cluster before the schema IDs they contain have been replicated. +* Deleting and recreating a subject: A hard delete on the source replicates on the next sync, not instantly. Wait until the subject is removed from the shadow cluster before registering a new schema under the same name, as recreating it too soon prevents the sync job from detecting the subject/subject-version change. + +== Configure schema replication + +Add the `shadow_schema_registry_api` option to the `schema_registry_sync_options` section of your shadow link configuration file. + +The following sample configuration file creates a shadow link that replicates schemas from a Confluent Schema Registry. The highlighted lines show the schema replication settings, which the sections that follow explain. + +// NOTE: keep the lines= range pointing at the schema_registry_sync_options block +// if you edit this sample. +[,yaml,lines=13-31] +---- +# Sample shadow link configuration with API-mode Schema Registry replication + +name: confluent-migration # Unique name for this shadow link + +client_options: + bootstrap_servers: # Source Kafka cluster brokers + - : # Example: "pkc-xxxxx.us-east-1.aws.confluent.cloud:9092" + - : + # For the TLS and authentication settings that the shadow cluster uses to + # connect to the source Kafka cluster, see the complete configuration file + # reference in Configure Shadowing. + +schema_registry_sync_options: + shadow_schema_registry_api: # API mode: replicate from a Confluent Schema Registry + source_url: https://psrc-xxxxx.us-east-1.aws.confluent.cloud # Source Schema Registry endpoint + auth_options: + basic: + username: # Confluent Schema Registry API key + password: # Confluent Schema Registry API secret + tls_settings: + enabled: true # Use TLS for the connection + tail_interval: 10s # Optional: poll for incremental changes (default: 10s) + full_sync_interval: 5m # Optional: full source scan interval (default: 5m) + max_source_requests_per_second: 30 # Optional: rate limit for source requests (default: 30) + source_filter: + contexts: + - "." # The default context + subjects: [] # Empty: all subjects in the selected contexts + destination: + identity: {} # Keep source context names + unsupported_schema_feature_policy: FAIL # FAIL (default) or REMOVE +---- + +For the complete configuration file, including consumer offset and security synchronization options, see xref:manage:disaster-recovery/shadowing/setup.adoc#create-a-shadow-link[Configure Shadowing]. + +=== Generate a configuration template + +Generate a configuration file template that includes all available fields with comments: + +[,bash] +---- +rpk shadow config generate --print-template -o shadow-config-template.yaml +---- + +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`]. + +=== Connect to the source registry + +Configure the connection to the source Schema Registry: + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + source_url: https://psrc-xxxxx.us-east-1.aws.confluent.cloud # Source Schema Registry endpoint + auth_options: + basic: + username: # Confluent Schema Registry API key + password: # Confluent Schema Registry API secret + tls_settings: + enabled: true # Use TLS for the connection + tls_file_settings: + ca_path: /path/to/ca.crt # Optional: CA certificate for custom trust + tail_interval: 10s # How often to poll for incremental changes + full_sync_interval: 5m # How often to run a full scan + max_source_requests_per_second: 30 # Rate limit for requests to the source registry +---- + +The intervals and rate limit are optional. If you omit them, Redpanda uses the defaults shown above. + +To authenticate to the source registry with mTLS instead of HTTP basic authentication, omit `auth_options` and provide a client certificate and key in `tls_settings`. + +=== Select contexts and subjects + +By default, the link replicates the entire source registry. To replicate a subset, add a `source_filter` with the contexts or subjects to include: + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings... + source_filter: + contexts: + - "." # The default context + - ".prod" # A named context + subjects: + - orders-value # A subject in the default context +---- + +The `contexts` and `subjects` lists accept literal names only. Wildcard and prefix patterns are not supported. + +Schema Registry contexts provide independent namespaces for subjects within one registry. The default context is named `.`. For more information, see xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts]. + +=== Map source contexts to destination contexts + +Choose how replicated contexts are named on the shadow cluster: + +* `identity`: Keep the source context names (default behavior for migrations). +* `exact`: Map each source context to a different destination context. + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings and filters... + destination: + identity: {} # Keep source context names +---- + +To rename contexts during replication: + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings and filters... + destination: + exact: + mappings: + - source: "." # Source context + destination: ".shadow" # Destination context on the shadow cluster +---- + +[IMPORTANT] +==== +With `exact` mapping, the mappings must cover every context that the link replicates. If the link encounters a source context that has no mapping, the schema replication task fails. If new contexts might be created on the source registry after you set up the link, scope the `source_filter` `contexts` list to the mapped contexts so that an unexpected context cannot stop replication. +==== + +[[choose-a-validation-policy]] +=== Choose a validation policy + +The `unsupported_schema_feature_policy` setting controls what happens when a source schema uses features that the Redpanda Schema Registry does not support. The unsupported Confluent Schema Registry features are: + +* In schema definitions: rule sets and metadata tags. +* In subject configurations: override metadata, override rule sets, default metadata, default rule sets, and compatibility groups. Compatibility groups are not the same as compatibility levels, which do replicate. + +The policy determines how the sync handles a schema or configuration that uses these features: + +[cols="1,3"] +|=== +| Policy | Behavior + +| `FAIL` (default) +| The schema is not replicated. The sync records an error, reports it in the link status, and continues with the remaining schemas. + +| `REMOVE` | The unsupported fields are removed and the rest of the schema is imported. The sync records each modification in the link status. -|=== - -[,yaml] ----- -schema_registry_sync_options: - shadow_schema_registry_api: - # ...connection settings, filters, and destination... - unsupported_schema_feature_policy: FAIL ----- - -=== Create the shadow link - -Create the shadow link with your completed configuration file: - -[,bash] ----- -rpk shadow create --config-file shadow-config.yaml ----- - -For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. - -To change the schema replication settings on an existing link, see xref:reference:rpk/rpk-shadow/rpk-shadow-update.adoc[`rpk shadow update`]. - -== Verify the configuration - -Confirm that the link is configured for API-based schema replication: - -[,bash] ----- -rpk shadow describe ----- - -The output includes the shadowing mode, source URL, sync intervals, validation policy, and your context and subject filters. For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`]. - -== Monitor replication status - -Check schema replication progress and errors for a link: - -[,bash] ----- -rpk shadow status ----- - -The Schema Registry section of the output reports: - -[cols="1,3"] -|=== -| Field | Description - -| Inventory -| The number of selected subjects and subject versions on the source, compared with the number of subjects and versions on the destination. The registries are synchronized when the destination counts match the selected source counts. A destination that is behind the source indicates that replication is still in progress. - -| Current sync -| The type of the sync in progress (`FULL` or `TAIL`) and the number of subject versions, compatibility configurations, and modes it has changed, including how many unsupported features were removed and how many errors occurred. - -| Last full sync -| Start time, finish time, and change counts for the most recent completed full sync. - -| Totals since task start -| Cumulative change and error counts since the schema replication task started. - -| Last error -| The most recent replication error. With the `FAIL` validation policy, schemas that fail validation appear here. -|=== - -The schema replication task runs on the broker and shard that hosts the leader of the `_schemas` topic's partition. The counters in the status output are not persisted: expect them to reset to zero when that broker restarts or when leadership of the `_schemas` partition moves to another broker. - -For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`]. For general link monitoring, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing]. - -== Fail over - +|=== + +[,yaml] +---- +schema_registry_sync_options: + shadow_schema_registry_api: + # ...connection settings, filters, and destination... + unsupported_schema_feature_policy: FAIL +---- + +=== Create the shadow link + +Create the shadow link with your completed configuration file: + +[,bash] +---- +rpk shadow create --config-file shadow-config.yaml +---- + +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. + +To change the schema replication settings on an existing link, see xref:reference:rpk/rpk-shadow/rpk-shadow-update.adoc[`rpk shadow update`]. + +== Verify the configuration + +Confirm that the link is configured for API-based schema replication: + +[,bash] +---- +rpk shadow describe +---- + +The output includes the shadowing mode, source URL, sync intervals, validation policy, and your context and subject filters. For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`]. + +== Monitor replication status + +Check schema replication progress and errors for a link: + +[,bash] +---- +rpk shadow status +---- + +The Schema Registry section of the output reports: + +[cols="1,3"] +|=== +| Field | Description + +| Inventory +| The number of selected subjects and subject versions on the source, compared with the number of subjects and versions on the destination. The registries are synchronized when the destination counts match the selected source counts. A destination that is behind the source indicates that replication is still in progress. + +| Current sync +| The type of the sync in progress (`FULL` or `TAIL`) and the number of subject versions, compatibility configurations, and modes it has changed, including how many unsupported features were removed and how many errors occurred. + +| Last full sync +| Start time, finish time, and change counts for the most recent completed full sync. + +| Totals since task start +| Cumulative change and error counts since the schema replication task started. + +| Last error +| The most recent replication error. With the `FAIL` validation policy, schemas that fail validation appear here. +|=== + +The schema replication task runs on the broker and shard that hosts the leader of the `_schemas` topic's partition. The counters in the status output are not persisted: expect them to reset to zero when that broker restarts or when leadership of the `_schemas` partition moves to another broker. + +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`]. For general link monitoring, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing]. + +== Fail over + For best results, shadow links should be failed over as a single unit, which prevents partial failover scenarios and unexpected results. Selective failover, such as topics only, does not stop schema replication. As part of failover, pause the schema replication task by setting `paused: true` in the `schema_registry_sync_options` section of the link configuration. Pausing the task stops further syncing from the source registry and makes the write-blocked destination contexts writable, so your applications can register new schemas on the promoted cluster. - -For the complete failover procedure, see xref:manage:disaster-recovery/shadowing/failover.adoc[Failover]. - -== Next steps - -* xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing] to replicate topic data, consumer offsets, and ACLs alongside your schemas. -* xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing] -* xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts] - -// end::single-source[] + +For the complete failover procedure, see xref:manage:disaster-recovery/shadowing/failover.adoc[Failover]. + +== Next steps + +* xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing] to replicate topic data, consumer offsets, and ACLs alongside your schemas. +* xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing] +* xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts] + +// end::single-source[] From 84f515f1e1d816711d5ac1191bce954f8c73b01b Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 20 Jul 2026 13:13:31 -0400 Subject: [PATCH 15/17] Explain source_filter union semantics and SerDes consumer impact Per Gellert's answers to Trevor's review questions: - Rework the Select contexts and subjects example so the two lists no longer overlap (the old example's subject was already inside a listed context), and add the union semantics from shadow_link.proto: contexts replicate in full, subjects use qualified syntax, both lists union, overlaps replicate once - Extend the SerDes coordination limitation with the user impact: no replication errors (schema IDs not validated during topic data replication), but consumers fail on unreplicated schema IDs, so wait for schema replication to catch up before consuming Co-Authored-By: Claude Fable 5 --- .../shadowing/migrate-schemas-confluent.adoc | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc index 9a2fa9bb13..01964bd2a0 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc @@ -67,7 +67,7 @@ Schema replication settings live in the shadow link configuration. Two cluster p * A shadow link replicates Schema Registry data in one mode only: either `shadow_schema_registry_topic` or `shadow_schema_registry_api`. * Replication is one way, from the source registry to the shadow cluster. Destination contexts owned by the link are read-only until failover. * Schemas that use Confluent features not supported by the Redpanda Schema Registry are not replicated as-is. Choose a <> to control whether these schemas are skipped or imported without the unsupported fields. -* Topic data replication and schema replication are not coordinated with each other. Records serialized in the Confluent SerDes wire format can arrive on the shadow cluster before the schema IDs they contain have been replicated. +* Topic data replication and schema replication are not coordinated with each other. Records serialized in the Confluent SerDes wire format can arrive on the shadow cluster before the schema IDs they contain have been replicated. This does not cause replication errors, because schema IDs are not validated during topic data replication, but consumers that look up those schema IDs on the shadow cluster fail until the schemas arrive. Wait for schema replication to catch up before consuming schema-dependent shadow topics. See <>. * Deleting and recreating a subject: A hard delete on the source replicates on the next sync, not instantly. Wait until the subject is removed from the shadow cluster before registering a new schema under the same name, as recreating it too soon prevents the sync job from detecting the subject/subject-version change. == Configure schema replication @@ -163,12 +163,19 @@ schema_registry_sync_options: # ...connection settings... source_filter: contexts: - - "." # The default context - - ".prod" # A named context + - ".prod" # Replicate this entire context subjects: - - orders-value # A subject in the default context + - orders-value # One subject from the default context ---- +The two lists combine as a union: + +* `contexts` selects entire contexts: every subject in each listed context replicates. +* `subjects` selects individual subjects, using qualified subject syntax: `orders-value` is the subject in the default context, and `:.staging:orders-value` is the subject of the same name in the `.staging` context. +* When both lists are set, the link replicates everything selected by either list. A subject selected by both lists replicates once. + +For example, the preceding filter replicates every subject in the `.prod` context, plus the single `orders-value` subject from the default context. + The `contexts` and `subjects` lists accept literal names only. Wildcard and prefix patterns are not supported. Schema Registry contexts provide independent namespaces for subjects within one registry. The default context is named `.`. For more information, see xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts]. From 6cedb4a53773a4427d2c18514b2490d927756ce8 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 20 Jul 2026 13:22:07 -0400 Subject: [PATCH 16/17] Gate migrate-schemas-confluent xrefs to Self-Managed cloud-docs has no consuming stub for the new page (the cloud twin is deferred to DOC-2307), so xrefs to it from the shared regions of the single-sourced shadowing pages would break every cloud build with target-not-found errors. Gate the cross-link sentences ifndef::env-cloud, gate monitor.adoc's Schema Registry sync status bullet entirely (it describes API-mode-only output), and give the overview's replication paragraph a cloud variant that mentions topic-mode replication only. Co-Authored-By: Claude Fable 5 --- .../pages/disaster-recovery/shadowing/monitor.adoc | 2 ++ .../pages/disaster-recovery/shadowing/overview.adoc | 13 +++++++++++-- .../pages/disaster-recovery/shadowing/setup.adoc | 5 ++++- 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index 0908026350..abeea2b8fe 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -158,7 +158,9 @@ endif::[] * **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`). * **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Shadow link tasks]. * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). +ifndef::env-cloud[] * **Schema Registry sync status**: For links that replicate schemas through the Schema Registry API, inventory counts for source and destination subjects, sync progress, and the most recent error. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc#monitor-replication-status[Monitor replication status]. +endif::[] include::manage:partial$shadowing/shadow-link-metrics.adoc[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 29848ed008..5c9b6d6202 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -119,7 +119,10 @@ The **Schema Registry Sync task** replicates Schema Registry content so that app The task is controlled by the `schema_registry_sync_options` section in the configuration file. It supports two modes: * **Topic mode** (`shadow_schema_registry_topic`): Shadows the `_schemas` system topic for byte-for-byte replication from another Redpanda cluster. -* **API mode** (`shadow_schema_registry_api`): Polls the source Schema Registry over HTTP and imports selected contexts and subjects, with validation. Use this mode to replicate schemas from a Confluent Schema Registry. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent Schema Registry]. +* **API mode** (`shadow_schema_registry_api`): Polls the source Schema Registry over HTTP and imports selected contexts and subjects, with validation. Use this mode to replicate schemas from a Confluent Schema Registry. +ifndef::env-cloud[] +See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent Schema Registry]. +endif::[] A shadow link uses one mode or the other, not both. Only API mode runs as a separate task that appears in the shadow link status. Topic mode adds the `_schemas` topic to the set of shadowed topics, so it is monitored like any other shadow topic rather than as a separate task. -- @@ -143,7 +146,13 @@ For monitoring task health and troubleshooting task issues, see xref:manage:disa Shadowing replicates your topic data with complete fidelity, preserving all message records with their original offsets, timestamps, headers, and metadata. The partition structure remains identical between source and shadow clusters, ensuring applications can resume processing from the exact same position after failover. -Consumer group data flows according to your group filters, replicating offsets and membership information for matched groups. ACLs replicate based on your security filters. Schema Registry data synchronizes schema definitions, versions, and compatibility settings, either by shadowing the `_schemas` topic or through the xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Schema Registry API]. +Consumer group data flows according to your group filters, replicating offsets and membership information for matched groups. ACLs replicate based on your security filters. +ifndef::env-cloud[] +Schema Registry data synchronizes schema definitions, versions, and compatibility settings, either by shadowing the `_schemas` topic or through the xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Schema Registry API]. +endif::[] +ifdef::env-cloud[] +Schema Registry data synchronizes schema definitions, versions, and compatibility settings by shadowing the `_schemas` topic. +endif::[] Partition count is always replicated to ensure the shadow topic matches the source topic's partition structure. diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index dd476821f6..e809c4c83d 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -490,7 +490,10 @@ consumer_offset_sync_options: Shadowing can replicate Schema Registry data in one of two modes: * **Topic mode** (`shadow_schema_registry_topic`): Shadows the `_schemas` system topic for byte-for-byte replication of schema definitions, versions, and compatibility settings from another Redpanda cluster. -* **API mode** (`shadow_schema_registry_api`): Polls the source Schema Registry over HTTP and imports selected contexts and subjects, with validation. Use this mode to replicate schemas from a Confluent Schema Registry, or to replicate only part of the source registry. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent Schema Registry]. +* **API mode** (`shadow_schema_registry_api`): Polls the source Schema Registry over HTTP and imports selected contexts and subjects, with validation. Use this mode to replicate schemas from a Confluent Schema Registry, or to replicate only part of the source registry. +ifndef::env-cloud[] +See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[Migrate Schemas from Confluent Schema Registry]. +endif::[] A shadow link uses one mode or the other, not both. From 68900b1527f14acb7ea74071ce049207969d5df9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Jul 2026 17:40:17 +0000 Subject: [PATCH 17/17] Resolve merge conflict in monitor.adoc: combine SR and role sync bullets in ifndef block --- modules/manage/pages/disaster-recovery/shadowing/monitor.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index fa637a8d44..8621ec42bb 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -160,11 +160,7 @@ endif::[] * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). ifndef::env-cloud[] * **Schema Registry sync status**: For links that replicate schemas through the Schema Registry API, inventory counts for source and destination subjects, sync progress, and the most recent error. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc#monitor-replication-status[Monitor replication status]. -<<<<<<< HEAD -ifndef::env-cloud[] * **Role sync counts**: For links that replicate RBAC roles, the `Reason` field of the xref:manage:disaster-recovery/shadowing/overview.adoc#roles-migrator-task[Roles Migrator task] reports the counts from the most recent sync cycle (roles created, updated, deleted, and failures). See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering]. -======= ->>>>>>> origin/DOC-2254-confluent-schema-registry-migration endif::[] include::manage:partial$shadowing/shadow-link-metrics.adoc[]