Update the Control Plane

Prerequisites

Before you begin, you must:

• Create a workload cluster.

Overview

You may have many reasons to update the control plane. This topic covers three of the most common:

1. To upgrade the Kubernetes version.

The control plane is described by a KubeadmControlPlane resource. This topic explains how to patch the KubeadmControlPlane in order to update the control plane.

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 ready to be 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 KUBEADMCONTROLPLANE_NAME=$(kubectl get kubeadmcontrolplanes --selector=cluster.x-k8s.io/cluster-name=${CLUSTER_NAME} -ojsonpath='{.items[0].metadata.name}')
   

5. Prepare the patch files.

   echo '{}' > control-plane-kubernetes-version-patch.yaml
   

Prepare to update the Kubernetes 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 > control-plane-kubernetes-version-patch.yaml
   apiVersion: controlplane.cluster.x-k8s.io/v1alpha4
   kind: KubeadmControlPlane
   spec:
     version: ${KUBERNETES_VERSION}
     rolloutStrategy:
       rollingUpdate:
         maxSurge: 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 control plane is not possible.

3. Update the KubeadmControlPlane

   The KubeadmControlPlane is patched to use a new Kubernetes version.

   NOTE: Patching the KubeadmControlPlane starts the control plane update. The control plane nodes will be drained and then cordoned from the cluster. Once this is complete, a job running Konvoy Image Builder will update the Kubernetes version for the Control Plane node in place. Finally once the update is complete, the node will rejoin the cluster with the updated version.

   kubectl get kubeadmcontrolplane ${KUBEADMCONTROLPLANE_NAME} --output=yaml \
     | kubectl patch --local=true -f- --patch-file=control-plane-kubernetes-version-patch.yaml --type=merge --output=yaml \
     | kubectl apply -f-
   

   kubeadmcontrolplane.controlplane.cluster.x-k8s.io/my-preprovisioned-cluster-control-plane configured
   

4. Wait for the update to complete.

   When the condition Ready is true, the update is complete.

   kubectl wait --timeout=30m kubeadmcontrolplane ${KUBEADMCONTROLPLANE_NAME} --for=condition=Ready
   

   NOTE: This may take longer than 30 minutes, depending on the size of your cluster.