Update control nodes in Cluster API clusters#

k0smotron supports two ways to update the control plane in the Cluster API clusters:

Using the k0s autopilot
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 to seamlessly update the k0s version on the control plane in-place.

k0smotron does not recycle new machines for the new nodes to make the control plane upgrade process faster by avoiding the need to spin up 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.

Check the configuration of deployed k0smotron cluster in your repository. For example:

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: InPlace
  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: {}

Change the k0s version to the target one. For example:

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: InPlace
  machineTemplate:
    infrastructureRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: DockerMachineTemplate
      name: docker-test-cp-template
      namespace: default

Update the resources:
```
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.

Check the configuration of deployed k0smotron cluster in your repository. For example:

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: {}

Change the k0s version to the target one. For example:

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

Update the resources:
```
kubectl apply -f ./path-to-file.yaml
```

Known issues#

Due to the bug in the older k0s autopilot versions, the control plane upgrade may get stuck on the Cordoning stage if the control plane is running on the same node as the worker nodes. For example, --enable-worker flag was used during the control plane deployment. The bug is fixed in the latest patch versions of k0s.

To fix this issue: - Check the current node that is being updated from the kubectl get plan autopilot -o yaml output. - Manually drain the node. - In Controlnode object patch the corresponding k0sproject.io/autopilot-signal-data annotation: change the status field in the JSON from Cordoning to ApplyingUpdate. - Repeat the steps for all the nodes that are being updated.