[AWS EKS - terraform] "Container runtime network not ready" reason: NetworkPluginNotReady message: Network plugin returns error: cni plugin not initialized 에러

주요 원인과 Terraform 관점의 조치사항

---

1. aws-auth ConfigMap 설정 누락

EKS는 IAM 역할을 통해 kubelet이 클러스터에 join할 수 있도록 허용해야 합니다. 해당 설정이 빠지면 Node는 EKS Control Plane과 통신이 안 되어 CNI도 설치되지 않습니다.

조치:

• Terraform에서 aws-auth ConfigMap 설정이 들어갔는지 확인해야 합니다.

예시:

resource "kubernetes_config_map_v1_data" "aws_auth" {
  metadata {
    name      = "aws-auth"
    namespace = "kube-system"
  }

  data = {
    mapRoles = yamlencode([
      {
        rolearn  = aws_iam_role.node_role.arn
        username = "system:node:{{EC2PrivateDNSName}}"
        groups   = [
          "system:bootstrappers",
          "system:nodes"
        ]
      }
    ])
  }
}

aws_iam_role.node_role.arn 이 NodeGroup에 할당된 역할과 정확히 일치해야 합니다.

---

2. VPC 서브넷 및 보안 그룹 문제

EKS는 amazon-k8s-cni DaemonSet을 클러스터가 직접 노드에 배포합니다. 하지만 다음 중 하나라도 문제가 있으면 실패합니다.

• 인터넷 접근 불가 (NAT Gateway 누락 또는 라우팅 문제)
  → amazon-k8s-cni는 AWS S3에서 바이너리를 받아야 합니다.
• 보안 그룹에서 EKS Control Plane → 노드 통신 차단
  → 443, 1025-65535 포트 오픈 필요

조치:

1. private 서브넷에 NAT Gateway를 통해 인터넷 접근 가능한지 확인
2. NodeGroup에 연결된 보안 그룹에서 Inbound/Outbound 규칙 확인

---

3. EKS Addon 설치 누락 또는 실패

Terraform 최신 모듈(terraform-aws-eks)은 CNI를 addon으로 자동 설치할 수 있습니다.

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "20.8.6"

  cluster_name    = "your-cluster"
  cluster_version = "1.29"

  enable_irsa = true

  vpc_id                         = module.vpc.vpc_id
  subnet_ids                     = module.vpc.private_subnets
  control_plane_subnet_ids       = module.vpc.intra_subnets

  eks_managed_node_groups = {
    default = {
      desired_size = 2
      instance_types = ["t3.medium"]
      iam_role_arn = aws_iam_role.node.arn
    }
  }

  eks_addons = {
    coredns = {
      most_recent = true
    }
    kube-proxy = {
      most_recent = true
    }
    vpc-cni = {
      most_recent = true
    }
  }
}

vpc-cni addon이 빠져 있거나 제대로 설치되지 않으면 위와 같은 cni plugin not initialized 에러가 발생합니다.

조치:

• eks_addons 블럭에서 vpc-cni 가 포함되어 있는지 확인
• 혹은 수동으로 설치 시 Helm 또는 kubectl apply -f 방식으로 배포 필요

---

4. 노드 그룹의 IAM Role에 필요한 권한 부족

CNI 플러그인이 동작하려면 노드 IAM Role에 아래와 같은 정책이 포함되어 있어야 합니다:

• AmazonEKSWorkerNodePolicy
• AmazonEKS_CNI_Policy
• AmazonEC2ContainerRegistryReadOnly

조치:

Terraform 예시:

resource "aws_iam_role_policy_attachment" "cni" {
  role       = aws_iam_role.node.name
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"
}

---

🔍 확인 체크리스트 요약

 

체크포인트	확인 사항
aws-auth 설정	Node IAM Role이 aws-auth ConfigMap에 등록되어 있는가
VPC 구성	NAT Gateway를 통해 인터넷 접근 가능한가
보안 그룹	Control Plane과 노드 간 통신 포트가 열려 있는가
EKS Addons	vpc-cni addon이 설치되었는가
IAM 정책	Node IAM Role에 AmazonEKS_CNI_Policy 포함되었는가

 

 

 

 

terraform aws eks 문서

https://github.com/terraform-aws-modules/terraform-aws-eks

GitHub - terraform-aws-modules/terraform-aws-eks: Terraform module to create Amazon Elastic Kubernetes (EKS) resources 🇺🇦