diff --git a/docs/book/src/clusterctl/commands/alpha-topology-plan.md b/docs/book/src/clusterctl/commands/alpha-topology-plan.md index cc5dd5d779ac..6eabadf3073f 100644 --- a/docs/book/src/clusterctl/commands/alpha-topology-plan.md +++ b/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. + + + + + +## 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. + + + +### `--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" +```