clusterctl add move cmd

Author: fabriziopandini

cmd/clusterctl/cmd/move.go

@@ -17,8 +17,11 @@ limitations under the License.
 package cmd
 
 import (
+	"fmt"
+
 	"github.com/pkg/errors"
 	"github.com/spf13/cobra"
+	"sigs.k8s.io/cluster-api/cmd/clusterctl/pkg/client"
 )
 
 type moveOptions struct {
@@ -59,5 +62,17 @@ func init() {
 }
 
 func runMove() error {
+	c, err := client.New(cfgFile)
+	if err != nil {
+		return err
+	}
+	fmt.Println("performing move...")
+	if err := c.Move(client.MoveOptions{
+		FromKubeconfig: mo.fromKubeconfig,
+		ToKubeconfig:   mo.toKubeconfig,
+		Namespace:      mo.namespace,
+	}); err != nil {
+		return err
+	}
 	return nil
 }

cmd/clusterctl/pkg/client/client.go

@@ -45,6 +45,13 @@ type GetClusterTemplateOptions struct {
 	WorkerMachineCount       int
 }
 
+// MoveOptions carries the options supported by move
+type MoveOptions struct {
+	FromKubeconfig string
+	ToKubeconfig   string
+	Namespace      string
+}
+
 // Client is exposes the clusterctl high-level client library
 type Client interface {
 	// GetProvidersConfig returns the list of providers configured for this instance of clusterctl.
@@ -58,6 +65,9 @@ type Client interface {
 
 	// GetClusterTemplate returns a workload cluster template.
 	GetClusterTemplate(options GetClusterTemplateOptions) (Template, error)
+
+	// Move moves all the Cluster API objects existing in a namespace (or from all the namespaces if empty) to a target management cluster
+	Move(options MoveOptions) error
 }
 
 // clusterctlClient implements Client.

cmd/clusterctl/pkg/client/client_test.go

@@ -78,6 +78,10 @@ func (f fakeClient) Init(options InitOptions) ([]Components, bool, error) {
 	return f.internalClient.Init(options)
 }
 
+func (f fakeClient) Move(options MoveOptions) error {
+	return f.internalClient.Move(options)
+}
+
 // newFakeClient returns a clusterctl client that allows to execute tests on a set of fake config, fake repositories and fake clusters.
 // you can use WithCluster and WithRepository to prepare for the test case.
 func newFakeClient(configClient config.Client) *fakeClient {

cmd/clusterctl/pkg/client/move.go

@@ -0,0 +1,47 @@
+/*
+Copyright 2020 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package client
+
+func (c *clusterctlClient) Move(options MoveOptions) error {
+	// Get the client for interacting with the source management cluster.
+	fromCluster, err := c.clusterClientFactory(options.FromKubeconfig)
+	if err != nil {
+		return err
+	}
+
+	// Ensures the custom resource definitions required by clusterctl are in place.
+	if err := fromCluster.ProviderInventory().EnsureCustomResourceDefinitions(); err != nil {
+		return err
+	}
+
+	// Get the client for interacting with the target management cluster.
+	toCluster, err := c.clusterClientFactory(options.ToKubeconfig)
+	if err != nil {
+		return err
+	}
+
+	// Ensures the custom resource definitions required by clusterctl are in place
+	if err := toCluster.ProviderInventory().EnsureCustomResourceDefinitions(); err != nil {
+		return err
+	}
+
+	if err := fromCluster.ObjectMover().Move(options.Namespace, toCluster); err != nil {
+		return err
+	}
+
+	return nil
+}

docs/book/src/clusterctl/commands/move.md

@@ -1 +1,36 @@
 # 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.
+
+<aside class="note warning">
+
+<h1> Warning </h1>
+
+Before running `clusterctl move`, the user should take care of preparing the target management cluster, including also installing
+all the required provider using `clusterctl init`.
+ 
+The version of the providers installed in the target management cluster should be at least the same version of the
+corresponding provider in the source cluster.
+
+</aside>
+
+You can use:
+
+```shell
+clusterctl move --to-kubeconfig="path-to-target-kubeconfig.yaml"
+```
+
+To move all the Cluster API objects objects in the source management cluster; in case if you want to move only the
+Cluster API objects defined in a specific namespace, you can use the `--namespace` flag.
+
+<aside class="note">
+
+<h1> Pause Reconciliation </h1>
+
+Before moving a `Cluster`, clusterctl sets the `Cluster.Spec.Paused` field to `true` stopping
+the controllers to reconcile the workload cluster _in the source management cluster_.
+
+The `Cluster` object created in the target management cluster instead will be actively reconciled. 
+
+</aside>

docs/book/src/clusterctl/provider-contract.md

@@ -163,6 +163,25 @@ Templates writers should use the common variables to ensure consistency across p
 Additionally, value of the command argument to `clusterctl config cluster <cluster-name>` (`<cluster-name>` in this case), will 
 be applied to every occurrence of the `${ CLUSTER_NAME }` variable.
 
+## OwnerReferences chain
+
+Each provider is responsible to ensure that all the providers resources (like e.g. `VSphereCluster`, `VSphereMachine`, `VSphereVM` etc. 
+for the `vsphere` provider) MUST have a `Metadata.OwnerReferences` entry that links directly or indirectly to a `Cluster` object.
+
+Please note that all the provider specific resources that are referenced by the Cluster API core objects will get the `OwnerReference`
+sets by the Cluster API core controllers, e.g.:
+
+- The Cluster controller ensures that all the objects reference in `Cluster.Spec.InfrastructureRef` get an `OwnerReference` 
+  that links directly to the corresponding `Cluster`.
+- The Machine controller ensures that all the objects reference in `Machine.Spec.InfrastructureRef` get an `OwnerReference` 
+  that links to the corresponding `Machine`, and the `Machine` is linked to the `Cluster` through its own `OwnerReference` chain.  
+
+That means that, practically speaking, the provider implementers are responsibility is to ensure that the `OwnerReference`
+is set only for objects that are not directly referenced by Cluster API core objects, e.g.:
+
+- All the `VSphereVM` should get an `OwnerReference` that links to the corresponding `VSphereMachine`, and the `VSphereMachine`
+  is linked to the `Cluster` through its own `OwnerReference` chain.
+
 ## Additional notes
 
 ### Components YAML transformations
@@ -199,10 +218,25 @@ If, for any reason, the provider authors/YAML designers decide not to comply wit
 The provider authors/YAML designers should be aware that it is their responsibility to ensure the proper
 functioning of all the `clusterctl` features both in single tenancy or multi-tenancy scenarios and/or document known limitations.
 
-### Move constraints
+### Move 
 
-WIP
+Provider authors should be aware that `clusterctl move` command implement a discovery mechanism that considers:
+
+* All the objects of Kind defined in one of the CRDs installed by clusterctl using `clusterctl init`. 
+* `Serets` and `ConfigMaps` objects.
+* the `OwnerReference` chain of the above objects.
+
+`clusterctl move` does NOT consider any objects:
 
+* Not included in the set of objects defined above.
+* Included in the set of objects defined above, but not directly or indirectly to a `Cluster` object through the `OwnerReference` chain.
+ 
+If moving some of excluded object is required, the provider authors should create documentation describing the
+the exact move sequence to be executed by the user.
+
+Additionally, provider authors should be aware that `clusterctl move` assumes all the provider's Controllers respect the
+`Cluster.Spec.Paused` field introduced in the v1alpha3 Cluster API specification. 
+ 
 ### Adopt
 
 WIP