Terraform EKS Managed Node Groups: Deep Configuration and Lifecycle Management

Terraform EKS Managed Node Groups provide AWS-managed compute capacity for EKS clusters through the terraform-aws-eks module. With this approach AWS handles the lifecycle of the underlying EC2 instances while providing integration with EKS cluster operations like scaling, updates, and node registration. EKS Managed Node Groups are created through the main EKS module by defining eksmanagednode_groups configurations. Each node group is implemented as a separate sub-module that creates the necessary AWS resources and integrates with the cluster.

For information about self-managed node groups using Auto Scaling Groups, see Self-Managed Node Groups. For serverless compute using AWS Fargate, see Fargate Profiles. For user data and bootstrap configuration, see User Data Configuration.

Core Architecture and Module Integration

EKS Managed Node Groups are built as a sub-module under the main terraform-aws-eks module. Main Module Integration sources node_groups.tf263-385. The EKS Managed Node Group sub-module creates several interconnected AWS resources to provide managed compute capacity for the EKS cluster.

The primary awseksnode_group resource is defined in modules/eks-managed-node-group/main.tf447-545. Key configuration includes:

min_size
max_size
desired_size for autoscaling behavior
instance_types
capacitytype (ONDEMAND/SPOT)
ami_type
update_config
noderepairconfig

The EKS Managed Node Group configuration flows from the main module through to the sub-module with cluster context and node-specific settings. Variable Processing occurs in the main module where nodegroups.tf263-385 processes var.eksmanagednodegroups map and time_sleep.this[0].triggers.

Every managed node is provisioned as part of an Amazon EC2 Auto Scaling group that’s managed for you by Amazon EKS. Every resource including the instances and Auto Scaling groups runs within your AWS account. Each node group runs across multiple Availability Zones that you define.

Managed node groups can also optionally leverage node auto repair, which continuously monitors the health of nodes. It automatically reacts to detected problems and replaces nodes when possible. This helps overall availability of the cluster with minimal manual intervention.

Managed Versus Self-Managed Node Groups

Running Kubernetes on AWS means running EKS. And if you want your worker nodes managed by AWS - patched, updated, and drained gracefully during upgrades - managed node groups are the way to go. They handle the EC2 lifecycle so you can focus on your workloads instead of babysitting instances.

With Amazon EKS managed node groups, you don’t need to separately provision or register the Amazon EC2 instances that provide compute capacity to run your Kubernetes applications. You can create, automatically update, or terminate nodes for your cluster with a single operation. Node updates and terminations automatically drain nodes to ensure that your applications stay available.

Simplify node lifecycle with managed node groups. Amazon EKS managed node groups automate the provisioning and lifecycle management of nodes for Amazon EKS Kubernetes clusters.

When deploying an EKS cluster with self managed node groups using the Terraform AWS EKS module, a common issue arises where the nodes simply aren’t created. In one case study, the root cause was identified as Terraform attempting to locate a custom AMI in an incorrect catalog. The solution was straightforward: explicitly specify the ami_type parameter.

The Terraform configuration was designed to set up an EKS cluster complete with self managed node groups. However, despite proper settings for VPCs, subnets, and IAM roles, the node groups were never created. The investigation revealed that Terraform was mistakenly searching for a custom AMI in a catalog that didn’t contain the desired image.

I was trying to build cluster nodes with AMI based on Amazon Linux 2023. However, AWS Console error message: Launch template nodegroup-launch-template-123456 should not specify an instance profile. The noderole in your request will be used to construct an instance profile.

Terraform plan output shows state operations such as:
module.eks.module.self_managed_node_group["custom_nodegroup "].data.aws_partition.current: Reading... module.eks.module.self_managed_node_group["custom_nodegroup "].data.aws_partition.current: Read complete after 0s [id=aws] module.eks.module.self_managed_node_group["custom_nodegroup "].data.aws_caller_identity.current: Reading... module.eks.module.self_managed_node_group["custom_nodegroup "].data.aws_iam_policy_document.assume_role_policy[0]: Reading... module.eks.module.self_managed_node_group["custom_nodegroup "].data.aws_ssm_parameter.ami[0]: Reading... module.eks.module.self_managed_node_group["custom_nodegroup "].data.aws_ssm_parameter.ami[0]: Read complete after 0s [id=/aws/service/eks/optimized-ami/1.32/amazon-linux-2/recommended/image_id]

Launch Template and User Data Customization

EKS Managed Node Groups can use custom launch templates to provide advanced EC2 configuration beyond what the managed service provides by default.

Launch Template Creation Logic:
The module creates a launch template when createlaunchtemplate = true and usecustomlaunch_template = true.

The template includes:
userdata sub-module

Each EKS Managed Node Group requires an IAM role with specific AWS managed policies and optional additional policies for extended functionality.

The module provides flexible AMI selection with automatic version management for AWS-optimized images.

IAM Roles and Policy Attachment

Each EKS Managed Node Group requires an IAM role with specific AWS managed policies and optional additional policies for extended functionality.

