Update existing cluster to new Kubernetes version

Ensure your cluster is in a state that will support an upgrade. This includes checking the Kubernetes APIs used by resources deployed into the cluster, ensuring the cluster is free of any health issues. You should use Amazon EKS upgrade insights when evaluating your cluster’s upgrade readiness.

Upgrade the control plane to the next minor version (for example, from 1.31 to 1.32).

Upgrade the nodes in the data plane to match that of the control plane.

Upgrade any additional applications that run on the cluster (for example, cluster-autoscaler).

Upgrade the add-ons provided by Amazon EKS, such as those included by default:

Upgrade any clients that communicate with the cluster (for example, kubectl).

Compare the Kubernetes version of your cluster control plane to the Kubernetes version of your nodes.

Before updating your control plane to a new Kubernetes version, make sure that the Kubernetes minor version of both the managed nodes and Fargate nodes in your cluster are the same as your control plane’s version. For example, if your control plane is running version 1.29 and one of your nodes is running version 1.28, then you must update your nodes to version 1.29 before updating your control plane to 1.30. We also recommend that you update your self-managed nodes and hybrid nodes to the same version as your control plane before updating the control plane. For more information, see Update a managed node group for your cluster, Update self-managed nodes for your cluster, and Upgrade hybrid nodes for your cluster. If you have Fargate nodes with a minor version lower than the control plane version, first delete the Pod that’s represented by the node. Then update your control plane. Any remaining Pods will update to the new version after you redeploy them.

If the Kubernetes version that you originally deployed your cluster with was Kubernetes 1.25 or later, skip this step.

By default, the Pod security policy admission controller is enabled on Amazon EKS clusters. Before updating your cluster, ensure that the proper Pod security policies are in place. This is to avoid potential security issues. You can check for the default policy with the kubectl get psp eks.privileged command.

kubectl get psp eks.privileged

If you receive the following error, see Amazon EKS default Pod security policy before proceeding.

Error from server (NotFound): podsecuritypolicies.extensions "eks.privileged" not found

If the Kubernetes version that you originally deployed your cluster with was Kubernetes 1.18 or later, skip this step.

You might need to remove a discontinued term from your CoreDNS manifest.

Open the Amazon EKS console.

Choose Upgrade now for a cluster you wish to upgrade.

Select the version to update your cluster to and choose Upgrade.

The update takes several minutes to complete. Continue to Step 4: Update cluster components.

Verify that the Amazon CLI is installed and that you are logged in. For more information, see Installing or updating to the latest version of the Amazon CLI.

Update your Amazon EKS cluster with the following Amazon CLI command. Replace <cluster-name> and <region-code> of the cluster you want to upgrade. Replace <version-number> with the Amazon EKS supported version number that you want to update your cluster to. For a list of supported version numbers, see Understand the Kubernetes version lifecycle on EKS.

aws eks update-cluster-version --name <cluster-name> \
  --kubernetes-version <verion-number> --region <region-code>

An example output is as follows.

{
    "update": {
        "id": "<update-id>",
        "status": "InProgress",
        "type": "VersionUpdate",
        "params": [
            {
                "type": "Version",
                "value": "<version-number>"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.1"
            }
        ],
[...]
        "errors": []
    }

The update takes several minutes to complete. Monitor the status of your cluster update with the following command. In addition to using the same <cluster-name> and <region-code>, use the <update-id> that the previous command returned.

aws eks describe-update --name <cluster-name> \
   --region <region-code> --update-id <update-id>

When a Successful status is displayed, the update is complete.

Continue to Step 4: Update cluster components.

After your cluster update is complete, update your nodes to the same Kubernetes minor version as your updated cluster. For more information, see Update self-managed nodes for your cluster, Update a managed node group for your cluster, and Upgrade hybrid nodes for your cluster. Any new Pods that are launched on Fargate have a kubelet version that matches your cluster version. Existing Fargate Pods aren’t changed.

(Optional) If you deployed the Kubernetes Cluster Autoscaler to your cluster before updating the cluster, update the Cluster Autoscaler to the latest version that matches the Kubernetes major and minor version that you updated to.

(Clusters with GPU nodes only) If your cluster has node groups with GPU support (for example, p3.2xlarge), you must update the NVIDIA device plugin for KubernetesDaemonSet on your cluster. Replace <vX.X.X> with your desired NVIDIA/k8s-device-plugin version before running the following command.

kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/<vX.X.X>/deployments/static/nvidia-device-plugin.yml

Update the Amazon VPC CNI plugin for Kubernetes, CoreDNS, and kube-proxy add-ons. We recommend updating the add-ons to the minimum versions listed in Service account tokens.

If necessary, update your version of kubectl. You must use a kubectl version that is within one minor version difference of your Amazon EKS cluster control plane.