topology plan command doc

docs/book/src/clusterctl/commands/alpha-topology-plan.md

@@ -1,3 +1,172 @@
 # clusterctl alpha topology plan
 
-**Under Construction**
+The `clusterctl alpha topology plan` command can be used to dry run the topology reconciler using an input file.
+
+The input file could contain a new/modified Cluster, a new/modified ClusterClass and/or new/modified templates.
+
+The dry run output would list the Clusters and ClusterClasses that would be affected by the input. The output also lists the
+objects that will be created, updated and deleted of a target cluster.
+
+This command can be used with and without a management cluster. In case the command is used without a management cluster the input should have
+all the objects needed to perform the dry run. In case the command is run with a management cluster the dry run operation will look for objects 
+in the real cluster as needed.
+
+```shell
+clusterctl alpha topology plan -f input.yaml -o output/
+```
+
+> Note: This command can be used with or without a management cluster. In case the command is used without a management cluster the input should have
+> all the objects needed to perform the dry run. In case the command is run with a management cluster the dry run operation will look for objects 
+> in the management cluster as needed.
+
+## Dry run
+
+The operation is composed of the following steps:
+* Set the namespace on objects in the input with missing namespace.
+* Run the Defaulting and Validation webhooks on the Cluster and ClusterClass objects in the input.
+* Dry run the topology reconciler on the target cluster.
+* Capture all changes observed during reconciliation.
+
+<aside class="note">
+
+<h1>Set missing namespace</h1>
+
+The namespace used for objects with missing namespace follows this precedence order:
+* Value passed using `--namespace`
+* Current namespace defined in kubeconfig
+* Value `default`
+
+</aside>
+
+<aside class="note warning">
+
+<h1>Defaulting and Validation of objects</h1>
+
+Defaulting and validation is only performed on the Cluster and ClusterClass objects in the input. Objects of all other kinds in the input should 
+be fully valid and any required default values should be set. Missing values will not be defaulted.
+
+> **Note on Validation**: If the command is used with a real management cluster, objects from the management cluster will be used to perform 
+> `ValidateUpdate` appropriately.
+
+</aside>
+
+## Input
+
+### `--file`, `-f` (REQUIRED)
+
+The input file with the target changes.
+The objects in the input should follow these rules:
+* All the objects in the input should belong to the same namespace.
+* Should not have multiple Clusters.
+* Should not have multiple ClusterClasses.
+
+<aside class="note warning">
+
+<h1>Object namespaces</h1>
+
+If some of the objects have a defined namespace and some do not, the objects are considered as belonging to different namespaces. The input
+will be considered as invalid.
+
+</aside>
+
+### `--output-directory`, `-o` (REQUIRED)
+
+Information about the objects that are created and updated during dry run are written to this directory.
+
+### `--cluster`, `-c` (Optional)
+
+When multiple clusters are affected by the input, `--cluster` can be used to specify a target cluster. 
+
+If only one cluster is affected or if a Cluster is in the input it defaults as the target cluster. 
+
+### `--namespace`, `-n` (Optional)
+
+Namespace used for objects with missing namespaces in the input.
+
+## Example use cases
+
+### Creating a new Cluster using a new ClusterClass
+
+The command can be used to dry run creating a new Cluster along with a new ClusterClass.
+```shell
+clusterctl alpha topology plan -f new-cluster-and-class.yaml -o output/
+```
+Produces an output similar to this:
+```shell
+Detected a cluster with Cluster API installed. Will use it to fetch missing objects.
+The following ClusterClasses will be affected by the changes:
+ ＊ default/new-cluster-class
+
+The following Clusters will be affected by the changes:
+ ＊ default/new-cluster
+
+Changes for Cluster "default/new-cluster": 
+
+  NAMESPACE  KIND                   NAME                              ACTION    
+  default    DockerCluster          new-cluster-jfjcs                 created   
+  default    DockerMachineTemplate  new-cluster-control-plane-6rkg8   created   
+  default    DockerMachineTemplate  new-cluster-md-0-infra-4nv62      created   
+  default    DockerMachineTemplate  new-cluster-md-1-infra-dcfnj      created   
+  default    KubeadmConfigTemplate  new-cluster-md-0-bootstrap-kk24t  created   
+  default    KubeadmConfigTemplate  new-cluster-md-1-bootstrap-k6xw4  created   
+  default    KubeadmControlPlane    new-cluster-dtdvx                 created   
+  default    MachineDeployment      new-cluster-md-0-z9v9f            created   
+  default    MachineDeployment      new-cluster-md-1-xjtg2            created   
+  default    Secret                 new-cluster-shim                  created   
+  default    Cluster                new-cluster                       modified  
+
+Created objects are written to directory "output/created"
+Modified objects are written to directory "output/modified"
+
+```
+
+The final state of objects that are created and updated are written to disk under the `output` folder. For objects that are modified the following
+files are written to disk:
+* Original object
+* Final object
+* JSON patch between the original and the final object
+* Diff of the original and final objects
+
+The contents fn the output directory is similar to this:
+```
+output
+├── created
+│   ├── DockerCluster_default_new-cluster-jfjcs.yaml
+│   ├── DockerMachineTemplate_default_new-cluster-control-plane-6rkg8.yaml
+│   ├── DockerMachineTemplate_default_new-cluster-md-0-infra-4nv62.yaml
+│   ├── DockerMachineTemplate_default_new-cluster-md-1-infra-dcfnj.yaml
+│   ├── KubeadmConfigTemplate_default_new-cluster-md-0-bootstrap-kk24t.yaml
+│   ├── KubeadmConfigTemplate_default_new-cluster-md-1-bootstrap-k6xw4.yaml
+│   ├── KubeadmControlPlane_default_new-cluster-dtdvx.yaml
+│   ├── MachineDeployment_default_new-cluster-md-0-z9v9f.yaml
+│   ├── MachineDeployment_default_new-cluster-md-1-xjtg2.yaml
+│   └── Secret_default_new-cluster-shim.yaml
+└── modified
+    ├── Cluster_default_new-cluster.diff
+    ├── Cluster_default_new-cluster.jsonpatch
+    ├── Cluster_default_new-cluster.modified.yaml
+    └── Cluster_default_new-cluster.original.yaml
+```
+
+### Modifying a ClusterClass that affects multiple Clusters
+
+```shell
+clusterctl alpha topology plan -f modified-first-cluster-class.yaml -o output/
+```
+When multiple clusters are affected, only the list of Clusters and ClusterClasses is presented.
+```shell
+Detected a cluster with Cluster API installed. Will use it to fetch missing objects.
+The following ClusterClasses will be affected by the changes:
+ ＊ default/first-cluster-class
+
+The following Clusters will be affected by the changes:
+ ＊ default/first-cluster
+ ＊ default/second-cluster
+
+No target cluster identified. Use --cluster to specify a target cluster to get detailed changes.
+```
+
+To get the full list of changes for the "first-cluster":
+```shell
+clusterctl alpha topology plan -f modified-first-cluster-class.yaml -o output/ -c "first-cluster"
+```