Amazon EKS
User Guide

Updating an Existing Worker Node Group

This topic helps you to update an existing AWS CloudFormation worker node stack with a new AMI. You can use this procedure to update your worker nodes to a new version of Kubernetes following a cluster update, or you can update to the latest Amazon EKS-optimized AMI for an existing Kubernetes version.

The latest default Amazon EKS worker node AWS CloudFormation template is configured to launch an instance with the new AMI into your cluster before removing an old one, one at a time. This configuration ensures that you always have your Auto Scaling group's desired count of active instances in your cluster during the rolling update.

Note

This method is not supported for worker node groups that were created with eksctl. If you created your cluster or worker node group with eksctl, see Migrating to a New Worker Node Group.

To update an existing worker node group

  1. Determine your cluster's DNS provider.

    kubectl get deployments -l k8s-app=kube-dns -n kube-system

    Output (this cluster is using kube-dns for DNS resolution, but your cluster may return coredns instead):

    NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE kube-dns 1 1 1 1 31m
  2. If your current deployment is running fewer than two replicas, scale out the deployment to two replicas. Substitute coredns for kube-dns if your previous command output returned that instead.

    kubectl scale deployments/kube-dns --replicas=2 -n kube-system
  3. (Optional) If you are using the Kubernetes Cluster Autoscaler, scale the deployment down to zero replicas to avoid conflicting scaling actions.

    kubectl scale deployments/cluster-autoscaler --replicas=0 -n kube-system
  4. Determine the instance type and desired instance count of your current worker node group. You will enter these values later when you update the AWS CloudFormation template for the group.

    1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

    2. Choose Launch Configurations in the left navigation, and note the instance type for your existing worker node launch configuration.

    3. Choose Auto Scaling Groups in the left navigation and note the Desired instance count for your existing worker node Auto Scaling group.

  5. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  6. Select your worker node group stack, and then choose Update.

  7. Select Replace current template and select Amazon S3 URL.

  8. For Amazon S3 URL, paste the following URL into the text area to ensure that you are using the latest version of the worker node AWS CloudFormation template, and then choose Next:

    https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2019-10-08/amazon-eks-nodegroup.yaml
  9. On the Specify stack details page, fill out the following parameters, and choose Next:

    • NodeAutoScalingGroupDesiredCapacity – Enter the desired instance count that you recorded in Step 4, or enter a new desired number of nodes to scale to when your stack is updated.

    • NodeAutoScalingGroupMaxSize – Enter the maximum number of nodes to which your worker node Auto Scaling group can scale out. This value must be at least one node greater than your desired capacity so that you can perform a rolling update of your worker nodes without reducing your node count during the update.

    • NodeInstanceType – Choose the instance type your recorded in Step 4, or choose a different instance type for your worker nodes.

      Note

      The supported instance types for the latest version of the Amazon VPC CNI plugin for Kubernetes are shown here. You may need to update your CNI version to take advantage of the latest supported instance types. For more information, see Amazon VPC CNI Plugin for Kubernetes Upgrades.

      Important

      Some instance types might not be available in all regions.

    • NodeImageIdSSMParam – The Amazon EC2 Systems Manager parameter of the AMI ID that you want to update to. The following value uses the latest Amazon EKS-optimized AMI for Kubernetes version 1.14.

      /aws/service/eks/optimized-ami/1.14/amazon-linux-2/recommended/image_id

      You can change the 1.14 value to any supported Kubernetes version. If you want to use the Amazon EKS-optimized AMI with GPU support, then change amazon-linux-2 to amazon-linux-2-gpu.

      Note

      Using the Amazon EC2 Systems Manager parameter enables you to update your worker nodes in the future without having to lookup and specify an AMI ID. If your AWS CloudFormation stack is using this value, any stack update will always launch the latest recommended Amazon EKS-optimized AMI for your specified Kubernetes version, even if you don't change any values in the template.

    • NodeImageId – To use your own custom AMI, enter the ID for the AMI to use.

      Important

      This value overrides any value specified for NodeImageIdSSMParam. If you want to use the NodeImageIdSSMParam value, ensure that the value for NodeImageId is blank.

  10. (Optional) On the Options page, tag your stack resources. Choose Next.

  11. On the Review page, review your information, acknowledge that the stack might create IAM resources, and then choose Update stack.

    Note

    Wait for the update to complete before performing the next steps.

  12. If your cluster's DNS provider is kube-dns, scale in the kube-dns deployment to one replica.

    kubectl scale deployments/kube-dns --replicas=1 -n kube-system
  13. (Optional) If you are using the Kubernetes Cluster Autoscaler, scale the deployment back to one replica.

    kubectl scale deployments/cluster-autoscaler --replicas=1 -n kube-system
  14. (Optional) Verify that you are using the latest version of the Amazon VPC CNI plugin for Kubernetes. You may need to update your CNI version to take advantage of the latest supported instance types. For more information, see Amazon VPC CNI Plugin for Kubernetes Upgrades.