Improvements for Amazon EKS Worker Node Provisioning

Amazon Elastic Container Service for Kubernetes (EKS) provides an optimized Amazon Machine Image (AMI) and AWS CloudFormation template that make it easy to provision worker nodes for your Amazon EKS cluster on AWS. These assets are both open source and available now on Github. In addition to the EKS Optimized AMI, the Packer by Hashicorp scripts used to build the EKS Optimized AMI are available on GitHub so you can build your own worker node AMI. These are useful if you want to modify the EKS Optimized AMI for your own purposes, or perhaps you want to bring your own OS entirely and mirror the configuration we use for the EKS Optimized AMI.

Previously, the CloudFormation template and the EKS Optimized AMI were tightly coupled, meaning the AMI required UserData from the CloudFormation template in order to properly boot and check in to an EKS Cluster.

The new EKS-optimized AMI and Cloudformation template refactors and breaks out the EKS Optimized AMI UserData into a separate resource: EKS Bootstrap.sh. This script simplifies the bootstrapping process for EKS worker nodes and removes the dependency on the amazon-eks-nodegroup.yaml Cloudformation template. This makes it significantly easier to provision nodes for an EKS cluster using the AWS CLI or another provisioning tool, such as Terraform.

Using the EKS Bootstrap.sh Script

The EKS Bootstrap.sh script is packaged into the EKS Optimized AMI, and only requires a single input: the EKS Cluster name. The bootstrap script can also disable “max pods” on the kubelet, add labels and taints, and supports setting any kubelet-extra-args at runtime.

$ /etc/eks/bootstrap.sh -h
usage: /etc/eks/bootstrap.sh [options] <cluster-name>
Bootstraps an instance into an EKS cluster

-h,--help print this help
--use-max-pods Sets --max-pods for the kubelet when true. (default: true)
--b64-cluster-ca The base64 encoded cluster CA content. Only valid when used with --apiserver-endpoint. Bypasses calling "aws eks describe-cluster"
--apiserver-endpoint The EKS cluster API Server endpoint. Only valid when used with --b64-cluster-ca. Bypasses calling "aws eks describe-cluster"
--kubelet-extra-args Extra arguments to add to the kubelet. Useful for adding labels or taints.

The EKS Bootstrap.sh script reduces the required UserData for EKS Node provisioning to the following:

#!/bin/bash -xe
/etc/eks/bootstrap.sh <cluster-name>

#If using with Cloudformation
/opt/aws/bin/cfn-signal --exit-code $? \ 
    --stack <stack-name> \
    --resource NodeGroup \
    --region <region>

Finally, the amazon-eks-nodegroup.yaml Cloudformation template also adds a new parameter that supports passing kubelet-extra-args to kubelet at boot time. Here’s an example of the input to the Cloudformation template BootstrapArguments parameter:

--kubelet-extra-args --node-labels=mykey=myvalue,nodegroup=NodeGroup1

Getting Started with the New AMI and CloudFormation Template

Previously, the EKS Optimized AMI was named eks-worker-vXX. Starting today, we’ve renamed the AMI to amazon-eks-node-vXX. The CloudFormation template amazon-eks-nodegroup.yaml contains version information in the description. You can run the AWS CLI command below and get the latest EKS worker image ID:

aws ec2 describe-images \
    --filters \
        Name=owner-id,Values=602401143452 \
        Name=virtualization-type,Values=hvm \
        Name=root-device-type,Values=ebs \
        Name=is-public,Values=true \
        Name=name,Values=amazon-eks-node-\* \
    --output text \
    --query 'max_by(Images[], &CreationDate).ImageId'

See the AWS documentation for more information on updating an existing CloudFormation stack to use the new CloudFormation template. Please keep in mind that the new EKS-optimized AMI and Cloudformation template must be used together. You will need to update the NodeImageID parameter to the new AMI ID when updating your stack.

Next Steps

For information on getting started and launching EKS worker nodes, with EKS, visit the Amazon EKS getting started guide. You can find the Packer by Hashicorp template for building the EKS-optimized AMI, the EKS Bootstrap script, and the amazon-eks-nodegroup.yaml Cloudformation template in our GitHub repository. To learn more about Amazon EKS, visit the EKS product page. We welcome your feedback and contributions!