You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md
+182-4Lines changed: 182 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,19 @@
1
1
# Operating a managed Cluster
2
2
3
-
## Upgrade the Cluster
3
+
The `spec.topology` field added to the Cluster object as part of ClusterClass allows changes made on the Cluster to be propagated across all relevant objects. This means the Cluster object can be used as a single point of control for making changes to objects that are part of the Cluster, including the ControlPlane and MachineDeployments.
4
4
5
-
The `spec.topology` field added to the Cluster object as part of ClusterClass allows changes made on the Cluster to be propagated across all relevant objects. This turns a Kubernetes cluster upgrade into a one-touch operation.
6
-
Let's assume we have created a CAPD cluster with ClusterClass and Kubernetes v1.21.2 (as documented in the [Quick Start guide]). Looking at the cluster, the version of the control plane and the MachineDeployments is v1.21.2.
5
+
A managed Cluster can be used to:
6
+
*[Upgrade a Cluster](#upgrade-a-cluster)
7
+
*[Scale a ControlPlane](#scale-a-controlplane)
8
+
*[Scale a MachineDeployment](#scale-a-machinedeployment)
9
+
*[Add a MachineDeployment](#add-a-machinedeployment)
10
+
*[Use variables in a Cluster](#use-variables)
11
+
*[Rebase a Cluster to a different ClusterClass](#rebase-a-cluster)
12
+
13
+
14
+
## Upgrade a Cluster
15
+
Using a managed topology the operation to upgrade a Kubernetes cluster is a one-touch operation.
16
+
Let's assume we have created a CAPD cluster with ClusterClass and specified Kubernetes v1.21.2 (as documented in the [Quick Start guide]). Specifying the version is done when running `clusterctl generate cluster`. Looking at the cluster, the version of the control plane and the MachineDeployments is v1.21.2.
7
17
8
18
```bash
9
19
> kubectl get kubeadmcontrolplane,machinedeployments
The patch will make the following change to the Cluster yaml:
37
+
```diff
38
+
spec:
39
+
topology:
40
+
class: quick-start
41
+
+ version: v1.22.0
42
+
- version: v1.21.2
43
+
```
44
+
26
45
**Important Note**: A +2 minor Kubernetes version upgrade is not allowed in Cluster Topologies. This is to align with existing control plane providers, like KubeadmControlPlane provider, that limit a +2 minor version upgrade. Example: Upgrading from `1.21.2` to `1.23.0` is not allowed.
27
46
28
47
The upgrade will take some time to roll out as it will take place machine by machine with older versions of the machines only being removed after healthy newer versions come online.
When using a managed topology scaling of MachineDeployments, both up and down, should be done through the Cluster topology.
67
+
68
+
Assume we have created a CAPD cluster with ClusterClass and Kubernetes v1.23.3 (as documented in the [Quick Start guide]). Initially we should have a MachineDeployment with 3 replicas. Running
69
+
```bash
70
+
kubectl get machinedeployments
71
+
```
72
+
Will give us:
73
+
```bash
74
+
NAME CLUSTER REPLICAS READY UPDATED UNAVAILABLE PHASE AGE VERSION
We can scale up or down this MachineDeployment through the Cluster object by changing the replicas field under `/spec/topology/workers/machineDeployments/0/replicas`
78
+
The `0` in the path refers to the position of the target MachineDeployment in the list of our Cluster topology. As we only have one MachineDeployment we're targeting the first item in the list under `/spec/topology/workers/machineDeployments/`.
As well as scaling a MachineDeployment, Cluster operators can edit the labels and annotations applied to a running MachineDeployment using the Cluster topology as a single point of control.
105
+
106
+
## Add a MachineDeployment
107
+
MachineDeployments in a managed Cluster are defined in the Cluster's topology. Cluster operators can add a MachineDeployment to a living Cluster by adding it to the `cluster.spec.topology.workers.machineDeployments` field.
108
+
109
+
Assume we have created a CAPD cluster with ClusterClass and Kubernetes v1.23.3 (as documented in the [Quick Start guide]). Initially we should have a single MachineDeployment with 3 replicas. Running
110
+
```bash
111
+
kubectl get machinedeployments
112
+
```
113
+
114
+
Will give us:
115
+
```bash
116
+
NAME CLUSTER REPLICAS READY UPDATED UNAVAILABLE PHASE AGE VERSION
A new MachineDeployment can be added to the Cluster by adding a new MachineDeployment spec under `/spec/topology/workers/machineDeployments/`. To do so we can patch our Cluster with:
Our second deployment uses the same underlying MachineDeployment class `default-worker` as our initial deployment. In this case they will both have exactly the same underlying machine templates. In order to modify the templates MachineDeployments are based on take a look at [Changing a ClusterClass].
148
+
149
+
A similar process as that described here - removing the MachineDeployment from `cluster.spec.topology.workers.machineDeployments` - can be used to delete a running MachineDeployment from an active Cluster.
150
+
151
+
## Scale a ControlPlane
152
+
When using a managed topology scaling of ControlPlane Machines, where the Cluster is using a topology that includes ControlPlane MachineInfrastructure, should be done through the Cluster topology.
153
+
154
+
This is done by changing the ControlPlane replicas field at `/spec/topology/controlPlane/replica` in the Cluster object. The command is:
This patch will make the below changes on the Cluster yaml:
161
+
```diff
162
+
spec:
163
+
topology:
164
+
controlPlane:
165
+
metadata: {}
166
+
+ replicas: 1
167
+
- replicas: 3
168
+
```
169
+
170
+
As well as scaling a ControlPlane, Cluster operators can edit the labels and annotations applied to a running ControlPlane using the Cluster topology as a single point of control.
171
+
172
+
173
+
## Use variables
174
+
A ClusterClass can use variables and patches in order to allow flexible customization of Clusters derived from a ClusterClass. Variable definition allows two or more Cluster topologies derived from the same ClusterClass to have different specs, with the differences controlled by variables in the Cluster topology.
175
+
176
+
Assume we have created a CAPD cluster with ClusterClass and Kubernetes v1.23.3 (as documented in the [Quick Start guide]). Our Cluster has a variable `etcdImageTag` as defined in the ClusterClass. The variable is not set on our Cluster. Some variables, depending on their definition in a ClusterClass, may need to be specified by the Cluster operator for every Cluster created using a given ClusterClass.
177
+
178
+
In order to specify the value of a variable all we have to do is set the value in the Cluster topology.
179
+
180
+
We can see the current unset variable with:
181
+
```bash
182
+
kubectl get cluster capi-quickstart -o jsonpath='{.spec.topology.variables[1]}'
183
+
184
+
```
185
+
Which will return something like:
186
+
```bash
187
+
{"name":"etcdImageTag","value":""}
188
+
```
189
+
190
+
In order to run a different version of etcd in new ControlPlane machines - the part of the spec this variable sets - change the value using the below patch:
Running the patch makes the following change to the Cluster yaml:
196
+
```diff
197
+
spec:
198
+
topology:
199
+
variables:
200
+
- name: imageRepository
201
+
value: k8s.gcr.io
202
+
- name: etcdImageTag
203
+
value: ""
204
+
- name: coreDNSImageTag
205
+
+ value: "3.5.0"
206
+
- value: ""
207
+
208
+
```
209
+
Retrieving the variable value from the Cluster object, with `kubectl get cluster capi-quickstart -o jsonpath='{.spec.topology.variables[1]}'` we can see:
210
+
```bash
211
+
{"name":"etcdImageTag","value":"3.5.0"}
212
+
```
213
+
Note: Changing the etcd version may have unintended impacts on a running Cluster. For safety the cluster should be reapplied after running the above variable patch.
214
+
215
+
## Rebase a Cluster
216
+
To perform more significant changes using a Cluster as a single point of control, it may be necessary to change the ClusterClass that the Cluster is based on. This is done by changing the class referenced in `/spec/topology/class`.
217
+
218
+
To read more about changing an underlying class please refer to [ClusterClass rebase].
0 commit comments