Skip to main content
Skip table of contents

Enterprise: Upgrade the Management Cluster Kubernetes Version

Upgrade the Kubernetes version on the Management cluster.

These pages refer to DKP Enterprise and DKP Gov Advanced products.

Upgrade the Kubernetes Version

When upgrading the Kubernetes version of a cluster:

  1. Upgrade the control plane first using the infrastructure specific command.

    1. NOTE the additional considerations for FIPS if using FIPS configuration.

  2. Upgrade the node pools second using the infrastructure specific command.

    1. NOTE the additional considerations for FIPS if using FIPS configuration.

  3. If you have any additional managed, you need to upgrade the core addons and Kubernetes version for each one. Attached clusters would need the Kubernetes version upgraded to a supported DKP version using the tool that created that cluster.

  4. During an upgrade, you would need to create new AMI’s or images with the K8S version to which you want to upgrade which requires selecting your OS and ensuring you have the current supported version. Build a new image if applicable.

    • If an AMI was specified when initially creating a cluster for AWS, you must build a new one with Konvoy Image Builder and set the flag(s) in the update commands. Either AMI ID --ami AMI_ID, or the lookup image flags: --ami-owner AWS_ACCOUNT_ID, --ami-base-os ubuntu-20.04, and --ami-format 'example-{{.BaseOS}}-?{{.K8sVersion}}-*'.

      ⚠️ The AMI lookup method will return an error if the lookup uses the upstream CAPA account ID.

    • If an Azure Machine Image was specified for Azure, you must build a new one with Konvoy Image Builder.

    • If a vSphere template Image was specified for vSphere, you must build a new one with Konvoy Image Builder.

    • You must build a new GCP image with Konvoy Image Builder.

  5. Upgrade the Kubernetes version of the control plane. Each cloud provider has distinctive commands. Below is the AWS command example. Select the drop-down menu next to your provider for compliant CLI.
    NOTE: The first example below is for AWS. If you created your initial cluster with a custom AMI using the --ami flag, it is required to set the --ami flag during the Kubernetes upgrade.

    CODE
    dkp update controlplane aws \ 
    --cluster-name=${CLUSTER_NAME} \ 
    --ami AMI_ID \
    --kubernetes-version=v1.26.14
OR for AWS AMI lookup ID
CODE
dkp update controlplane aws \
--cluster-name=${CLUSTER_NAME} \
--ami-owner AWS_ACCOUNT_ID \
--ami-base-os ubuntu-20.04 \
--ami-format 'example-{{.BaseOS}}-?{{.K8sVersion}}-*' \
--kubernetes-version=v1.26.14
Azure
CODE
dkp update controlplane azure --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14 --compute-gallery-id <Azure Compute Gallery built by KIB for Kubernetes v1.26.14>
  • If these fields were specified in the override file during image creation, the flags must be used in upgrade:

    • --plan-offer, --plan-publisher and --plan-sku

    • CODE
      --plan-offer rockylinux-9
      --plan-publisher erockyenterprisesoftwarefoundationinc1653071250513
      --plan-sku rockylinux-9
vSphere
CODE
dkp update controlplane vsphere --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14 --vm-template <vSphere template built by KIB for Kubernetes v1.26.14>
GCP
CODE
dkp update controlplane gcp --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14 --image=projects/${GCP_PROJECT}/global/images/<GCP image built by KIB for Kubernetes v1.26.14>
Pre-provisioned
CODE
dkp update controlplane preprovisioned --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14
EKS
CODE
dkp update controlplane eks --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.25.11
Additional Considerations for upgrading a FIPS cluster:

If upgrading a FIPS cluster, to correctly upgrade the Kubernetes version, instead run the command shown below which includes the etcd FIPS information as well:

CODE
dkp update controlplane aws --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14+fips.0 --ami=<ami-with-fips-id>

The output should be similar to the below example, with the provider name corresponding to the CLI you executed from the choices above:

CODE
Updating control plane resource controlplane.cluster.x-k8s.io/v1beta1, Kind=KubeadmControlPlane default/my-aws-cluster-control-plane
Waiting for control plane update to finish.
 ✓ Updating the control plane

Some advanced options are available for various providers. To see all the options for your particular provider, run this command dkp update controlplane aws|vsphere|preprovisioned|azure|gcp|eks --help for more advance options like the example below:

This example for AWS AMI instance type: aws: --ami, --instance-type would be some of the options mentioned in the note above.

NOTE: The command dkp update controlplane {provider} has a 30 minute default timeout for the update process to finish. If you see the error " timed out waiting for the condition“, you can check the control plane nodes version using the command kubectl get machines -o wide $KUBECONFIG before trying again.

6. Upgrade the Kubernetes version of your node pools. Upgrading a nodepool involves draining the existing nodes in the nodepool and replacing them with new nodes. In order to ensure minimum downtime and maintain high availability of the critical application workloads during the upgrade process, we recommend deploying Pod Disruption Budget (Disruptions) for your critical applications. For more information, refer to Update Cluster Nodepools documentation.

a. First, get a list of all node pools available in your cluster by running the following command:

CODE
dkp get nodepool --cluster-name ${CLUSTER_NAME}

b. Select the nodepool you want to upgrade with the command below:

CODE
export NODEPOOL_NAME=my-nodepool

c. Then update the selected nodepool using the command below. The first example command shows AWS language, so select the drop-down menu for your provider for the correct command. Execute the update command for each of the node pools listed in the previous command:
NOTE: The first example below is for AWS. If you created your initial cluster with a custom AMI using the --ami flag, it is required to set the --ami flag during the Kubernetes upgrade.

CODE
dkp update nodepool aws ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14
Azure
CODE
dkp update nodepool azure ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14 --compute-gallery-id <Azure Compute Gallery built by KIB for Kubernetes v1.26.14>
  • If these fields were specified in the override file during image creation, the flags must be used in upgrade:

    • --plan-offer, --plan-publisher and --plan-sku

    • CODE
      --plan-offer rockylinux-9
      --plan-publisher erockyenterprisesoftwarefoundationinc1653071250513
      --plan-sku rockylinux-9
vSphere
CODE
dkp update nodepool vsphere ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14 --vm-template <vSphere template built by KIB for Kubernetes v1.26.14>
GCP
CODE
dkp update nodepool gcp ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14 --image=projects/${GCP_PROJECT}/global/images/<GCP image built by KIB for Kubernetes v1.26.14>
Pre-provisioned
CODE
dkp update nodepool preprovisioned ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14
EKS
CODE
dkp update nodepool eks ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.25.11

The output should be similar to the following, with the name of the infrastructure provider shown accordingly:

CODE
Updating node pool resource cluster.x-k8s.io/v1beta1, Kind=MachineDeployment default/my-aws-cluster-my-nodepool
Waiting for node pool update to finish.
 ✓ Updating the my-aws-cluster-my-nodepool node pool

d. Repeat this step for each additional node pool.

Additional Considerations for upgrading a FIPS cluster:

If upgrading a FIPS cluster, to correctly upgrade the Kubernetes version, instead run the command shown below:

CODE
dkp update nodepool aws ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.26.14+fips.0 --ami=<ami-with-fips-id>

When all nodepools have been updated, your upgrade is complete. For the overall process for upgrading to the latest version of DKP, refer back to Upgrade DKP for more details.

Next Step:

Enterprise: Upgrade Managed Clusters

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.