TerraformPilot

Troubleshooting

Fix Terraform EKS Node Group - InvalidParameterException

Fix EKS node group creation errors in Terraform. Covers subnet requirements, AMI compatibility, instance types, IAM roles, and launch template conflicts.

LLuca Berton2 min read

Quick Answer

#

The EKS node group configuration has invalid parameters — usually wrong subnets (need private with NAT), missing IAM policies, incompatible instance types, or launch template conflicts. Check the specific error detail after InvalidParameterException:.

The Error

# 
Error: creating EKS Node Group (prod:workers):
  InvalidParameterException: Subnet subnet-xxx is not valid for
  creating nodes. The subnet must have a route to the internet.
Error: creating EKS Node Group:
  InvalidParameterException: instanceTypes must be within the
  same family to use with a node group
Error: creating EKS Node Group:
  InvalidParameterException: The provided role doesn't have the
  Amazon EKS Managed Policies associated with it.

What Causes This Error

#

1. Subnets Without NAT Gateway Route

#

EKS worker nodes need outbound internet access to pull container images. Private subnets must route through a NAT Gateway.

2. Missing IAM Policies

#

The node group IAM role needs specific AWS managed policies.

3. Instance Type Incompatibility

#

Mixing instance families or using unavailable instance types for the region/AZ.

4. Launch Template Conflicts

#

Launch template settings that conflict with EKS managed node group requirements.

How to Fix It

#

Solution 1: Use Private Subnets with NAT

# 
resource "aws_eks_node_group" "workers" {
  cluster_name    = aws_eks_cluster.main.name
  node_group_name = "workers"
  node_role_arn   = aws_iam_role.eks_nodes.arn
  subnet_ids      = var.private_subnet_ids  # Private subnets with NAT route
 
  scaling_config {
    desired_size = 2
    max_size     = 4
    min_size     = 1
  }
 
  instance_types = ["t3.medium"]
 
  depends_on = [
    aws_iam_role_policy_attachment.eks_worker_node_policy,
    aws_iam_role_policy_attachment.eks_cni_policy,
    aws_iam_role_policy_attachment.ecr_read_only,
  ]
}

Solution 2: Attach Required IAM Policies

# 
resource "aws_iam_role" "eks_nodes" {
  name = "eks-node-group-role"
 
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "ec2.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })
}
 
# All three policies are REQUIRED
resource "aws_iam_role_policy_attachment" "eks_worker_node_policy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy"
  role       = aws_iam_role.eks_nodes.name
}
 
resource "aws_iam_role_policy_attachment" "eks_cni_policy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"
  role       = aws_iam_role.eks_nodes.name
}
 
resource "aws_iam_role_policy_attachment" "ecr_read_only" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
  role       = aws_iam_role.eks_nodes.name
}

Solution 3: Fix Instance Type Selection

# 
# Use compatible instance types from the same generation
resource "aws_eks_node_group" "workers" {
  instance_types = ["t3.medium", "t3.large"]  # Same family OK
 
  # For GPU workloads
  # instance_types = ["g4dn.xlarge"]
 
  # For ARM/Graviton
  # instance_types = ["t4g.medium", "t4g.large"]
  # ami_type = "AL2_ARM_64"
}

Solution 4: Verify Subnet Routing

# 
# Check subnet route tables
aws ec2 describe-route-tables \
  --filters "Name=association.subnet-id,Values=subnet-xxx" \
  --query 'RouteTables[].Routes[?DestinationCidrBlock==`0.0.0.0/0`]'
 
# Should show a NAT Gateway for private subnets:
# NatGatewayId: nat-xxx

Required IAM Policies Reference

#
PolicyRequired For
AmazonEKSWorkerNodePolicyNode registration with EKS
AmazonEKS_CNI_PolicyPod networking (VPC CNI)
AmazonEC2ContainerRegistryReadOnlyPulling container images from ECR
AmazonSSMManagedInstanceCoreOptional: SSM access to nodes

Troubleshooting Checklist

#
  1. ✅ Do subnets have a route to the internet? (NAT Gateway for private subnets)
  2. ✅ Does the IAM role have all three required policy attachments?
  3. ✅ Are instance types available in the target AZs?
  4. ✅ Is the AMI type compatible with the instance type?
  5. ✅ Does the launch template conflict with EKS managed settings?
  6. ✅ Is the EKS cluster in ACTIVE state?

Prevention Tips

#
  • Always attach all three required IAM policies before creating node groups
  • Use depends_on for IAM policy attachments — IAM propagation takes seconds
  • Use private subnets with NAT for node groups — don't expose nodes publicly
  • Test instance type availability in your target AZs before committing
#

Conclusion

#

EKS node group InvalidParameterException errors come from subnet routing, missing IAM policies, or instance type issues. Ensure private subnets have NAT Gateway routes, attach all three required IAM policies, and use compatible instance types. Check the specific error detail — it tells you exactly which parameter is invalid.

#Terraform#AWS#Troubleshooting#Error Fix

Share this article

Related articles