clusterctl move

The clusterctl move command allows to move the Cluster API objects defining workload clusters, like e.g. Cluster, Machines, MachineDeployments, etc. from one management cluster to another management cluster.

You can use:

clusterctl move --to-kubeconfig="path-to-target-kubeconfig.yaml"

To move the Cluster API objects existing in the current namespace of the source management cluster; in case if you want to move the Cluster API objects defined in another namespace, you can use the --namespace flag.

The discovery mechanism for determining the objects to be moved is in the provider contract

Warning

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.

Also, it is important to notice that move has not been designed for being used as a backup/restore solution and it has several limitation for this scenario, like e.g. the implementation assumes the cluster must be stable while doing the move operation, and possible race conditions happening while the cluster is upgrading, scaling up, remediating etc. has never been investigated nor addressed.

In order to avoid further confusion about this point, clusterctl backup and clusterctl restore commands have been removed because they were built on top of clusterctl move logic and they were sharing the same limitations. User can use clusterctl move --to-directory and clusterctl move --from-directory instead; this will hopefully make it clear those operation have the same limitations of the move command.

Pivot

Pivoting is a process for moving the provider components and declared Cluster API resources from a source management cluster to a target management cluster.

This can now be achieved with the following procedure:

Use clusterctl init to install the provider components into the target management cluster
Use clusterctl move to move the cluster-api resources from a Source Management cluster to a Target Management cluster

Bootstrap & Pivot

The pivot process can be bounded with the creation of a temporary bootstrap cluster used to provision a target Management cluster.

This can now be achieved with the following procedure:

Create a temporary bootstrap cluster, e.g. using kind or minikube
Use clusterctl init to install the provider components
Use clusterctl generate cluster ... | kubectl apply -f - to provision a target management cluster
Wait for the target management cluster to be up and running
Get the kubeconfig for the new target management cluster
Use clusterctl init with the new cluster’s kubeconfig to install the provider components
Use clusterctl move to move the Cluster API resources from the bootstrap cluster to the target management cluster
Delete the bootstrap cluster

Note: It’s required to have at least one worker node to schedule Cluster API workloads (i.e. controllers). A cluster with a single control plane node won’t be sufficient due to the NoSchedule taint. If a worker node isn’t available, clusterctl init will timeout.

Dry run

With --dry-run option you can dry-run the move action by only printing logs without taking any actual actions. Use log level verbosity -v to see different levels of information.

The Cluster API Book