Restore a Kafka topic from backup — without guesswork
The topic is gone, or its data is wrong, and you have a backup. This is the runbook: find the backup, rehearse the restore, then replay it — to the same cluster, a new one, or a new topic name.
How to restore a Kafka topic from backup
A topic restore replays backed-up records into a target cluster. The restore creates the topic if it no longer exists, keeps the original partition layout, and can reposition consumer groups where they left off. Three steps: list your backups, validate the restore plan, then run it.
- 1. Find the backup
- 2. restore.yaml
- 3. Rehearse, then run
kafka-backup list --path s3://my-kafka-backups/backups/production
kafka-backup list --path s3://my-kafka-backups/backups/production \
--backup-id prod-backup-20260810
mode: restore
backup_id: "prod-backup-20260810"
target:
bootstrap_servers:
- broker-1.kafka.svc:9092
storage:
backend: s3
bucket: my-kafka-backups
region: us-west-2
prefix: backups/production
topics:
include:
- orders # Restore just this topic
restore:
create_topics: true # Recreate it if it was deleted
default_replication_factor: 3
consumer_group_strategy: header-based
# Checks the backup, target cluster, and config together
kafka-backup validate-restore --config restore.yaml
# The real thing
kafka-backup restore --config restore.yaml
validate-restore verifies the backup exists, the target cluster is reachable,
and the plan is consistent — without writing anything. Keep dry_run: true in
the config as a second guard until you are ready.
Match the restore config to the failure
The restore options change with the situation. Every key below is documented in the configuration reference.
| Situation | Config to use | What happens |
|---|---|---|
| Topic was deleted | create_topics: true with default_replication_factor | The topic is recreated, then records are replayed into it |
| Live topic still exists and must stay | topic_mapping: {orders: orders_restored} | The backup replays under a new name, next to the live topic |
| Bad records after a known time | time_window_end (Unix ms) | Only records before the incident are restored — see point-in-time recovery |
| Restoring into a different cluster | target.bootstrap_servers pointing at the new cluster | Same backup, different destination — staging replays and migrations work the same way |
| Managed topic that cannot be deleted | purge_topics: true | Existing records are purged via the DeleteRecords API before replay — safe for Strimzi-managed topics |
Bring consumer groups back with the data
Restoring records without consumer positions forces every application to
reprocess from the beginning or skip to the end. Backups store original
offsets in record headers, and consumer_group_strategy: header-based maps
each group to its equivalent position after the restore.
To run the restore and the offset reset as one operation, use
kafka-backup three-phase-restore --config restore.yaml. It collects the
offset headers, restores the data, and resets consumer groups in sequence.
With auto_consumer_groups: true, the group list comes from the backup's own
consumer group snapshot.
For choosing a backup method in the first place — CLI, Connect S3 sink, or consumer scripts — read the topic backup and restore guide. For selecting which topics to back up, see backup Kafka topics selectively.
Frequently asked questions
How do I restore a Kafka topic from a backup?
Write a restore config naming the backup_id, target cluster, storage location, and topic, then run kafka-backup restore --config restore.yaml. Run kafka-backup validate-restore first to check the plan without producing records.
Can I restore a deleted Kafka topic?
Yes, if a backup was taken before the deletion. Set create_topics: true and a default_replication_factor in the restore config, and the topic is recreated before records are replayed. Replication cannot do this — deletes propagate to replicas.
Can I restore a Kafka topic to a different cluster?
Yes. The restore target is independent of the backup source — point target.bootstrap_servers at any cluster. Combine it with topic_mapping to restore under a different topic name.
How do I test a Kafka topic restore without writing records?
Two guards exist: kafka-backup validate-restore checks the backup, target, and config together and reports without producing, and dry_run: true in the restore config validates the full plan at execution time.
Do consumer groups keep their positions after a topic restore?
Yes, with consumer_group_strategy: header-based. Original offsets stored in record headers are mapped to post-restore offsets, and each consumer group resumes from the equivalent position. The three-phase-restore command runs the data restore and offset reset together.
Ready to protect your Kafka data?
Take your first backup in minutes with the open source CLI, or talk to us about Enterprise features like encryption, RBAC, and audit logging.