sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/clusterctl/commands/move.md (about)

     1  # clusterctl move
     2  
     3  The `clusterctl move` command allows to move the Cluster API objects defining workload clusters, like e.g. Cluster, Machines,
     4  MachineDeployments, etc. from one management cluster to another management cluster.
     5  
     6  <aside class="note warning">
     7  
     8  <h1> Warning </h1>
     9  
    10  Before running `clusterctl move`, the user should take care of preparing the target management cluster, including also installing
    11  all the required provider using `clusterctl init`.
    12  
    13  The version of the providers installed in the target management cluster should be at least the same version of the
    14  corresponding provider in the source cluster.
    15  
    16  </aside>
    17  
    18  You can use:
    19  
    20  ```bash
    21  clusterctl move --to-kubeconfig="path-to-target-kubeconfig.yaml"
    22  ```
    23  
    24  To move the Cluster API objects existing in the current namespace of the source management cluster; in case if you want
    25  to move the Cluster API objects defined in another namespace, you can use the `--namespace` flag.
    26  
    27  The discovery mechanism for determining the objects to be moved is in the [provider contract](../provider-contract.md#move)
    28  
    29  <aside class="note">
    30  
    31  <h1> Pause Reconciliation </h1>
    32  
    33  Before moving a `Cluster`, clusterctl sets the `Cluster.Spec.Paused` field to `true` stopping
    34  the controllers from reconciling the workload cluster _in the source management cluster_.
    35  clusterctl will wait until the `clusterctl.cluster.x-k8s.io/block-move` annotation is not
    36  present on any resource targeted by the move operation.
    37  
    38  The `Cluster` object created in the target management cluster instead will be actively reconciled as soon as the move
    39  process completes.
    40  
    41  </aside>
    42  
    43  <aside class="note warning">
    44  
    45  <h1> Warning </h1>
    46  
    47  `clusterctl move` has been designed and developed around the bootstrap use case described below, and currently this is the only
    48  use case verified by Cluster API E2E tests.
    49  
    50  If someone intends to use `clusterctl move` outside of this scenario, it's recommended to set up a custom validation pipeline of
    51  it before using the command on a production environment.
    52  
    53  Also, it is important to notice that move has not been designed for being used as a backup/restore solution and it has 
    54  several limitation for this scenario, like e.g. the implementation assumes the cluster must be stable
    55  while doing the move operation, and possible race conditions happening while the cluster is upgrading, scaling up, 
    56  remediating etc. has never been investigated nor addressed.
    57  
    58  In order to avoid further confusion about this point, `clusterctl backup` and `clusterctl restore` commands have been
    59  removed because they were built on top of `clusterctl move` logic and they were sharing the same limitations.
    60  User can use `clusterctl move --to-directory` and `clusterctl move --from-directory` instead; this will hopefully
    61  make it clear those operation have the same limitations of the move command.
    62  
    63  </aside>
    64  
    65  <aside class="note warning">
    66  
    67  <h1> Warning: Status subresource is never restored </h1>
    68  
    69  Every object's `Status` subresource, including every nested field (e.g. `Status.Conditions`), is never restored during a `move` operation. A `Status` subresource should never contain fields that cannot be recreated or derived from information in spec, metadata, or external systems.
    70  Provider implementers should not store non-ephemeral data in the `Status`. 
    71  `Status` should be able to be fully rebuilt by controllers by observing the current state of resources.
    72  
    73  </aside>
    74  
    75  ## Pivot
    76  
    77  Pivoting is a process for moving the provider components and declared Cluster API resources from a source management
    78  cluster to a target management cluster.
    79  
    80  This can now be achieved with the following procedure:
    81  
    82  1. Use `clusterctl init` to install the provider components into the target management cluster
    83  2. Use `clusterctl move` to move the cluster-api resources from a Source Management cluster to a Target Management cluster
    84  
    85  ## Bootstrap & Pivot
    86  
    87  The pivot process can be bounded with the creation of a temporary bootstrap cluster
    88  used to provision a target Management cluster.
    89  
    90  This can now be achieved with the following procedure:
    91  
    92  1. Create a temporary bootstrap cluster, e.g. using kind or minikube
    93  2. Use `clusterctl init` to install the provider components
    94  3. Use `clusterctl generate cluster ... | kubectl apply -f -` to provision a target management cluster
    95  4. Wait for the target management cluster to be up and running
    96  5. Get the kubeconfig for the new target management cluster
    97  6. Use `clusterctl init` with the new cluster's kubeconfig to install the provider components
    98  7. Use `clusterctl move` to move the Cluster API resources from the bootstrap cluster to the target management cluster
    99  8. Delete the bootstrap cluster
   100  
   101  > Note: It's required to have at least one worker node to schedule Cluster API workloads (i.e. controllers).
   102  > 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.
   103  
   104  ## Dry run
   105  
   106  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.