Update the Worker Node Pool

Prerequisites

Before you begin, you must:

• Create a workload cluster.

Overview

This topic details how to update the worker node pool by updating the k8s version:

The worker node pool is described by a MachineDeployment resource, which references immutable PreprovisionedMachineTemplate and KubeadmConfigTemplate resources. This topic explains how to patch the MachineDeployment in order to update the node pool in place.

Prepare the environment

1. Set the environment variable to the name you assigned this cluster.

   CLUSTER_NAME=my-preprovisioned-cluster
   

   See define infrastructure for information on naming your cluster.

2. If your workload cluster is self-managed, as described in Make the New Cluster Self-Managed, configure kubectl to use the kubeconfig for the cluster. If it is not self-managed, skip this step.

   export KUBECONFIG=${CLUSTER_NAME}.conf
   

3. Verify that the control plane is already updated.

   kubectl get kubeadmcontrolplane ${CLUSTER_NAME}-control-plane
   

   The replicas, ready replicas, and updated replicas counts should be equal, as seen here:

   NAME                             INITIALIZED   API SERVER AVAILABLE   VERSION   REPLICAS   READY   UPDATED   UNAVAILABLE
   my-preprovisioned-cluster-control-plane        true          true                   v1.21.3   1          1       1
   

4. Define the names of the resources.

   export MACHINEDEPLOYMENT_NAME=$(kubectl get machinedeployments --selector=cluster.x-k8s.io/cluster-name=${CLUSTER_NAME} -ojsonpath='{.items[0].metadata.name}')
   

5. Define the name of your worker template.

   export WORKER_TEMPLATE=$(kubectl get PreprovisionedMachineTemplate ${CLUSTER_NAME}-md-0 -ojsonpath='{.metadata.name}')
   

6. Prepare the patch files.

   echo '{}' > md-kubernetes-version-patch.yaml
   

Prepare to update the Kubernetes version

WARNING: Update the Kubernetes version of the worker node pool only if the control plane is already at the newer version.

1. Define the Kubernetes version. Use the letter v followed by major.minor.patch version.

   export KUBERNETES_VERSION=v1.21.6
   

2. Create a patch file.

   cat <<EOF > md-kubernetes-version-patch.yaml
   apiVersion: cluster.x-k8s.io/v1alpha4
   kind: MachineDeployment
   spec:
     template:
       spec:
         version: ${KUBERNETES_VERSION}
     strategy:
       rollingUpdate:
         maxSurge: 0
         maxUnavailable: 0
   EOF
   

   NOTE: The maxSurge: 0 configuration sets the update strategy so that an old machine is deleted before a new machine is created. This strategy is required to perform a rolling update when additional, unused machines are not available.

   WARNING: When maxSurge: 0 is configured, an update of a one-machine worker node pool interrupts workloads running in that pool.

3. Update the MachineDeployment

   The MachineDeployment is patched to use a new Kubernetes version.

   kubectl get machinedeployment ${MACHINEDEPLOYMENT_NAME} --output=yaml \
     | kubectl patch --local=true -f- --patch="{\"spec\": {\"template\": {\"spec\": {\"infrastructureRef\": {\"name\": \"$WORKER_TEMPLATE\"} } } } }" --type=merge --output=yaml \
     | kubectl patch --local=true -f- --patch-file=md-kubernetes-version-patch.yaml --type=merge --output=yaml \
     | kubectl apply -f-
   

   machinedeployment.cluster.x-k8s.io/my-preprovisioned-cluster-md-0 configured
   

4. Wait for the update to complete. When the number of replicas is equal to the number of updated replicas, the update is complete. You can check the status of the update by running the following command.

   kubectl get machinedeployment ${MACHINEDEPLOYMENT_NAME}