📖 Docs/namespace renaming known limitation

[Tamar-Dinavetsky]

#732

Summary

Documents a known limitation: when a namespace is renamed during migration, Crane does not automatically update
references to the old namespace name in ClusterRoleBinding subjects or NetworkPolicy namespaceSelectors. Both
cases silently break after migration.

Changes

Added a warning in all relevant docs entry points:

• docs/commands/transform.md - in the Pass-Through Stages section (where manual renaming happens)
• docs/plugins.md - before the --optional-flags namespace-rename example
• docs/multistage-pipeline.md and docs/kustomize-multistage.md - in the Manual/Non-Plugin Stages section
• docs/pre-apply-validation-guide.md - in section 4 (References between resources)
• docs/resource-compatibility.md and docs/CRANE_COMPATIBILITY_MATRIX.md - inline in the relevant resource
  sections and pre-migration checklist

No code changes

This is documentation only. The limitation itself is a known issue and is not planned to be fixed at this time.

Summary by CodeRabbit

• Documentation
  • Added NetworkPolicy to the documented set of supported namespace-scoped networking resources.
  • Clarified that namespace renaming does not automatically update related ClusterRoleBinding service account references or NetworkPolicy namespace selectors.
  • Added migration and pre-apply checklist guidance requiring these references to be reviewed and updated manually.
  • Applied the warnings consistently across transformation, multistage, plugin, validation, and quickstart documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 78d4b8ea-1864-4c98-8908-aa08d66767d2

📥 Commits

Reviewing files that changed from the base of the PR and between 0c48dbf and 7828422.

📒 Files selected for processing (8)

• docs/CRANE_COMPATIBILITY_MATRIX.md
• docs/commands/transform.md
• docs/kustomize-multistage.md
• docs/multistage-pipeline.md
• docs/plugins.md
• docs/pre-apply-validation-guide.md
• docs/resource-compatibility.md
• docs/stateless-migration-quickstart.md

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

• docs/resource-compatibility.md
• docs/pre-apply-validation-guide.md
• docs/stateless-migration-quickstart.md
• docs/CRANE_COMPATIBILITY_MATRIX.md
• docs/kustomize-multistage.md
• docs/plugins.md
• docs/multistage-pipeline.md
• docs/commands/transform.md

---

📝 Walkthrough

Walkthrough

The documentation lists NetworkPolicy as a supported networking resource and explains that namespace renaming does not update related ClusterRoleBinding.subjects or NetworkPolicy.namespaceSelectors. Migration guides now require manual updates before applying resources.

Changes

Namespace Renaming Documentation

Layer / File(s)	Summary
Compatibility matrix and migration checklist docs/CRANE_COMPATIBILITY_MATRIX.md, docs/resource-compatibility.md	The compatibility matrices list NetworkPolicy as supported and document manual updates for ClusterRoleBinding.subjects and NetworkPolicy.namespaceSelectors.
Migration workflow warnings docs/commands/transform.md, docs/kustomize-multistage.md, docs/multistage-pipeline.md, docs/plugins.md, docs/pre-apply-validation-guide.md, docs/stateless-migration-quickstart.md	Migration guides warn that namespace renaming leaves related namespace references unchanged and require manual updates before applying resources.

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

Possibly related PRs

• migtools/crane#221: The compatibility guidance extends documentation introduced by this PR.
• migtools/crane#663: This PR documents namespace migration behavior for NetworkPolicy and ClusterRoleBinding references, while that PR adds related end-to-end coverage.

Suggested reviewers: aufi

🚥 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 clearly identifies the documentation change about the known namespace-renaming limitation.
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.

✨ 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: 1

🤖 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 `@docs/CRANE_COMPATIBILITY_MATRIX.md`:
- Around line 42-43: Update the affected documentation references to use the
Kubernetes API field name “namespaceSelector” and explain that selectors match
namespace labels, such as “kubernetes.io/metadata.name: old-ns”, rather than
pointing to bare namespace names. Apply this wording consistently in
docs/CRANE_COMPATIBILITY_MATRIX.md lines 42-43 and 76,
docs/resource-compatibility.md lines 42-43 and 76, docs/commands/transform.md
lines 265-270, docs/kustomize-multistage.md lines 482-483,
docs/multistage-pipeline.md lines 473-474, docs/plugins.md lines 78-79,
docs/pre-apply-validation-guide.md lines 92-93, and
docs/stateless-migration-quickstart.md lines 296-297.

🪄 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 Plus

Run ID: a3d51ee0-2985-4c0a-b50f-8143823a5c5a

📥 Commits

Reviewing files that changed from the base of the PR and between 7592906 and 0c48dbf.

📒 Files selected for processing (8)

• docs/CRANE_COMPATIBILITY_MATRIX.md
• docs/commands/transform.md
• docs/kustomize-multistage.md
• docs/multistage-pipeline.md
• docs/plugins.md
• docs/pre-apply-validation-guide.md
• docs/resource-compatibility.md
• docs/stateless-migration-quickstart.md

[Tamar-Dinavetsky]

/rfr