使用Terraform创建EKS集群失败：节点无法加入Kubernetes集群

问题描述 #

使用Terraform创建AWS EKS集群时，节点组创建失败，报错提示Instances failed to join the kubernetes cluster，相关配置及错误信息如下：

Terraform代码 #

provider "aws" {
  region = "us-west-2"
}

resource "aws_eks_cluster" "example" {
  name     = "example-cluster"
  role_arn = aws_iam_role.example.arn

  vpc_config {
    subnet_ids = aws_subnet.example[*].id
  }
}

resource "aws_iam_role" "example" {
  name = "example-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Principal = {
          Service = "eks.amazonaws.com"
        }
      },
    ]
  })
}

resource "aws_iam_role_policy_attachment" "example-AmazonEKSClusterPolicy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSClusterPolicy"
  role       = aws_iam_role.example.name
}

resource "aws_iam_role_policy_attachment" "example-AmazonEKSServicePolicy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSServicePolicy"
  role       = aws_iam_role.example.name
}

resource "aws_vpc" "example" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_subnet" "example" {
  count = 2
  vpc_id     = aws_vpc.example.id
  cidr_block = cidrsubnet(aws_vpc.example.cidr_block, 8, count.index)
  availability_zone = element(data.aws_availability_zones.available.names, count.index)
}

data "aws_availability_zones" "available" {}

resource "aws_eks_node_group" "example" {
  cluster_name    = aws_eks_cluster.example.name
  node_group_name = "example-node-group"
  node_role_arn   = aws_iam_role.example_node_group.arn
  subnet_ids      = aws_subnet.example[*].id

  scaling_config {
    desired_size = 2
    max_size     = 3
    min_size     = 1
  }

  instance_types = ["t3.medium"]

  remote_access {
    ec2_ssh_key = "my-key"
  }

  tags = {
    Name = "example-node-group"
  }
}

resource "aws_iam_role" "example_node_group" {
  name = "example-node-group-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Principal = {
          Service = "ec2.amazonaws.com"
        }
      },
    ]
  })
}

resource "aws_iam_role_policy_attachment" "example-AmazonEKSWorkerNodePolicy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy"
  role       = aws_iam_role.example_node_group.name
}

resource "aws_iam_role_policy_attachment" "example-AmazonEC2ContainerRegistryReadOnly" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
  role       = aws_iam_role.example_node_group.name
}

resource "aws_iam_role_policy_attachment" "example-AmazonEKS_CNI_Policy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"
  role       = aws_iam_role.example_node_group.name
}

密钥对创建命令 #

aws ec2 create-key-pair --key-name my-key --query 'KeyMaterial' --output text > my-key.pem --region us-west-2 
ls -l my-key.pem 
chmod 600 my-key.pem

错误信息 #

_eks_node_group.example: Still creating... [22m40s elapsed]
aws_eks_node_group.example: Still creating... [22m50s elapsed]
aws_eks_node_group.example: Still creating... [23m0s elapsed]
aws_eks_node_group.example: Still creating... [23m10s elapsed]
╷
│ Error: waiting for EKS Node Group (example-cluster:example-node-group) create: unexpected state 'CREATE_FAILED', wanted target 'ACTIVE'. last error: i-008194c5266bcbf08, i-0df3c0087882195a7: NodeCreationFailure: Instances failed to join the kubernetes cluster
│ 
│   with aws_eks_node_group.example,
│   on main.tf line 86, in resource "aws_eks_node_group" "example":
│   86: resource "aws_eks_node_group" "example" {
│ 
╵

解决方案 #

从配置和报错来看，需修正以下几个核心问题：

1. 配置EKS集群安全组与VPC端点访问 #

节点需要和EKS API服务器通信，默认配置未开放必要端口和权限。先创建集群安全组，再更新EKS集群的VPC配置：

# 创建EKS集群安全组
resource "aws_security_group" "eks_cluster" {
  name        = "eks-cluster-sg"
  description = "EKS cluster security group"
  vpc_id      = aws_vpc.example.id

  ingress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"] # 生产环境建议限制为特定IP范围
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# 更新EKS集群的VPC配置
resource "aws_eks_cluster" "example" {
  name     = "example-cluster"
  role_arn = aws_iam_role.example.arn

  vpc_config {
    subnet_ids              = aws_subnet.example[*].id
    security_group_ids      = [aws_security_group.eks_cluster.id]
    endpoint_public_access  = true
    public_access_cidrs     = ["0.0.0.0/0"] # 生产环境建议缩小范围
  }
}

2. 添加节点组与集群的显式依赖 #

节点组必须等待集群完全就绪后再创建，否则无法获取集群配置信息：

resource "aws_eks_node_group" "example" {
  cluster_name    = aws_eks_cluster.example.name
  node_group_name = "example-node-group"
  node_role_arn   = aws_iam_role.example_node_group.arn
  subnet_ids      = aws_subnet.example[*].id

  # 显式依赖集群资源，确保集群创建完成再启动节点组
  depends_on = [aws_eks_cluster.example]

  scaling_config {
    desired_size = 2
    max_size     = 3
    min_size     = 1
  }

  instance_types = ["t3.medium"]

  remote_access {
    ec2_ssh_key = "my-key"
  }

  tags = {
    Name = "example-node-group"
  }
}

3. 配置VPC互联网网关与子网路由 #

节点需要公网访问权限以拉取镜像、连接EKS API，需添加网关和路由配置：

# 创建互联网网关
resource "aws_internet_gateway" "example" {
  vpc_id = aws_vpc.example.id
}

# 创建公网路由表
resource "aws_route_table" "example" {
  vpc_id = aws_vpc.example.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.example.id
  }
}

# 关联子网到公网路由表
resource "aws_route_table_association" "example" {
  count          = 2
  subnet_id      = aws_subnet.example[count.index].id
  route_table_id = aws_route_table.example.id
}

4. 验证密钥对存在性 #

确认密钥对在目标区域存在：

aws ec2 describe-key-pairs --key-name my-key --region us-west-2

操作步骤 #

1. 销毁现有失败资源：terraform destroy
2. 将上述修正代码合并到配置文件中
3. 执行terraform init初始化配置
4. 执行terraform plan确认配置无误
5. 执行terraform apply重新创建集群与节点组

内容的提问来源于stack exchange，提问作者learner