Skip to content

Commit b6a44fa

Browse files
author
Yuvaraj Kakaraparthi
committed
topology plan command doc
1 parent 18c7ec8 commit b6a44fa

File tree

1 file changed

+170
-1
lines changed

1 file changed

+170
-1
lines changed

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

Lines changed: 170 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,172 @@
11
# clusterctl alpha topology plan
22

3-
**Under Construction**
3+
The `clusterctl alpha topology plan` command can be used to dry run the topology reconciler using an input file.
4+
5+
The input file could contain a new/modified Cluster, a new/modified ClusterClass and/or new/modified templates.
6+
7+
The dry run output would list the Clusters and ClusterClasses that would be affected by the input. The output also lists the
8+
objects that will be created, updated and deleted of a target cluster.
9+
10+
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
11+
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
12+
in the real cluster as needed.
13+
14+
```shell
15+
clusterctl alpha topology plan -f input.yaml -o output/
16+
```
17+
18+
> 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
19+
> 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
20+
> in the management cluster as needed.
21+
22+
## Dry run
23+
24+
The operation is composed of the following steps:
25+
* Set the namespace on objects in the input with missing namespace.
26+
* Run the Defaulting and Validation webhooks on the Cluster and ClusterClass objects in the input.
27+
* Dry run the topology reconciler on the target cluster.
28+
* Capture all changes observed during reconciliation.
29+
30+
<aside class="note">
31+
32+
<h1>Set missing namespace</h1>
33+
34+
The namespace used for objects with missing namespace follows this precedence order:
35+
* Value passed using `--namespace`
36+
* Current namespace defined in kubeconfig
37+
* Value `default`
38+
39+
</aside>
40+
41+
<aside class="note warning">
42+
43+
<h1>Defaulting and Validation of objects</h1>
44+
45+
Defaulting and validation is only performed on the Cluster and ClusterClass objects in the input. Objects of all other kinds in the input should
46+
be fully valid and any required default values should be set. Missing values will not be defaulted.
47+
48+
> **Note on Validation**: If the command is used with a real management cluster, objects from the management cluster will be used to perform
49+
> `ValidateUpdate` appropriately.
50+
51+
</aside>
52+
53+
## Input
54+
55+
### `--file`, `-f` (REQUIRED)
56+
57+
The input file with the target changes.
58+
The objects in the input should follow these rules:
59+
* All the objects in the input should belong to the same namespace.
60+
* Should not have multiple Clusters.
61+
* Should not have multiple ClusterClasses.
62+
63+
<aside class="note warning">
64+
65+
<h1>Object namespaces</h1>
66+
67+
If some of the objects have a defined namespace and some do not, the objects are considered as belonging to different namespaces. The input
68+
will be considered as invalid.
69+
70+
</aside>
71+
72+
### `--output-directory`, `-o` (REQUIRED)
73+
74+
Information about the objects that are created and updated during dry run are written to this directory.
75+
76+
### `--cluster`, `-c` (Optional)
77+
78+
When multiple clusters are affected by the input, `--cluster` can be used to specify a target cluster.
79+
80+
If only one cluster is affected or if a Cluster is in the input it defaults as the target cluster.
81+
82+
### `--namespace`, `-n` (Optional)
83+
84+
Namespace used for objects with missing namespaces in the input.
85+
86+
## Example use cases
87+
88+
### Creating a new Cluster using a new ClusterClass
89+
90+
The command can be used to dry run creating a new Cluster along with a new ClusterClass.
91+
```shell
92+
clusterctl alpha topology plan -f new-cluster-and-class.yaml -o output/
93+
```
94+
Produces an output similar to this:
95+
```shell
96+
Detected a cluster with Cluster API installed. Will use it to fetch missing objects.
97+
The following ClusterClasses will be affected by the changes:
98+
＊ default/new-cluster-class
99+
100+
The following Clusters will be affected by the changes:
101+
＊ default/new-cluster
102+
103+
Changes for Cluster "default/new-cluster":
104+
105+
NAMESPACE KIND NAME ACTION
106+
default DockerCluster new-cluster-jfjcs created
107+
default DockerMachineTemplate new-cluster-control-plane-6rkg8 created
108+
default DockerMachineTemplate new-cluster-md-0-infra-4nv62 created
109+
default DockerMachineTemplate new-cluster-md-1-infra-dcfnj created
110+
default KubeadmConfigTemplate new-cluster-md-0-bootstrap-kk24t created
111+
default KubeadmConfigTemplate new-cluster-md-1-bootstrap-k6xw4 created
112+
default KubeadmControlPlane new-cluster-dtdvx created
113+
default MachineDeployment new-cluster-md-0-z9v9f created
114+
default MachineDeployment new-cluster-md-1-xjtg2 created
115+
default Secret new-cluster-shim created
116+
default Cluster new-cluster modified
117+
118+
Created objects are written to directory "output/created"
119+
Modified objects are written to directory "output/modified"
120+
121+
```
122+
123+
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
124+
files are written to disk:
125+
* Original object
126+
* Final object
127+
* JSON patch between the original and the final object
128+
* Diff of the original and final objects
129+
130+
The contents fn the output directory is similar to this:
131+
```
132+
output
133+
├── created
134+
│ ├── DockerCluster_default_new-cluster-jfjcs.yaml
135+
│ ├── DockerMachineTemplate_default_new-cluster-control-plane-6rkg8.yaml
136+
│ ├── DockerMachineTemplate_default_new-cluster-md-0-infra-4nv62.yaml
137+
│ ├── DockerMachineTemplate_default_new-cluster-md-1-infra-dcfnj.yaml
138+
│ ├── KubeadmConfigTemplate_default_new-cluster-md-0-bootstrap-kk24t.yaml
139+
│ ├── KubeadmConfigTemplate_default_new-cluster-md-1-bootstrap-k6xw4.yaml
140+
│ ├── KubeadmControlPlane_default_new-cluster-dtdvx.yaml
141+
│ ├── MachineDeployment_default_new-cluster-md-0-z9v9f.yaml
142+
│ ├── MachineDeployment_default_new-cluster-md-1-xjtg2.yaml
143+
│ └── Secret_default_new-cluster-shim.yaml
144+
└── modified
145+
├── Cluster_default_new-cluster.diff
146+
├── Cluster_default_new-cluster.jsonpatch
147+
├── Cluster_default_new-cluster.modified.yaml
148+
└── Cluster_default_new-cluster.original.yaml
149+
```
150+
151+
### Modifying a ClusterClass that affects multiple Clusters
152+
153+
```shell
154+
clusterctl alpha topology plan -f modified-first-cluster-class.yaml -o output/
155+
```
156+
When multiple clusters are affected, only the list of Clusters and ClusterClasses is presented.
157+
```shell
158+
Detected a cluster with Cluster API installed. Will use it to fetch missing objects.
159+
The following ClusterClasses will be affected by the changes:
160+
＊ default/first-cluster-class
161+
162+
The following Clusters will be affected by the changes:
163+
＊ default/first-cluster
164+
＊ default/second-cluster
165+
166+
No target cluster identified. Use --cluster to specify a target cluster to get detailed changes.
167+
```
168+
169+
To get the full list of changes for the "first-cluster":
170+
```shell
171+
clusterctl alpha topology plan -f modified-first-cluster-class.yaml -o output/ -c "first-cluster"
172+
```

0 commit comments

Comments
 (0)