Update the Control Plane

Prerequisites

Before you begin, you must:

Create a workload cluster.

Overview

There are many reasons to update the control plane. This topic covers one of the most common:

To upgrade the Kubernetes version.

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

Prepare the environment

Set the environment variable to the name you assigned this cluster.
```
CLUSTER_NAME=my-azure-cluster
```
See Get Started with Azure for information on naming your cluster.
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.
```
export KUBECONFIG=${CLUSTER_NAME}.conf
```

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-azure-cluster-control-plane        true          true                   v1.21.6   3          3       3

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}')
export CURRENT_TEMPLATE_NAME=$(kubectl get kubeadmcontrolplanes ${KUBEADMCONTROLPLANE_NAME} -ojsonpath='{.spec.machineTemplate.infrastructureRef.name}')
export NEW_TEMPLATE_NAME=${KUBEADMCONTROLPLANE_NAME}-v1216

Prepare the patch file.

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

Prepare to update the Kubernetes version

Verify that the Kubernetes version has a compatible machine image

If you use a custom image built with your own tooling, follow the tooling documentation to verify the image’s Kubernetes version.

If you do not use a custom machine image, Konvoy uses an Ubuntu 18.04 default machine image. Check that a default machine image is available for the Kubernetes version in Azure.

WARNING: If the machine image used in this step is not built for the Kubernetes version used in the previous step, the control plane machines will be unable to join the cluster.
Define the Kubernetes version. Use the letter v followed by major.minor.patch version.
```
export KUBERNETES_VERSION=v1.21.6
```

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}
EOF

Apply all prepared updates

Update the KubeadmControlPlane

The KubeadmControlPlane is patched to reference the new AzureMachineTemplate created in the previous step, and to use a new Kubernetes version, if one was provided.

NOTE: Patching the KubeadmControlPlane starts the control plane update. Machines with updated properties are created, and machines with out-of-date properties are deleted. The update is "rolling". New machines replace old machines one at a time. The update waits for each new machine to successfully join the control plane. Regardless of the specified replica count the update works the same way.
```
kubectl get kubeadmcontrolplane ${KUBEADMCONTROLPLANE_NAME} --output=yaml \
  | kubectl patch --local=true -f- --patch="{\"spec\": {\"machineTemplate\": {\"infrastructureRef\": {\"name\": \"$NEW_TEMPLATE_NAME\"} } } }" --type=merge --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-azure-cluster-control-plane configured
```

Wait for the update to complete.

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