Update the Control Plane

Update the control plane to upgrade Kubernetes and/or change machine properties


Before you begin, you must:


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.


    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:

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