MSK KRaft Migration CLI Reference

All migration commands use the subcommand structure:

kafka-backup migrate msk-kraft <SUBCOMMAND> [OPTIONS]

plan

Generate a migration plan without making any changes. No license required.

kafka-backup migrate msk-kraft plan \
  --config <PATH> \
  [--format <FORMAT>] \
  [--out-dir <PATH>] \
  [--migration-id <ID>] \
  [--force]

Flag	Type	Required	Default	Description
`--config`	PATH	Yes	—	Path to migration config YAML
`--format`	enum	No	`json`	Output format: `json`, `runbook`, `aws-cli`, `iam-policy`, `cost`, `all`
`--out-dir`	PATH	No	—	Directory for output artifacts. Required when `--format all`.
`--migration-id`	string	No	auto-generated	Pin the migration ID for deterministic output
`--force`	flag	No	`false`	Overwrite existing files in `--out-dir`

Output artifacts (`--format all`)

File	Description
`plan.json`	Machine-readable migration plan
`runbook.md`	Step-by-step operator runbook
`aws-cli.sh`	AWS CLI commands for infrastructure setup
`iam-policy-templated.json`	IAM policy template with placeholders
`iam-policy-concrete.json`	IAM policy with your actual ARNs
`cost-estimate.json`	Estimated S3 and data transfer costs

Example

kafka-backup migrate msk-kraft plan \
  --config migration.yaml \
  --format all \
  --out-dir ./migration-plan

precheck

Read-only infrastructure and compatibility checks. No license required.

kafka-backup migrate msk-kraft precheck --config <PATH>

Flag	Type	Required	Description
`--config`	PATH	Yes	Path to migration config YAML

Output

JSON-formatted report with findings categorized as Blocker, Warning, or Info. See Precheck Codes Reference for all codes.

Example output:

W04 warn: could not verify target message-size floor (target broker DescribeConfigs returned no message.max.bytes or replica.fetch.max.bytes (dynamic-config only on this broker)) — ensure target `message.max.bytes` and `replica.fetch.max.bytes` ≥ largest source topic's effective max.message.bytes
W03 info: KMS key ARN set on backup channel — CMK access is not verified by this precheck phase; ensure the caller has kms:Encrypt/Decrypt/GenerateDataKey
I01 info: target is IAM-auth — ACLs will be emitted as access-map.json for customer IaC to translate to IAM policies (tool does not apply IAM)

Exit codes

Code	Meaning
0	All checks passed (warnings are OK)
1	One or more blockers detected

execute

Run the migration from planned through drain_ready. Blocks until the data is caught up, then returns. License required.

kafka-backup migrate msk-kraft execute \
  --config <PATH> \
  [--migration-id <ID>] \
  [--journal-dir <PATH>] \
  [--force-restart]

Flag	Type	Required	Default	Description
`--config`	PATH	Yes	—	Path to migration config YAML
`--migration-id`	string	No	auto-generated	Resume a specific migration. If omitted, a new migration starts.
`--journal-dir`	PATH	No	—	Local directory for the migration journal. If omitted, journal is stored in S3.
`--force-restart`	flag	No	`false`	Allow re-running seed after a partial run. Accepts risk of duplicate records on target.

State transitions

planned → precheck → topology_copy → seed → tail → drain_ready

Example journal excerpt:

2026-04-25T06:15:07.512121Z topology_copy -> seed
2026-04-25T06:25:30.777840Z seed -> tail
2026-04-25T06:26:19.079610Z tail -> drain_ready drain ready: max_partition_lag=0 records_replayed=0 bytes_replayed=0

Exit codes

Code	Meaning
0	Migration reached `drain_ready` successfully
1	Migration failed (check logs and journal)

Example

kafka-backup migrate msk-kraft execute \
  --config migration.yaml \
  --journal-dir ./journal

# With debug logging
RUST_LOG=debug kafka-backup migrate msk-kraft execute \
  --config migration.yaml \
  --journal-dir ./journal

resume

Resume an in-flight migration from its last journal entry. License required.

kafka-backup migrate msk-kraft resume \
  --config <PATH> \
  --migration-id <ID> \
  [--journal-dir <PATH>]

Flag	Type	Required	Description
`--config`	PATH	Yes	Path to migration config YAML
`--migration-id`	string	Yes	ID of the migration to resume
`--journal-dir`	PATH	No	Directory where the journal is stored

Exit codes

Code	Meaning
0	Migration advanced or reached a terminal state
1	Resume failed
10	Migration is waiting on operator action (check stderr for `next_command`)

status

Show current state and live lag for a migration. License required.

kafka-backup migrate msk-kraft status \
  --config <PATH> \
  --migration-id <ID> \
  [--journal-dir <PATH>]

Flag	Type	Required	Description
`--config`	PATH	Yes	Path to migration config YAML
`--migration-id`	string	Yes	ID of the migration to query
`--journal-dir`	PATH	No	Directory where the journal is stored

