# Migrate to the Unified Redpanda Migrator

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

---
title: Migrate to the Unified Redpanda Migrator
latest-connect-version: 4.93.0
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-redpanda-tag: v26.1.9
docname: migration/migrate-unified-redpanda-migrator
page-component-name: connect
page-version: master
page-component-version: master
page-component-title: Connect
page-relative-src-path: migration/migrate-unified-redpanda-migrator.adoc
page-edit-url: https://github.com/redpanda-data/rp-connect-docs/edit/main/modules/guides/pages/migration/migrate-unified-redpanda-migrator.adoc
description: Learn how to migrate from legacy migrator components to the unified `redpanda_migrator` input/output pair in Redpanda Connect 4.67.5+.
page-git-created-date: "2025-10-24"
page-git-modified-date: "2026-03-31"
---

<!-- Source: https://docs.redpanda.com/connect/guides/migration/migrate-unified-redpanda-migrator.md -->

> ❗ **IMPORTANT**
>
> This page is about migrating to a newer version of Redpanda Connect. For information about migrating your data using Redpanda Migrator, see [Redpanda Migrator](https://docs.redpanda.com/connect/cookbooks/redpanda_migrator/).

This guide explains how to migrate from legacy migrator components (`redpanda_migrator_bundle`, `legacy_redpanda_migrator` and `legacy_redpanda_migrator_offsets`) to the unified `redpanda_migrator` input/output pair introduced in Redpanda Connect 4.67.5+.

The unified migrator consolidates all migration logic into a single input/output pair, simplifying configuration and improving reliability.

## [](#overview)Overview

| Available in | Redpanda Connect 4.67.5+ |
| --- | --- |
| Legacy status | Deprecated in 4.67.5, removed in 4.85.0 |
| Compatibility | Not backward-compatible |
| Configuration model | One input and one output, paired by label |
| Primary control | All migration logic resides in the output component |

Key concepts:

-   Components are paired by matching `label` values.

-   The input defines the source cluster and schema registry.

-   The output defines the destination cluster, schema registry, and migration behavior.

-   Topic mapping and consumer group migration are configured in the output.


## [](#architectural-changes)Architectural changes

### [](#legacy-architecture)Legacy architecture

A complex bundle (`redpanda_migrator_bundle`) that managed three subcomponents:

-   `redpanda_migrator`: Data transfer

-   `schema_registry`: Schema synchronization

-   `redpanda_migrator_offsets`: Consumer group offsets


This design required complex internal routing and sequencing.

### [](#unified-architecture)Unified architecture

A single `redpanda_migrator` input/output pair replaces the bundle:

-   **Input**: Consumes from the source Kafka cluster.

-   **Output**: Handles topic creation, schema synchronization, ACLs, and consumer group offsets.


Benefits:

-   Simplified setup: all configuration consolidated in one output component.

-   Improved coordination: no internal routing or wrapper logic.

-   Enhanced control: fine-grained schema and topic options, improved offset handling.


## [](#migration-steps)Migration steps

Follow this checklist in order to ensure a safe, low-risk migration.

-    Back up your existing configurations.

-    Add new `input.redpanda_migrator` and `output.redpanda_migrator` components with matching labels.

-    Move source Kafka and Schema Registry settings to the input.

-    Move destination Kafka and Schema Registry settings to the output.

-    Replace `topic_prefix` with `topic` using interpolation syntax.

-    Move offset settings to `output.redpanda_migrator.consumer_groups`.

-    Remove deprecated fields.

-    Validate configuration with `rpk connect lint`.

-    Test using non-production topics first.

-    Monitor logs and performance during migration.

-    Remove legacy configuration after successful migration.


## [](#field-mapping-reference)Field mapping reference

### [](#bundle-wrapper-redpanda_migrator_bundle)Bundle wrapper (`redpanda_migrator_bundle`)

#### [](#input-mapping)Input mapping

| Legacy Field | New Location | Status | Notes |
| --- | --- | --- | --- |
| redpanda_migrator | input.redpanda_migrator | Moved | Source cluster connection |
| schema_registry | input.redpanda_migrator.schema_registry | Moved | Source schema registry |
| migrate_schemas_before_data | - | Removed | Controlled by output schema interval |
| consumer_group_offsets_poll_interval | output.redpanda_migrator.consumer_groups.interval | Moved | Now controls sync frequency |

#### [](#output-mapping)Output mapping

| Legacy Field | New Location | Status | Notes |
| --- | --- | --- | --- |
| redpanda_migrator | output.redpanda_migrator | Moved | Destination cluster configuration |
| schema_registry | output.redpanda_migrator.schema_registry | Moved | Destination schema registry |
| translate_schema_ids | output.redpanda_migrator.schema_registry.translate_ids | Moved | Schema ID translation |
| input_bundle_label | label | Replaced | Input and output paired by label |

### [](#data-migration-fields)Data migration fields

| Legacy Field | New Location | Status | Notes |
| --- | --- | --- | --- |
| All (*) | input.redpanda_migrator.* | Moved | Direct mapping |
| topics (explicit list) | input.redpanda_migrator.topics | Unchanged | Still supported for explicit lists |
| regexp_topics: true | input.redpanda_migrator.regexp_topics_include, regexp_topics_exclude | Deprecated | Use include/exclude arrays for pattern-based selection |
| topic_prefix | output.redpanda_migrator.topic | Replaced | Use interpolation, for example 'prefix_${! @kafka_topic }' |
| replication_factor_override, replication_factor | output.redpanda_migrator.topic_replication_factor | Replaced | Unified field |
| input_resource | label | Replaced | Label pairing replaces internal routing |
| - | output.redpanda_migrator.provenance_header | New | Optional header for tracking message source cluster |

### [](#schema-migration-fields)Schema migration fields

| Legacy Field | New Location | Status | Notes |
| --- | --- | --- | --- |
| Connection fields | input.redpanda_migrator.schema_registry.* | Moved | Source schema registry |
| subject_filter | output.redpanda_migrator.schema_registry.include, exclude | Replaced | Use regex lists for filtering |
| include_deleted | output.redpanda_migrator.schema_registry.include_deleted | Moved | Configured on destination |
| backfill_dependencies | output.redpanda_migrator.schema_registry.versions | Replaced | Choose all or latest |

### [](#consumer-group-offset-migration)Consumer group offset migration

The `redpanda_migrator_offsets` pair is replaced by the `consumer_groups` block in the output.

| Legacy Component | New Location | Status | Notes |
| --- | --- | --- | --- |
| redpanda_migrator_offsets (input/output) | output.redpanda_migrator.consumer_groups | Replaced | Unified control block |

## [](#migration-example)Migration example

The following example demonstrates a complete migration from legacy to unified components.

Legacy configuration

```yaml
input:
  label: "source_cluster"
  redpanda_migrator_bundle:
    legacy_redpanda_migrator:
      seed_brokers: [ "source-kafka:9092" ]
      topics: [ "orders", "payments" ]
      consumer_group: "migration_group"
    schema_registry:
      url: "http://source-registry:8081"
    migrate_schemas_before_data: false
    consumer_group_offsets_poll_interval: 30s

output:
  redpanda_migrator_bundle:
    legacy_redpanda_migrator:
      seed_brokers: [ "destination-redpanda:9092" ]
      topic_prefix: "migrated_"
    schema_registry:
      url: "http://destination-registry:8081"
    translate_schema_ids: true
    input_bundle_label: "source_cluster"
```

Unified configuration

```yaml
input:
  label: "migration_pipeline" (1)
  redpanda_migrator:
    # Source Kafka settings
    seed_brokers: [ "source-kafka:9092" ]

    # Pattern-based topic selection (for migrating all topics except system topics)
    # Note: You can still use explicit lists: topics: [ "orders", "payments" ]
    regexp_topics_include: [ '.' ] (2)
    regexp_topics_exclude: [ '^_' ] (3)
    consumer_group: "migration_group"

    # Source Schema Registry settings
    schema_registry:
      url: "http://source-registry:8081"

output:
  label: "migration_pipeline" (4)
  redpanda_migrator:
    # Destination Redpanda settings
    seed_brokers: [ "destination-redpanda:9092" ]

    # Topic mapping (replaces topic_prefix)
    topic: 'migrated_${! @kafka_topic }' (5)

    # Add source cluster tracking header
    provenance_header: "x-source-cluster" (6)

    # Destination Schema Registry and migration settings
    schema_registry:
      url: "http://destination-registry:8081"
      translate_ids: true
      # Rename subjects
      subject: 'migrated_${! metadata("schema_registry_subject") }'

    # Consumer group migration settings
    consumer_groups:
      enabled: true
      interval: 30s (7)
```

| 1 | Labels are now used for pairing input and output. |
| --- | --- |
| 2 | Match all topics using regex pattern. |
| 3 | Exclude internal/system topics starting with underscore. |
| 4 | Matching label pairs the input and output components. |
| 5 | Use interpolation syntax to replicate topic_prefix behavior. |
| 6 | Adds a header to track which cluster messages originated from, useful for debugging and auditing. |
| 7 | Replaces consumer_group_offsets_poll_interval. |

## [](#validation)Validation

Before running, validate your configuration:

```bash
rpk connect lint config.yaml
```

Then test on a small set of topics before running full migrations.

## [](#troubleshooting)Troubleshooting

| Problem | Likely Cause | Solution |
| --- | --- | --- |
| Labels do not match | Input and output labels differ | Use identical, case-sensitive labels. |
| Topic interpolation errors | Incorrect syntax | Use topic: 'prefix_${! @kafka_topic }' with quotes and !. |
| Schema registry connection fails | Incorrect registry placement | The source registry must be in the input. The destination registry must be in the output. |
| Consumer group migration not working | Missing consumer_groups.enabled: true | Ensure consumer group migration is explicitly enabled. |

## [](#after-migration)After migration

After verifying that the new migrator works as expected:

-   Remove legacy configuration files.

-   Update internal documentation and runbooks.

-   Train your team on the new configuration model.

-   See the [`redpanda_migrator` output](https://docs.redpanda.com/connect/components/outputs/redpanda_migrator/) reference for advanced configuration options.