How can I get my worker nodes to join my Amazon EKS cluster?

Last updated: 2021-01-13

My worker nodes won't join my Amazon Elastic Kubernetes Service (Amazon EKS) cluster.

Short description

To get your worker nodes to join your Amazon EKS cluster, you must complete the following:

  • Confirm that you have DNS support for your Amazon Virtual Private Cloud (Amazon VPC)
  • Get the right permissions for your instance profile's worker nodes
  • Configure the user data for your worker nodes
  • Verify that your worker nodes are in a subnet that is associated with your Amazon EKS cluster
  • Update the aws-auth ConfigMap with the NodeInstanceRole of your worker nodes
  • Meet the security group requirements of your worker nodes
  • Set the tags for your worker nodes
  • Confirm that your worker nodes can reach the API server endpoint for your Amazon EKS cluster
  • Connect to your Amazon EKS worker node's Amazon Elastic Compute Cloud (Amazon EC2) instance using SSH and search through kubelet agent logs for errors

Important: The following steps don't include the configurations that are required to register worker nodes in your Amazon EKS cluster in environments where the following criteria aren't met:

  • In the VPC for your Amazon EKS cluster, the configuration parameter domain-name-servers is set to AmazonProvidedDNS. For more information, see DHCP options sets.
  • You're using an Amazon EKS-optimized Linux Amazon Machine Image (AMI) to launch your worker nodes.
    Note: The Amazon EKS-optimized Linux AMI provides all necessary configurations, including a /etc/eks/bootstrap.sh bootstrap script for registering worker nodes to your Amazon EKS cluster.

Resolution

Confirm that you have DNS support for your VPC

Confirm that the VPC for your Amazon EKS cluster has support for a DNS hostname and DNS resolution.

If required, view and update the DNS support attributes for your VPC.

Get the right permissions for your instance profile's worker nodes

Attach the following AWS managed polices to the role associated with your instance profile's worker nodes:

  • AmazonEKSWorkerNodePolicy
  • AmazonEKS_CNI_Policy
  • AmazonEC2ContainerRegistryReadOnly

To attach policies to roles, see Adding IAM identity permissions (console).

Configure the user data for your worker nodes

Note: You don't have to configure the user data for your worker nodes if you're using AWS CloudFormation to launch your worker nodes.

To configure user data for your worker nodes, specify the user data when you launch your Amazon EC2 instances.

For example, if you’re using a third-party tool such as Terraform, update the User data field to launch your Amazon EKS worker nodes with the following:

#!/bin/bash
set -o xtrace
/etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments}

Important: Replace ${ClusterName} with the name of your Amazon EKS cluster. Replace ${BootstrapArguments} with additional bootstrap values, or leave this property blank.

Verify that your worker nodes are in a subnet that is associated with your Amazon EKS cluster

1.    Open the Amazon EKS console.

2.    Choose Clusters, and then select your cluster.

3.    In the Networking section, identify the subnets that are associated with your cluster.

4.    Verify that your worker nodes belong only to the subnets that you identified in step 3.

Update the aws-auth ConfigMap with the NodeInstanceRole of your worker nodes

Verify that the aws-auth ConfigMap is configured correctly with the AWS Identity and Access Management (IAM) role of your worker nodes (and not the instance profile).

Meet the security group requirements of your worker nodes

Confirm that your control plane's security group and worker node security group are configured with recommended settings for inbound and outbound traffic.

Set the tags for your worker nodes

For the Tag property of your worker nodes, set key to kubernetes.io/cluster/clusterName and set value to owned.

For more information, see Cluster VPC considerations.

Confirm that your worker nodes can reach the API server endpoint for your Amazon EKS cluster

Consider the following:

  • You can launch worker nodes in a subnet that is associated with a route table that has a route to the API endpoint through a NAT gateway or internet gateway.
  • If your worker nodes are launched in a restricted private network, then confirm that your worker nodes can reach the Amazon EKS API server endpoint.
  • If your worker nodes are launched as part of a VPC using a custom DNS instead of AmazonProvidedDNS, then your worker nodes might not resolve the endpoint for the Amazon EKS cluster if public access to the endpoint is disabled and only private access is enabled. For more information, see Enabling DNS resolution for Amazon EKS cluster endpoints.

Connect to your Amazon EKS worker node instance with SSH and check kubelet agent logs

The kubelet agent is configured as a systemd service.

1.    To validate your kubelet logs, run the following command:

journalctl -f -u kubelet

2.    To resolve any issues, check the Amazon EKS troubleshooting guide for common errors.


Did this article help?


Do you need billing or technical support?