clusterctl move fails when migrating from v1beta1 to v1beta2 management cluster

[LuckyChen666]

What would you like to be added (User Story)?

Support Cross-Version clusterctl move Between v1beta1 and v1beta2 Management Clusters

Detailed Description

What happened?

When attempting to migrate a workload cluster from a v1.10 (v1beta1) management cluster to a v1.11 (v1beta2) management cluster using clusterctl move, the operation fails with:

Error: this version of clusterctl could be used only with "v1beta2" management clusters, "v1beta1" detected

What did you expect to happen?

clusterctl move should support migration between different API versions, especially during version upgrades from v1beta1 to v1beta2, or provide clear upgrade path documentation.

How to reproduce it?

clusterctl move \
  --kubeconfig ~/migration/mccdev03-capi/mccdev03-capi.config \
  --to-kubeconfig ~/migration/golden-odev-1/golden-odev-1.config \
  --namespace migrate-test \
  --v=5

Environment:

• Source management cluster: CAPI v1.10 (v1beta1)
• Target management cluster: CAPI v1.11 (v1beta2)
• clusterctl version: v1.11.3

Anything else you would like to add?

1. Should clusterctl move support cross-version migration?
2. Given that an in-place production upgrade of the source management cluster to v1.11 is too risky, is an officially supported cross-version move workflow planned or documented?
3. If not, what's the recommended upgrade path? Should we:
   • First upgrade the source management cluster to v1.11
   • Then perform the move operation
   • Or use alternative migration strategies?

Label(s) to be applied

/kind feature
One or more /area label. See https://github.com/kubernetes-sigs/cluster-api/labels?q=area for the list of labels.

[k8s-ci-robot]

This issue is currently awaiting triage.

If CAPI contributors determine this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[fabriziopandini]

clusterctl move should support migration between different API versions, especially during version upgrades from v1beta1 to v1beta2, or provide clear upgrade path documentation.

clusterctl move has not been designed to handle migration nor upgrade paths, and limitations are documented in https://cluster-api.sigs.k8s.io/clusterctl/commands/move#warning-1

The only effort planned in this area is #12843, but I doubt it is what you are looking for and several limitation applies (PTAL the corresponding issue).

[LuckyChen666]

The only effort planned in this area is #12843, but I doubt it is what you are looking for and several limitation applies (PTAL the corresponding issue).

A production workload cluster is currently running on Management Cluster A (v1.10).
To upgrade the management cluster to v1.11 without impacting the existing workload cluster, a new Management Cluster B (v1.11) is planned to be created.
#12843 is necessary for us to migrate workload cluster to mgnt Cluster B.
It seems that the clusterctl move does not support cross-version migration.

[sbueringer]

It seems that the clusterctl move does not support cross-version migration.

Exactly

To quote the documentation that Fabrizio linked:

clusterctl move has been designed and developed around the bootstrap use case described below, and currently this is the only use case verified by Cluster API E2E tests.
If someone intends to use clusterctl move outside of this scenario, it’s recommended to set up a custom validation pipeline of it before using the command on a production environment.

[sbueringer]

To upgrade the management cluster to v1.11 without impacting the existing workload cluster, a new Management Cluster B (v1.11) is planned to be created.

What sort of impact do you expect? We've been upgrading CAPI mgmt clusters for a long time without impact on workload clusters.