Launching self-managed Amazon Linux nodes

(Optional) If the AmazonEKS_CNI_Policy managed IAM policy is attached to your Amazon EKS node IAM role, we recommend assigning it to an IAM role that you associate to the Kubernetes aws-node service account instead. For more information, see Configuring the Amazon VPC CNI plugin for Kubernetes to use IAM roles for service accounts (IRSA).

The following command creates a node group in an existing cluster. Replace al-nodes with a name for your node group. The node group name can't be longer than 63 characters. It must start with letter or digit, but can also include hyphens and underscores for the remaining characters. Replace my-cluster with the name of your cluster. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 100 characters. Replace the remaining example value with your own values. The nodes are created with the same Kubernetes version as the control plane, by default.

Before choosing a value for --node-type, review Choosing an Amazon EC2 instance type.

Replace my-key with the name of your Amazon EC2 key pair or public key. This key is used to SSH into your nodes after they launch. If you don't already have an Amazon EC2 key pair, you can create one in the Amazon Web Services Management Console. For more information, see Amazon EC2 key pairs in the Amazon EC2 User Guide for Linux Instances.

Create your node group with the following command.

eksctl create nodegroup \
  --cluster my-cluster \
  --name al-nodes \
  --node-type t3.medium \
  --nodes 3 \
  --nodes-min 1 \
  --nodes-max 4 \
  --ssh-access \
  --managed=false \
  --ssh-public-key my-key

To deploy a node group that:

For a complete list of all available options and defaults, enter the following command.

eksctl create nodegroup --help

If nodes fail to join the cluster, then see Nodes fail to join cluster in the Troubleshooting guide.

An example output is as follows. Several lines are output while the nodes are created. One of the last lines of output is the following example line.

[✔]  created 1 nodegroup(s) in cluster "my-cluster"

(Optional) Deploy a sample application to test your cluster and Linux nodes.

We recommend blocking Pod access to IMDS if the following conditions are true:

For more information, see Restrict access to the instance profile assigned to the worker node.

Download the latest version of the Amazon CloudFormation template.

curl -O https://s3.cn-north-1.amazonaws.com.cn/amazon-eks/cloudformation/2022-12-23/amazon-eks-nodegroup.yaml

Wait for your cluster status to show as ACTIVE. If you launch your nodes before the cluster is active, the nodes fail to register with the cluster and you will have to relaunch them.

Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

Choose Create stack and then select With new resources (standard).

For Specify template, select Upload a template file and then select Choose file.

Select the amazon-eks-nodegroup.yaml file that you downloaded.

Select Next.

On the Specify stack details page, enter the following parameters accordingly, and then choose Next:

Select your desired choices on the Configure stack options page, and then choose Next.

Select the check box to the left of I acknowledge that Amazon CloudFormation might create IAM resources., and then choose Create stack.

When your stack has finished creating, select it in the console and choose Outputs.

Record the NodeInstanceRole for the node group that was created. You need this when you configure your Amazon EKS nodes.

Check to see if you already have an aws-auth ConfigMap.

kubectl describe configmap -n kube-system aws-auth

If you are shown an aws-auth ConfigMap, then update it as needed.

1. Open the ConfigMap for editing.

   kubectl edit -n kube-system configmap/aws-auth
   

2. Add a new mapRoles entry as needed. Set the rolearn value to the NodeInstanceRole value that you recorded in the previous procedure.

   [...]
   data:
     mapRoles: |
       - rolearn: <ARN of instance role (not instance profile)>
         username: system:node:{{EC2PrivateDNSName}}
         groups:
           - system:bootstrappers
           - system:nodes
   [...]

3. Save the file and exit your text editor.

If you received an error stating "Error from server (NotFound): configmaps "aws-auth" not found, then apply the stock ConfigMap.

1. Download the configuration map.

   curl -O https://s3.cn-north-1.amazonaws.com.cn/amazon-eks/cloudformation/2020-10-29/aws-auth-cm.yaml
   

2. In the aws-auth-cm.yaml file, set the rolearn value to the NodeInstanceRole value that you recorded in the previous procedure. You can do this with a text editor, or by replacing my-node-instance-role and running the following command:

   sed -i.bak -e 's|<ARN of instance role (not instance profile)>|my-node-instance-role|' aws-auth-cm.yaml
   

3. Apply the configuration. This command may take a few minutes to finish.

   kubectl apply -f aws-auth-cm.yaml
   

Watch the status of your nodes and wait for them to reach the Ready status.

kubectl get nodes --watch

Enter Ctrl+C to return to a shell prompt.

If nodes fail to join the cluster, then see Nodes fail to join cluster in the Troubleshooting guide.

(GPU nodes only) If you chose a GPU instance type and the Amazon EKS optimized accelerated AMI, you must apply the NVIDIA device plugin for Kubernetes as a DaemonSet 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/nvidia-device-plugin.yml

(Optional) Deploy a sample application to test your cluster and Linux nodes.

(Optional) If the AmazonEKS_CNI_Policy managed IAM policy (if you have an IPv4 cluster) or the AmazonEKS_CNI_IPv6_Policy (that you created yourself if you have an IPv6 cluster) is attached to your Amazon EKS node IAM role, we recommend assigning it to an IAM role that you associate to the Kubernetes aws-node service account instead. For more information, see Configuring the Amazon VPC CNI plugin for Kubernetes to use IAM roles for service accounts (IRSA).

We recommend blocking Pod access to IMDS if the following conditions are true:

For more information, see Restrict access to the instance profile assigned to the worker node.