Updating an Amazon EKS cluster Kubernetes version

To update the Kubernetes version for your cluster

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

   • Get the Kubernetes version of your cluster control plane.

     kubectl version --short
     

   • Get the Kubernetes version of your nodes. This command returns all self-managed and managed Amazon EC2 and Fargate nodes. Each Fargate pod is listed as its own node.

     kubectl get 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.24 and one of your nodes is running version 1.23, then you must update your nodes to version 1.24 before updating your control plane to 1.25. We also recommend that you update your self-managed nodes to the same version as your control plane before updating the control plane. For more information, see Updating a managed node group and Self-managed node updates. 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.

2. 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 default pod security policy before proceeding.

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

3. 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.

   1. Check to see if your CoreDNS manifest has a line that only has the word upstream.

      kubectl get configmap coredns -n kube-system -o jsonpath='{$.data.Corefile}' | grep upstream
      

      If no output is returned, this means that your manifest doesn't have the line. If this is the case, skip to the next step. If the word upstream is returned, remove the line.

   2. Remove the line near the top of the file that only has the word upstream in the configmap file. Don't change anything else in the file. After the line is removed, save the changes.

      kubectl edit configmap coredns -n kube-system -o yaml
      

4. Update your cluster using eksctl, the Amazon Web Services Management Console, or the Amazon CLI.

   Important

   • If you're updating to version 1.22, you must make the changes listed in Kubernetes version 1.22 prerequisites to your cluster before updating it.

   • If you're updating to version 1.23 and use Amazon EBS volumes in your cluster, then you must install the Amazon EBS CSI driver in your cluster before updating your cluster to version 1.23 to avoid workload disruptions. For more information, see Kubernetes 1.23 and Amazon EBS CSI driver.

   • Because Amazon EKS runs a highly available control plane, you can update only one minor version at a time. For more information about this requirement, see Kubernetes Version and Version Skew Support Policy. Assume that your current cluster version is version 1.23 and you want to update it to version 1.25. You must first update your version 1.23 cluster to version 1.24 and then update your version 1.24 cluster to version 1.25.

   • Make sure that the kubelet on your managed and Fargate nodes are at the same Kubernetes version as your control plane before you update. We recommend that your self-managed nodes are at the same version as the control plane. They can be only up to one version behind the current version of the control plane.

   • If your cluster is configured with a version of the Amazon VPC CNI plugin for Kubernetes that is earlier than 1.8.0, then we recommend that you update the plugin to the latest version before updating your cluster to version 1.21 or later. To update the plugin, see Working with the Amazon VPC CNI plugin for Kubernetes Amazon EKS add-on.

   • If you're updating your cluster to version 1.25 or later and have the Amazon Load Balancer Controller deployed in your cluster, then update the controller to version 2.4.7 or later before updating your cluster version to 1.25. For more information, see the Kubernetes 1.25 release notes.

   eksctl

   This procedure requires eksctl version 0.135.0 or later. You can check your version with the following command:

   eksctl version
   

   For instructions on how to install and update eksctl, see Installing or updating eksctl.

   Update the Kubernetes version of your Amazon EKS control plane. Replace my-cluster with your cluster name. Replace 1.25 with the Amazon EKS supported version number that you want to update your cluster to. For a list of supported version numbers, see Amazon EKS Kubernetes versions.

   eksctl upgrade cluster --name my-cluster --version 1.25 --approve
   

   The update takes several minutes to complete.

   Amazon Web Services Management Console

   1. Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters.

   2. Choose the name of the Amazon EKS cluster to update and choose Update cluster version.

   3. For Kubernetes version, select the version to update your cluster to and choose Update.

   4. For Cluster name, enter the name of your cluster and choose Confirm.

      The update takes several minutes to complete.

   Amazon CLI

   1. Update your Amazon EKS cluster with the following Amazon CLI command. Replace the example values with your own. Replace 1.25 with the Amazon EKS supported version number that you want to update your cluster to. For a list of supported version numbers, see Amazon EKS Kubernetes versions.

      aws eks update-cluster-version --region region-code --name my-cluster --kubernetes-version 1.25
      

      The example output is as follows.

      {
          "update": {
              "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
              "status": "InProgress",
              "type": "VersionUpdate",
              "params": [
                  {
                      "type": "Version",
                      "value": "1.25"
                  },
                  {
                      "type": "PlatformVersion",
                      "value": "eks.1"
                  }
              ],
      ...
              "errors": []
          }
      }

   2. Monitor the status of your cluster update with the following command. Use the cluster name and update ID that the previous command returned. When a Successful status is displayed, the update is complete. The update takes several minutes to complete.

      aws eks describe-update --region region-code --name my-cluster --update-id b5f0ba18-9a87-4450-b5a0-825e6e84496f
      

      The example output is as follows.

      {
          "update": {
              "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
              "status": "Successful",
              "type": "VersionUpdate",
              "params": [
                  {
                      "type": "Version",
                      "value": "1.25"
                  },
                  {
                      "type": "PlatformVersion",
                      "value": "eks.1"
                  }
              ],
      ...
              "errors": []
          }
      }

5. After your cluster update is complete, update your nodes to the same Kubernetes minor version as your updated cluster. For more information, see Self-managed node updates and Updating a managed node group. Any new pods that are launched on Fargate have a kubelet version that matches your cluster version. Existing Fargate pods aren't changed.

6. (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.

   1. Open the Cluster Autoscaler releases page in a web browser and find the latest Cluster Autoscaler version that matches your cluster's Kubernetes major and minor version. For example, if your cluster's Kubernetes version is 1.25 find the latest Cluster Autoscaler release that begins with 1.25. Record the semantic version number (1.25.n, for example) for that release to use in the next step.

   2. Set the Cluster Autoscaler image tag to the version that you recorded in the previous step with the following command. If necessary, replace 1.25.n with your own value.

      kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=public.ecr.aws/bitnami/cluster-autoscaler:v1.25.n
      

7. (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 Kubernetes DaemonSet on your cluster with the following command.

   kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.9.0/nvidia-device-plugin.yml
   

8. Update the Amazon VPC CNI plugin for Kubernetes, CoreDNS, and kube-proxy add-ons. If you updated your cluster to version 1.21 or later, than we recommend updating the add-ons to the minimum versions listed in Service account tokens.

   • If you are using Amazon EKS add-ons, select Clusters in the Amazon EKS console, then select the name of the cluster that you updated in the left navigation pane. Notifications appear in the console. They inform you that a new version is available for each add-on that has an available update. To update an add-on, select the Add-ons tab. In one of the boxes for an add-on that has an update available, select Update now, select an available version, and then select Update.

   • Alternately, you can use the Amazon CLI or eksctl to update add-ons. For more information, see Updating an add-on.

9. 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. For example, a 1.24 kubectl client works with Kubernetes 1.23, 1.24, and 1.25 clusters. You can check your currently installed version with the following command.

   kubectl version --short --client