docs: add Registry v2 migration runbook

[zhhray]

Summary by CodeRabbit

• Documentation
  • Added a comprehensive migration runbook for upgrading ACP image workloads from the legacy ACP Registry to Registry v2. Includes step-by-step procedures for both storage reuse and image copying scenarios, metadata backfill guidance, verification steps, and rollback procedures for operational safety.

[coderabbitai]

Walkthrough

New migration runbook documenting end-to-end procedures to migrate ACP image workloads from legacy ACP Registry to Registry v2, including discovery, inventory, two migration scenarios (filesystem/object storage reuse and image copy), shell-based metadata backfill implementation, verification, and rollback guidance.

Changes

ACP Registry v2 Migration Runbook

Layer / File(s)	Summary
Runbook overview and migration workspace setup docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx (lines 1–121)	Introduction, migration trigger, ac command workflow, maintenance windows, two scenario comparison table, required inputs matrix, workspace setup, kubeconfig and file path definitions, registry URL construction logic, and initial legacy vs modern registry discovery flow.
Image inventory gathering and authentication setup docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx (lines 121–196)	Procedures to export legacy image list and digest list from ac get images with command pipelines, deduplication guidance, and OCI registry credential setup via ac registry login for both legacy and target registries.
Metadata backfill shell implementation docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx (lines 200–358)	Complete shell-driven metadata backfill with helper functions to create ImageStream resources, compute/inspect digests and media types, build and apply ImageStreamMapping YAML, and a backfill_metadata driver with progress tracking and summary output.
Scenario A: Storage reuse (filesystem and object storage) docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx (lines 376–620)	Two approaches to reuse legacy backing storage: filesystem/PVC reuse with NFS CSI example (pause writes, create static PV/PVC, stop/restart Registry v2, await readiness) and object storage reuse (inspect legacy configuration, apply Registry v2 storage settings, validate pickup, backfill metadata from legacy registry).
Scenario B: Image copy between registries docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx (lines 620–722)	Mirror-based copy workflow covering mirror map generation, dry-run execution, real copy with error tolerance and concurrency limits, result summarization, modern mode switch, metadata backfill from target Registry v2, and safe rerun section with idempotent behavior.
Verification, cutover, and rollback docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx (lines 724–810)	Verification via sample image validation, ImageStreamTag inspection, digest presence checks, registry mode cutover, dry-run image management commands, rollback procedures (revert context to legacy), and enumeration of artifacts to retain for troubleshooting and migration continuation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A runbook hops through registries anew,
Storage reuse and mirrors both work true,
Metadata blooms in shells so fine,
The images dance in perfect line,
From legacy paths to Registry's design! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a new Registry v2 migration runbook documentation file. It is concise, specific, and clearly indicates the primary purpose of the changeset.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/registry-v2-migration-runbook

---

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 and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx (1)

458-464: 💤 Low value

Consider adding timeout protection to wait loops.

The while loops waiting for deployment removal could run indefinitely if the deployment doesn't get removed as expected. While acceptable for supervised operations where an operator can interrupt, adding a max iteration count or timestamp check would make the runbook more robust.

Example enhancement:

max_wait=60  # 5 minutes
elapsed=0
while ac get deployment image-registry -n "$MODERN_REGISTRY_NAMESPACE" >/dev/null 2>&1; do
  sleep 5
  elapsed=$((elapsed + 5))
  if [ $elapsed -ge $max_wait ]; then
    echo "Timeout waiting for image-registry deployment removal" >&2
    exit 1
  fi
done

This same pattern applies to similar wait loops at lines 518-524, 543-549, and 591-597.

🤖 Prompt for 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.

In `@docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx` around lines 458 -
464, The two wait loops that poll `ac get deployment image-registry -n
"$MODERN_REGISTRY_NAMESPACE"` and `ac get deployment image-api-server -n
"$MODERN_REGISTRY_NAMESPACE"` should include timeout protection so they don't
hang indefinitely: add a max-wait counter/timestamp (e.g., `max_wait` and
`elapsed` or `deadline`), increment elapsed on each sleep, and if the timeout is
reached print a clear error and exit non‑zero; apply the same pattern to the
other similar loops referenced (the blocks waiting on the same deployments at
the later locations) to fail fast and surface a clear message instead of looping
forever.

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

Nitpick comments:
In `@docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx`:
- Around line 458-464: The two wait loops that poll `ac get deployment
image-registry -n "$MODERN_REGISTRY_NAMESPACE"` and `ac get deployment
image-api-server -n "$MODERN_REGISTRY_NAMESPACE"` should include timeout
protection so they don't hang indefinitely: add a max-wait counter/timestamp
(e.g., `max_wait` and `elapsed` or `deadline`), increment elapsed on each sleep,
and if the timeout is reached print a clear error and exit non‑zero; apply the
same pattern to the other similar loops referenced (the blocks waiting on the
same deployments at the later locations) to fail fast and surface a clear
message instead of looping forever.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1aa028db-f4c3-4c98-9e4a-245b1c3258d0

📥 Commits

Reviewing files that changed from the base of the PR and between 4d9cdd9 and 90f54b8.

📒 Files selected for processing (1)

• docs/en/solutions/ACP_Registry_v2_Migration_Runbook.mdx