Output

Prints migration state, per-partition lag, and operational notes.

cutover

Transition from drain_ready through producer freeze, sentinel publishing, offset translation, to awaiting_client_switch. License required.

kafka-backup migrate msk-kraft cutover \
  --config <PATH> \
  --migration-id <ID> \
  [--journal-dir <PATH>]

Flag	Type	Required	Description
`--config`	PATH	Yes	Path to migration config YAML
`--migration-id`	string	Yes	ID of the migration
`--journal-dir`	PATH	No	Directory where the journal is stored

What happens during cutover

Freezes producers (via webhook or TTY prompt)
Publishes sentinel records to every partition on source
Drains final records from source to target
Snapshots all consumer group offsets from source
Translates offsets using the offset map
Commits translated offsets on target
Verifies target log-start offsets have not advanced past the copied data
Logs READY_FOR_CLIENT_SWITCH

Example output:

2026-04-25T06:40:46.854037Z cutover -> awaiting_client_switch READY_FOR_CLIENT_SWITCH: groups_translated=0 offsets_committed=0 warnings=0

Exit codes

Code	Meaning
0	Cutover completed, ready for client switch
1	Cutover failed (producers are automatically unfrozen on failure)

cutover-ack

Acknowledge that clients have switched to the target cluster. Transitions from awaiting_client_switch to validating. License required.

kafka-backup migrate msk-kraft cutover-ack \
  --config <PATH> \
  --migration-id <ID> \
  [--journal-dir <PATH>]

Flag	Type	Required	Description
`--config`	PATH	Yes	Path to migration config YAML
`--migration-id`	string	Yes	ID of the migration
`--journal-dir`	PATH	No	Directory where the journal is stored

rollback

Abort the migration and mark it as rolled back. Only available before cutover completes. License required.

kafka-backup migrate msk-kraft rollback \
  --config <PATH> \
  --migration-id <ID> \
  [--journal-dir <PATH>]

Flag	Type	Required	Description
`--config`	PATH	Yes	Path to migration config YAML
`--migration-id`	string	Yes	ID of the migration
`--journal-dir`	PATH	No	Directory where the journal is stored

Available from states

planned, precheck, topology_copy, seed, tail, drain_ready

Not available from states

cutover, awaiting_client_switch, validating, finalized

What rollback does

Unfreezes producers (if frozen)
Marks migration as rolled_back in the journal
Uploads rollback report to evidence bucket
Does not delete topics or data on the target (manual cleanup)

finalize

Run the 5-check validation suite and produce the signed evidence bundle. Transitions from validating to finalized when validation passes. If a previous validation attempt found a repairable issue, finalize can be retried from failed after the repair. License required.

kafka-backup migrate msk-kraft finalize \
  --config <PATH> \
  --migration-id <ID> \
  [--journal-dir <PATH>]

Flag	Type	Required	Description
`--config`	PATH	Yes	Path to migration config YAML
`--migration-id`	string	Yes	ID of the migration
`--journal-dir`	PATH	No	Directory where the journal is stored

Validation checks

Topic parity — partition counts match
Counts & offsets — record counts within tolerance
Spot-check records — sampled records byte-equal
Sentinel presence — cutover markers landed
Consumer group reconciliation — translated offsets committed

Exit codes

Code	Meaning
0	Validation passed, evidence bundle uploaded
1	Validation failed (review the validation report)

Example successful verification output:

partitions_checked=306
target_behind_or_missing=0
earliest_partitions_checked=306
earliest_mismatches=0
latest_partitions_checked=306
latest_mismatches=0

Common Flags

These flags appear across most subcommands:

Flag	Description
`--config <PATH>`	Path to migration configuration YAML (always required)
`--migration-id <ID>`	Migration identifier (auto-generated by `execute`, required by others)
`--journal-dir <PATH>`	Local journal directory (if omitted, journal stored in S3)

Next Steps

Configuration Reference — config YAML details
Precheck Codes — precheck finding reference
Production Runbook — step-by-step guide

plan​

Output artifacts (--format all)​

Example​

precheck​

Output​

Exit codes​

execute​

State transitions​

Exit codes​

Example​

resume​

Exit codes​

status​

Output​

cutover​

What happens during cutover​

Exit codes​

cutover-ack​

rollback​

Available from states​

Not available from states​

What rollback does​

finalize​

Validation checks​

Exit codes​

Common Flags​

Next Steps​

plan

Output artifacts (`--format all`)

Example

precheck

Output

Exit codes

execute

State transitions

Exit codes

Example

resume

Exit codes

status

Output

cutover

What happens during cutover

Exit codes

cutover-ack

rollback

Available from states

Not available from states

What rollback does

finalize

Validation checks

Exit codes

Common Flags

Next Steps