IAM Policy Selection Logic:
The module automatically attaches the appropriate CNI policy based on the cluster's IP family:
- AmazonEKSCNIPolicy
- AmazonEKSCNIIPv6_Policy

Policy attachment logic is implemented in modules/eks-managed-node-group/main.tf594-614.

The node group inherits security groups from multiple sources:
- vpcsecuritygroup_ids

Security group logic is in modules/eks-managed-node-group/main.tf701-753.

AMI Selection and Version Management

The module provides flexible AMI selection with automatic version management for AWS-optimized images.

AMI Selection Logic:
When amiid is not provided, the module uses AWS Systems Manager Parameter Store to find the latest AMI:
- kubernetesversion or queries latest supported versions
- ssmamitypetossm_param

The mapping logic is implemented in modules/eks-managed-node-group/main.tf401-421.

Data source usage is visible during plan:
module.eks.module.self_managed_node_group["custom_nodegroup "].data.aws_ssm_parameter.ami[0]: Read complete after 0s [id=/aws/service/eks/optimized-ami/1.32/amazon-linux-2/recommended/image_id]

Configuration Parameters and Autoscaling

Key configuration for awseksnode_group includes autoscaling behavior and instance selection.

Parameter	Purpose
min_size	Minimum number of nodes in the group
max_size	Maximum number of nodes allowed
desired_size	Target number of nodes
instance_types	List of instance types to use
capacity_type	ON_DEMAND or SPOT
ami_type	AMI type for node images
update_config	Controls node update behavior
noderepairconfig	Enables node auto repair

Capacity type selection allows mixing ON_DEMAND stability with SPOT cost savings within the same managed node group. Update config controls how AWS drains and replaces nodes during version upgrades.

Node auto repair continuously monitors node health and replaces unhealthy instances with minimal manual intervention.

Network Prerequisites and VPC Setup

This guide walks through building a production-ready EKS cluster with managed node groups in Terraform. We will cover the VPC, IAM roles, the cluster itself, node groups with different instance types, and launch template customization.

Prerequisites:
You need the AWS provider configured and a VPC with subnets ready. If you are starting from scratch, we will build the VPC as part of this setup.

terraform { required_version = ">= 1.5.0" required_providers { aws = { source = "hashicorp/aws" version = "~> 5.0" } } } provider "aws" { region = "us-east-1" }

Building the VPC:
EKS needs subnets across at least two availability zones.

Security Group Integration:
The node group inherits security groups from multiple sources:
vpcsecuritygroup_ids

Security group logic is in modules/eks-managed-node-group/main.tf701-753.

Production Terraform Example

A typical managed node group definition uses eksmanagednode_groups with autoscaling and AMI type.

module "eks" { source = "terraform-aws-modules/eks/aws" ... eks_managed_node_groups = { example = { min_size = 1 max_size = 5 desired_size = 2 instance_types = ["m5.large"] capacity_type = "ON_DEMAND" ami_type = "AL2_x86_64" } } }

Launch template customization is enabled by setting createlaunchtemplate = true and usecustomlaunch_template = true to allow advanced EC2 configuration beyond default managed settings.

The userdata sub-module is included in the template for bootstrap configuration.

Common Pitfalls and Troubleshooting

When deploying with self managed node groups, nodes may not be created due to AMI catalog mismatches. Explicitly specify the ami_type parameter to avoid Terraform searching for a custom AMI in an incorrect catalog.

Error conditions can include:
- Launch template nodegroup-launch-template-123456 should not specify an instance profile. The noderole in your request will be used to construct an instance profile.

Acquiring state lock operations during plan show data source reads for partition, caller identity, IAM policy documents, and SSM parameters for AMI lookup.

Terraform used the selected providers to generate the following execution plan.

Conclusion

EKS Managed Node Groups through the terraform-aws-eks module deliver fully managed compute with deep integration into the cluster lifecycle. The sub-module architecture creates awseksnodegroup resources with autoscaling parameters minsize, maxsize, desiredsize, instancetypes, capacitytype, amitype, updateconfig, and noderepairconfig. Launch template creation is gated by createlaunchtemplate and usecustomlaunchtemplate flags with an included _userdata sub-module.

IAM roles are provisioned with CNI policies selected automatically based on IP family, AmazonEKSCNIPolicy and AmazonEKSCNIIPv6Policy. AMI selection defaults to AWS Systems Manager Parameter Store lookups using kubernetesversion and ssmamitypetossmparam mapping. Security groups are inherited via vpcsecuritygroupids.

From an operational perspective, managed node groups eliminate manual EC2 provisioning and registration, provide automatic draining during updates and terminations, and run across multiple Availability Zones within the customer account. Node auto repair adds continuous health monitoring and automatic replacement.

Production deployments require a VPC with subnets across at least two availability zones, AWS provider version ~> 5.0 with terraform requiredversion >= 1.5.0, and explicit AMI type declarations to avoid catalog resolution failures. The module processes var.eksmanagednodegroups through node_groups.tf and delivers a single operation interface for create, update, and terminate actions with minimal manual intervention.