#6726·crossplane

Migration tooling for v1 --> v2 resources

Author: jbw976Created Aug 14, 2025Updated Sep 17, 2026
Labelsenhancementroadmapv2

Because of the v2 backward compatibility support of existing v1 workloads, we are mostly recommending right now that folks keep those as is when they upgrade to v2, and to start creating new resources using the v2 namespaced style.

  • Upgrade from v1.20 to v2.0 - your existing claims, XRs, etc should keep working the same way
  • Start using the new v2.0 style for new XRs and composed resources you create going forward

we have a documentation page for how to upgrade to v2, but it's missing the critical and challenging element of updating existing resources to start using v2 style XRs and namespaced resources: https://docs.crossplane.io/latest/guides/upgrade-to-crossplane-v2/

It would be nice to have automation for the full migration process of existing v1 workloads to v2 style namespaced scope. This would be tricky to cover all scenarios and work reliably, but it would definitely be a boost for more folks to adopt v2 for all of their workloads.

A very rough sketch from @negz for the process to migrate a v1 claim would be something like this:

  1. Author a new v2 variant of your existing XRD and Composition (don't try update existing ones in place)
  2. Update your existing Composition to set all MRs to deletionPolicy: Orphan (or the equivalent management policy)
  3. Delete the claim
  4. Replace the claim with a v2 XR that adopts the MRs that were orphaned in step 3

The last step is particularly challenging - your new XR is going to need to set the external name correctly for all composed MRs such that they adopt the existing ones, not replace them.

This roadmap item will be fleshed out more as design thinking progresses. Feel free to leave comments/feedback on what folks want to see in such an experience!