# Migrate Schemas from Confluent Schema Registry

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: Migrate Schemas from Confluent Schema Registry
latest-redpanda-tag: v26.2.1
latest-console-tag: v3.10.0
latest-operator-version: v26.2.2
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "false"
page-eol-date: July 28, 2027
latest-connect-version: 4.105.0
docname: disaster-recovery/shadowing/migrate-schemas-confluent
page-component-name: streaming
page-version: "26.2"
page-component-version: "26.2"
page-component-title: Streaming
page-relative-src-path: disaster-recovery/shadowing/migrate-schemas-confluent.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/migrate-schemas-confluent.adoc
description: Replicate subjects, versions, and compatibility settings from a Confluent Schema Registry into a Redpanda shadow cluster.
page-topic-type: how-to
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
page-git-created-date: "2026-07-20"
page-git-modified-date: "2026-08-04"
support-status: supported
---

<!-- Source: https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/migrate-schemas-confluent.md -->

> 📝 **NOTE**
>
> This feature requires an [enterprise license](https://docs.redpanda.com/streaming/current/get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade).
>
> If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](https://docs.redpanda.com/streaming/current/get-started/licensing/#self-managed) apply.

When you migrate to Redpanda from a deployment that uses a Confluent Schema Registry, your producers and consumers depend on the [schemas](https://docs.redpanda.com/streaming/current/reference/glossary/#schema) stored in that registry. Shadowing removes this migration obstacle: a [shadow link](https://docs.redpanda.com/streaming/current/reference/glossary/#shadow-link) continuously replicates schemas from the source Confluent Schema Registry into the [Schema Registry](https://docs.redpanda.com/streaming/current/reference/glossary/#schema-registry) built into the Redpanda [shadow cluster](https://docs.redpanda.com/streaming/current/reference/glossary/#shadow-cluster), preserving [subject](https://docs.redpanda.com/streaming/current/reference/glossary/#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:

-   Configure a shadow link that continuously replicates schemas from a Confluent Schema Registry

-   Filter replication by context or subject and map source contexts to destination contexts

-   Monitor schema replication status and resolve validation errors


## [](#how-http-api-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:

-   **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 [validation policy](#choose-a-validation-policy) 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 [Configure Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/setup/#schema-registry-synchronization). 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)Use cases

-   **Migrate from Confluent to Redpanda**: Replicate schemas continuously while [Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/setup/) 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)Prerequisites

-   A cluster running Redpanda version 26.2 or later. The schema replication feature activates after all brokers complete the upgrade.

-   To configure schema replication in [Redpanda Console](https://docs.redpanda.com/streaming/current/console/) rather than with `rpk`, Redpanda Console v3.9.0 or later. The Schema Registry fields appear only when the shadow cluster reports Redpanda 26.2 or later. On an earlier cluster, Redpanda Console falls back to a single toggle that enables `_schemas` topic replication, and API mode is unavailable.

-   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 [Configure Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/setup/).

-   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 [`schema_registry_enable_qualified_subjects`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#schema_registry_enable_qualified_subjects) cluster property must be enabled on the shadow cluster (the default). See [Schema Registry Contexts](https://docs.redpanda.com/streaming/current/manage/schema-reg/schema-reg-contexts/#prerequisites).


## [](#limitations)Limitations

-   HTTP basic authentication and mTLS are the supported authentication methods for the source registry. You can also connect to a source registry that requires no authentication.

-   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 [validation policy](#choose-a-validation-policy) 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. 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 [Monitor replication status](#monitor-replication-status).

-   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)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.

```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
  - <source-broker-1>:<port>                 # Example: "pkc-xxxxx.us-east-1.aws.confluent.cloud:9092"
  - <source-broker-2>:<port>
  # 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: <sr-api-key>               # Confluent Schema Registry API key
        password: <sr-api-secret>            # 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 [Configure Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/setup/#create-a-shadow-link).

### [](#generate-a-configuration-template)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 [`rpk shadow config generate`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-shadow/rpk-shadow-config-generate/).

### [](#connect-to-the-source-registry)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: <sr-api-key>                # Confluent Schema Registry API key
        password: <sr-api-secret>             # 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`.

To connect to a source registry that requires no authentication, omit `auth_options` and do not provide a client certificate.

### [](#select-contexts-and-subjects)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:
      - ".prod"                               # Replicate this entire context
      subjects:
      - 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 [Schema Registry Contexts](https://docs.redpanda.com/streaming/current/manage/schema-reg/schema-reg-contexts/).

### [](#map-source-contexts-to-destination-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:

| 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

Create the shadow link with your completed configuration file:

```bash
rpk shadow create --config-file shadow-config.yaml
```

For detailed command options, see [`rpk shadow create`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-shadow/rpk-shadow-create/).

To change the schema replication settings on an existing link, see [`rpk shadow update`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-shadow/rpk-shadow-update/).

## [](#configure-schema-replication-in-redpanda-console)Configure schema replication in Redpanda Console

[Redpanda Console](https://docs.redpanda.com/streaming/current/console/) writes the same schema replication settings as a configuration file. The modes, filters, and validation policy behave identically; only the names of the fields differ. Use the [field mapping](#console-fields-and-configuration-keys) to move between the two.

### [](#create-a-shadow-link-with-api-mode-schema-replication)Create a shadow link with API-mode schema replication

Every schema replication setting lives in the **Shadow Schema Registry** card. Selecting the **Other** mode tab reveals the source connection, scope, and sync behavior sections:

![The Shadow Schema Registry card in Redpanda Console, with the Other mode tab selected and the source connection, scope, and sync behavior sections visible](https://docs.redpanda.com/streaming/current/console/_images/shadow-link-schema-registry.png)

1.  From the navigation menu, select **Shadow Links**, then click **Create shadow link**.

2.  On the **Connection** step, complete the connection details for the source Kafka cluster. See [Configure Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/setup/#create-a-shadow-link).

3.  On the **Configuration** step, in the **Shadow Schema Registry** card, select the **Other** mode tab. **Other** is API mode. **Redpanda** shadows the `_schemas` topic instead, and **None** leaves the shadow cluster’s Schema Registry independent.

4.  Under **Source connection**, enter the **Source URL** of the source Schema Registry.

5.  For **Authentication**, select the method that the source registry requires:

    -   **HTTP Basic**: enter the **Username** and **Password**. For Confluent Cloud, these are the Schema Registry API key and secret.

    -   **None**: Redpanda sends requests to the source registry without authentication. Also select **None** to authenticate with mTLS, then provide a client certificate and private key in the TLS settings in the next step.


6.  Leave **Enable TLS** on to connect to the source registry over TLS. It is on by default. Turn it off only if the source registry does not use TLS. To trust a private certificate authority, upload a CA certificate. To authenticate with mTLS, provide a client certificate and private key.

7.  Under **Scope**, choose what to replicate:

    -   **Entire Schema Registry** replicates every context and subject.

    -   **Specify contexts and subjects** limits replication to the **Contexts** and **Subjects** that you enter. Press Enter after each entry. The two lists combine as a union. For the selection rules and the qualified subject syntax, see [Select contexts and subjects](#select-contexts-and-subjects).


8.  Under **Destination contexts**, select **Preserve source context names** to keep the source names, or **Map source contexts to explicit destination contexts** to rename them. With explicit mapping, every source context in scope must map to a distinct destination context. See [Map source contexts to destination contexts](#map-source-contexts-to-destination-contexts).

9.  Optional: expand **Sync behavior** to change the **Tail interval**, **Full sync interval**, **Max source request rate**, or the **Unsupported schema features** policy. Leave these fields empty to use the cluster defaults.

10.  Click **Create shadow link**.


Redpanda Console does not test the source connection or list the matching subjects before you save. To confirm that the link works, [verify the configuration](#verify-the-configuration), then [monitor replication status](#monitor-replication-status).

### [](#console-fields-and-configuration-keys)Console fields and configuration keys

Most fields carry the name of the configuration key they set, such as **Tail interval** for `tail_interval`. The following fields do not:

| Redpanda Console | Configuration key |
| --- | --- |
| Shadow Schema Registry mode: Redpanda, Other, or None | shadow_schema_registry_topic, shadow_schema_registry_api, or neither |
| Authentication: HTTP Basic or None | auth_options.basic, with username and password, or auth_options omitted |
| Enable TLS, CA certificate, and client certificate and key | tls_settings |
| Scope: Entire Schema Registry or Specify contexts and subjects, with Contexts and Subjects | source_filter.contexts and source_filter.subjects |
| Destination contexts: Preserve source context names | destination.identity |
| Destination contexts: Map source contexts to explicit destination contexts | destination.exact.mappings |
| Max source request rate | max_source_requests_per_second |
| Unsupported schema features: Fail the sync or Remove unsupported features | unsupported_schema_feature_policy: FAIL or REMOVE |

### [](#edit-an-existing-shadow-link)Edit an existing shadow link

You can change the schema replication settings of an existing link in Redpanda Console, with the following constraints:

-   You cannot switch an existing link directly between **Redpanda** and **Other**. Redpanda Console locks the unavailable tab. To use a different Schema Registry replication mode, create a new shadow link.

-   Switching away from **Other** discards the stored Schema Registry connection settings, including credentials, scope, and sync behavior. Redpanda Console warns you before you save.

-   Turning off **Redpanda** mode does not remove a `_schemas` shadow topic that the link already added. To stop shadowing that topic, fail over the link, or delete the shadow topic after you save. Deleting the topic also discards the schemas that the link replicated into it, so fail over instead if you need to keep them.

-   When you edit a link that uses **HTTP Basic**, Redpanda Console requires you to re-enter the **Password**. It never populates the field with the stored value, and it does not accept an empty field.

-   Redpanda Console preserves settings that it does not expose, such as `paused`, when you save.


## [](#verify-the-configuration)Verify the configuration

Confirm that the link is configured for API-based schema replication.

### [](#use-rpk)Use rpk

```bash
rpk shadow describe <link-name>
```

The output includes the shadowing mode, source URL, sync intervals, validation policy, and your context and subject filters. For detailed command options, see [`rpk shadow describe`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-shadow/rpk-shadow-describe/).

### [](#use-redpanda-console)Use Redpanda Console

On the shadow link’s detail page, the **Schema Registry** section reports the stored configuration as read-only:

| Field | Description |
| --- | --- |
| Connection | The Source URL of the source Schema Registry. |
| Authentication | The authentication Type and Username. The Password shows as Set, Not set, or the date it last changed; Redpanda Console never displays the stored value. When the link does not use HTTP basic authentication, this section reports that no authentication is configured. |
| TLS | Whether TLS is Enabled, whether the Trust store is a Custom CA or the System trust store, and whether Client auth uses an mTLS certificate. |
| Scope | Either Entire Schema Registry, or the Contexts and Subjects that the link replicates. |
| Destination contexts mapping | The source-to-destination context mappings, or the source names when the link preserves them. |
| Sync behavior | The tail interval, full sync interval, max source request rate, and unsupported schema features policy. Shows Cluster defaults when the link does not override them. |

## [](#monitor-replication-status)Monitor replication status

Check schema replication progress and errors for a link:

```bash
rpk shadow status <link-name>
```

The Schema Registry section of the output reports:

| 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 [`rpk shadow status`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-shadow/rpk-shadow-status/). For general link monitoring, see [Monitor Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/monitor/).

## [](#fail-over)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 [Failover](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/failover/).

## [](#next-steps)Next steps

-   [Configure Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/setup/) to replicate topic data, consumer offsets, and ACLs alongside your schemas.

-   [Monitor Shadowing](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/monitor/)

-   [Schema Registry Contexts](https://docs.redpanda.com/streaming/current/manage/schema-reg/schema-reg-contexts/)