MTV-5895: Document warm migration performance impact for storage copy offload

[RichardHoch]

Resolves https://redhat.atlassian.net/browse/MTV-5895 by adding a new section to the documentation, "Disk write activity and warm migration performance for storage copy offload" to the documentation.

Preview:
https://forklift-documentation-git-fork-ri-4862f6-yaacov-8047s-projects.vercel.app/downstream/documentation/doc-Planning_your_migration/master.html#con_sco-warm-migration-performance_vmware

Summary

• Adds new concept module con_sco-warm-migration-performance.adoc documenting how high disk write activity during warm storage copy offload migrations can increase downtime and negate the time savings of warm migration
• Includes guidance on measuring storage array performance using a test VM with varied write speeds before migrating production VMs
• Inserts the module into assembly_planning-migration-vmware.adoc after the storage copy offload planning steps

Test plan

• Verify AsciiDoc builds without errors
• Verify module placement in the assembly renders correctly in the TOC
• Review content for technical accuracy with SME

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added guidance for evaluating warm migration performance with storage copy offload.
  • Explained how disk write activity and Changed Block Tracking affect migration time.
  • Included recommendations for measuring storage performance and identifying when cold migration may be faster.
  • Clarified that warm migration completes successfully even when write rates reduce its downtime advantage.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
forklift-documentation	Ready	Preview	Aug 5, 2026 11:16am

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a VMware vSphere migration planning module that explains how disk write rates affect warm migration performance and describes how to measure the threshold for selecting warm migration.

Changes

Warm migration performance documentation

Layer / File(s)	Summary
Add and assemble performance guidance documentation/modules/con_sco-warm-migration-performance.adoc, documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc	Documents CBT delta growth, disk write rates, switchover downtime, and storage array measurement. Includes the module in the VMware migration planning assembly.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• kubev2v/forklift-documentation#960: Updates related warm-migration and storage copy offload documentation.

Suggested reviewers: anarnold97

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change and its focus on warm migration performance for storage copy offload.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@documentation/modules/con_sco-warm-migration-performance.adoc`:
- Around line 10-14: Revise the warm-migration guidance to prioritize measuring
final switchover downtime against the cold-migration baseline, rather than using
cumulative or total copy time as the primary decision metric. Retain total
elapsed migration time as a secondary metric, and clarify that warm migration
may take longer overall while still providing the intended downtime reduction.
- Around line 21-24: Revise the [NOTE] in the warm migration performance
documentation to avoid claiming success at any write rate. Limit the statement
to the tested workload range, or state only that high disk write activity can
reduce or eliminate the expected downtime benefit while preserving the rest of
the note’s guidance.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2d04fd45-455f-419c-b894-f2e4b4d8f5a3

📥 Commits

Reviewing files that changed from the base of the PR and between 4c7a4da and a926e7a.

📒 Files selected for processing (2)

• documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc
• documentation/modules/con_sco-warm-migration-performance.adoc

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[RichardHoch]

@mrnold @mnecas Please review this PR.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@documentation/modules/con_sco-warm-migration-performance.adoc`:
- Around line 28-30: Add an explicit placeholder section or TODO immediately
after the generic storage-array performance testing procedure in the warm
migration module, indicating that a future single-VM test example will be added.
- Around line 28-30: Update the warm migration threshold guidance in this
section to document the VM write pattern used during testing, including whether
writes target existing or new blocks. Clarify that the measured threshold
applies only to production VMs with comparable write patterns, rather than
treating it as a storage-array-wide write-rate limit.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2d73e0d1-71c8-40cd-913b-379704e16d30

📥 Commits

Reviewing files that changed from the base of the PR and between e3bbec8 and abfef63.

📒 Files selected for processing (2)

• documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc
• documentation/modules/con_sco-warm-migration-performance.adoc

🚧 Files skipped from review as they are similar to previous changes (1)

• documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc

[RichardHoch]

@mnecas Is it OK to use numbers here? The rates differ by 2 orders of magnitude.

[mrnold]

I think this is okay, the line before this specifically says these are just examples. The order of magnitude difference here shows two extremes so that one saves downtime and the other doesn't.