Merge pull request #667 from makhov/k0scontrolplane-update-strategy-r…

…ecreate K0sControlPlane update strategy Recreate
k0sproject · Sep 16, 2024 · 0373914 · 0373914
2 parents aa85585 + c1ec82e
commit 0373914
Show file tree

Hide file tree

Showing 18 changed files with 1,066 additions and 126 deletions.
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
@@ -159,6 +159,8 @@ jobs:
           - check-capi-controlplane-docker-worker
           - check-capi-remote-machine-template-update
           - check-capi-docker-machine-template-update
+          - check-capi-docker-machine-template-update-recreate
+          - check-capi-docker-machine-template-update-recreate-single
           - check-capi-remote-machine-job-provision
 
     uses: ./.github/workflows/capi-smoke-tests.yml

diff --git a/api/controlplane/v1beta1/k0s_types.go b/api/controlplane/v1beta1/k0s_types.go
@@ -30,7 +30,8 @@ func init() {
 type UpdateStrategy string
 
 const (
-	UpdateInPlace UpdateStrategy = "InPlace"
+	UpdateInPlace  UpdateStrategy = "InPlace"
+	UpdateRecreate UpdateStrategy = "Recreate"
 )
 
 // +kubebuilder:object:root=true
@@ -52,9 +53,9 @@ type K0sControlPlaneSpec struct {
 	//+kubebuilder:validation:Optional
 	//+kubebuilder:default=1
 	Replicas int32 `json:"replicas,omitempty"`
-	// UpdateStrategy defines the strategy to use when updating the control plane. Currently only InPlace is supported.
+	// UpdateStrategy defines the strategy to use when updating the control plane.
 	//+kubebuilder:validation:Optional
-	//+kubebuilder:validation:Enum:InPlace
+	//+kubebuilder:validation:Enum=InPlace;Recreate
 	//+kubebuilder:default=InPlace
 	UpdateStrategy UpdateStrategy `json:"updateStrategy,omitempty"`
 	// Version defines the k0s version to be deployed. You can use a specific k0s version (e.g. v1.27.1+k0s.0) or

diff --git a/config/clusterapi/controlplane/bases/controlplane.cluster.x-k8s.io_k0scontrolplanes.yaml b/config/clusterapi/controlplane/bases/controlplane.cluster.x-k8s.io_k0scontrolplanes.yaml
@@ -251,7 +251,10 @@ spec:
               updateStrategy:
                 default: InPlace
                 description: UpdateStrategy defines the strategy to use when updating
-                  the control plane. Currently only InPlace is supported.
+                  the control plane.
+                enum:
+                - InPlace
+                - Recreate
                 type: string
               version:
                 description: |-

diff --git a/config/crd/bases/controlplane.cluster.x-k8s.io_k0scontrolplanes.yaml b/config/crd/bases/controlplane.cluster.x-k8s.io_k0scontrolplanes.yaml
@@ -251,7 +251,10 @@ spec:
               updateStrategy:
                 default: InPlace
                 description: UpdateStrategy defines the strategy to use when updating
-                  the control plane. Currently only InPlace is supported.
+                  the control plane.
+                enum:
+                - InPlace
+                - Recreate
                 type: string
               version:
                 description: |-

diff --git a/docs/resource-reference.md b/docs/resource-reference.md
@@ -1342,10 +1342,11 @@ Resource Types:
         <td>false</td>
       </tr><tr>
         <td><b>updateStrategy</b></td>
-        <td>string</td>
+        <td>enum</td>
         <td>
-          UpdateStrategy defines the strategy to use when updating the control plane. Currently only InPlace is supported.<br/>
+          UpdateStrategy defines the strategy to use when updating the control plane.<br/>
           <br/>
+            <i>Enum</i>: InPlace, Recreate<br/>
             <i>Default</i>: InPlace<br/>
         </td>
         <td>false</td>

diff --git a/docs/update/update-capi-cluster.md b/docs/update/update-capi-cluster.md
@@ -1,6 +1,13 @@
 # Update control nodes in Cluster API clusters
 
-k0smotron uses [k0s autopilot](https://docs.k0sproject.io/stable/autopilot/)
+k0smotron supports two ways to update the control plane in the Cluster API clusters:
+
+- [Using the k0s autopilot](#updating-the-control-plane-using-k0s-autopilot)
+- [Using the Cluster API workflow](#updating-the-control-plane-using-the-cluster-api-workflow)
+
+## Updating the control plane using k0s autopilot
+
+In case `K0sContolPlane` is created with `spec.updateStrategy=InPlace`, k0smotron uses [k0s autopilot](https://docs.k0sproject.io/stable/autopilot/)
 to seamlessly update the k0s version on the control plane **in-place**.
 
 k0smotron does not recycle new machines for the new nodes
@@ -9,8 +16,6 @@ and configure the new machine, and safer by keeping any data on the machine safe
 This differs from the usual Cluster API workflow,
 where deploying the new control plane is followed by decommissioning of the old one.
 
-## Updating the control plane
-
 1. Check the configuration of deployed k0smotron cluster in your repository. For example:
 
     ```yaml 
@@ -44,6 +49,7 @@ where deploying the new control plane is followed by decommissioning of the old
     spec:
       replicas: 3
       version: v1.28.7+k0s.0
+      updateStrategy: InPlace
       machineTemplate:
         infrastructureRef:
           apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
@@ -71,6 +77,7 @@ where deploying the new control plane is followed by decommissioning of the old
    spec:
      replicas: 3
      version: v1.29.2+k0s.0 # updated version
+     updateStrategy: InPlace
      machineTemplate:
        infrastructureRef:
          apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
@@ -85,6 +92,94 @@ where deploying the new control plane is followed by decommissioning of the old
    kubectl apply -f ./path-to-file.yaml
    ```
 
+## Updating the control plane using the Cluster API workflow
+
+In case `K0sControlPlane` is created with `spec.updateStrategy=Recreate`, k0smotron uses the Cluster API workflow to update the control plane, 
+which involves creating a new machines for control plane and decommissioning the old ones.
+
+!!! warning
+
+    The `Recreate` update strategy is not supported for k0s clusters running in `--single` mode. 
+
+For the example below, k0smotron will create 3 new machines for the control plane, ensure that the new control plane nodes are online, and then remove the old machines.
+
+```yaml
+
+1. Check the configuration of deployed k0smotron cluster in your repository. For example:
+
+    ```yaml 
+    apiVersion: cluster.x-k8s.io/v1beta1
+    kind: Cluster
+    metadata:
+      name: docker-test
+      namespace: default
+    spec:
+      clusterNetwork:
+        pods:
+          cidrBlocks:
+          - 192.168.0.0/16
+        serviceDomain: cluster.local
+        services:
+          cidrBlocks:
+          - 10.128.0.0/12
+      controlPlaneRef:
+        apiVersion: controlplane.cluster.x-k8s.io/v1beta1
+        kind: K0sControlPlane
+        name: docker-test-cp
+      infrastructureRef:
+        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+        kind: DockerCluster
+        name: docker-test
+    ---
+    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
+    kind: K0sControlPlane
+    metadata:
+      name: docker-test-cp
+    spec:
+      replicas: 3
+      version: v1.28.7+k0s.0
+      updateStrategy: Recreate
+      machineTemplate:
+        infrastructureRef:
+          apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+          kind: DockerMachineTemplate
+          name: docker-test-cp-template
+          namespace: default
+    ---
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+    kind: DockerMachineTemplate
+    metadata:
+      name: docker-test-cp-template
+      namespace: default
+    spec:
+      template:
+        spec: {}
+    ```
+
+2. Change the k0s version to [the target one](https://docs.k0sproject.io/stable/releases/#k0s-release-and-support-model). For example:
+
+   ```yaml
+   apiVersion: controlplane.cluster.x-k8s.io/v1beta1
+   kind: K0sControlPlane
+   metadata:
+     name: docker-test-cp
+   spec:
+     replicas: 3
+     version: v1.29.2+k0s.0 # updated version
+     updateStrategy: Recreate
+     machineTemplate:
+       infrastructureRef:
+         apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+         kind: DockerMachineTemplate
+         name: docker-test-cp-template
+         namespace: default
+   ```
+
+3. Update the resources:
+
+   ```bash
+   kubectl apply -f ./path-to-file.yaml
+   ```
 
 ## Known issues