Update the Worker Node Pool

Update the worker node pool to upgrade Kubernetes and/or change machine properties


Before you begin, you must:


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.


    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:

    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
          version: ${KUBERNETES_VERSION}
          maxSurge: 0
          maxUnavailable: 0

    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}