# terraform-aws-modules/terraform-aws-eks: what the module actually builds

> The Terraform module most teams reach for when they need an EKS cluster, its node groups and its access entries from one apply. Here is how it is structured, how to install it, and where it stops being the right tool.

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

- Repository: https://github.com/terraform-aws-modules/terraform-aws-eks
- Website: https://registry.terraform.io/modules/terraform-aws-modules/eks/aws
- Stars: 5,006 · Forks: 4,412
- Language: HCL
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/terraform-aws-modules-terraform-aws-eks

## The gap this module fills between raw aws_eks_* resources and a working cluster

Creating an EKS cluster with the plain AWS provider means writing an aws_eks_cluster resource, then IAM roles for the control plane, then aws_eks_node_group resources, then the aws-auth ConfigMap or access entries, then the addons, then the security group rules that let nodes talk to the control plane. Each of those is a separate resource with its own dependency graph. The module collapses that graph into a single module call with arguments such as name, kubernetes_version, vpc_id and subnet_ids. The README describes it as a module which creates Amazon EKS (Kubernetes) resources, and the repository layout backs that up: main.tf, node_groups.tf, outputs.tf and variables.tf at the top level, with a modules/ directory for the pieces the root module composes. It is aimed at platform teams who already run Terraform and want the cluster to be one more entry in the same state file, not a separate toolchain. If you are still deciding whether Terraform and Kubernetes belong together at all, this module assumes the answer is yes and that Terraform owns the cluster while kubectl owns the workloads.

## How the module is laid out and what happens during an apply

The root module is the composition layer. It reads your inputs, creates the control plane resources, and passes the resulting identifiers down into submodules under modules/. Node groups are not in main.tf; they are in node_groups.tf, which is why eks_managed_node_groups, self-managed node groups and the Karpenter sub-module each get their own path through the module. The examples/ directory mirrors this: examples/eks-managed-node-group/, examples/self-managed-node-group/, examples/karpenter/, examples/eks-auto-mode/, examples/eks-hybrid-nodes/ and examples/eks-capabilities/. That directory list is the clearest map of what the project supports.

Access entries are handled for you in most cases. The README states that when authentication_mode = "API_AND_CONFIG_MAP" is enabled, EKS creates an access entry for the IAM roles used by managed node groups and Fargate profiles, and that for self-managed node groups and the Karpenter sub-module the project adds the access entry on behalf of users. The README also notes that clusters created before cluster access management support will already have an access entry for the cluster creator, one that was previously invisible when using the aws-auth ConfigMap. That is a migration detail worth reading twice: the entry exists, it just was not shown to you before.

The addons argument is where ordering gets expressed. In the managed node group example the README sets before_compute = true on eks-pod-identity-agent and vpc-cni, which tells the module to install those addons before the node group is created. Get that ordering wrong and nodes come up without a CNI, which is a failure you diagnose from the AWS console rather than from Terraform output.

## Installing the module and applying a first cluster

There is nothing to install in the usual sense. The module is consumed from the Terraform registry, and the README's usage examples pin it with version = "~> 21.0". You need Terraform and AWS credentials with permission to create EKS, IAM and EC2 resources in the target account. The registry page linked from the repository is the source of truth for the current version constraint.

A minimal managed node group cluster looks like this. It declares the module, names the cluster, pins the Kubernetes version, points at an existing VPC and subnets, and defines one node group with AL2023 as the AMI type:

```hcl
module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 21.0"

  name               = "my-cluster"
  kubernetes_version = "1.33"

  enable_cluster_creator_admin_permissions = true

  vpc_id     = "vpc-1234556abcdef"
  subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]

  eks_managed_node_groups = {
    example = {
      ami_type       = "AL2023_x86_64_STANDARD"
      instance_types = ["m5.xlarge"]

      min_size     = 2
      max_size     = 10
      desired_size = 2
    }
  }
}
```

After terraform init and terraform apply, the outputs.tf file in the repository is where the module exposes what it built. The README does not enumerate the outputs inline, so read outputs.tf or the registry documentation for the exact names before you reference them from another module. Expect the control plane creation to take several minutes; EKS does not return immediately.

If you want EKS Auto Mode instead of a node group you manage, the README's Auto Mode example sets compute_config with enabled = true and node_pools = ["general-purpose"]. The README carries a caution about that argument, and it is worth quoting because it is a genuine trap: to disable EKS Auto Mode you must explicitly set enabled = false, and only after applying that can you remove the compute_config block. Removing the block directly will fail to disable it.

## compute_config and the disable path that catches people out

The compute_config block is the one place in this module where the Terraform diff does not match the AWS API's expectations. The README is explicit that removing the block does not turn Auto Mode off. You set enabled = false, apply, and then remove the block in a later change. That is a two-step teardown for a feature that looks like a single boolean, and it means any module that wraps this one has to model the same two-step sequence or it will leave Auto Mode running while reporting success.

The second option in the README is create_auto_mode_iam_resources = true alongside compute_config with only enabled = true. That path creates the IAM resources Auto Mode needs without attaching the built-in node pools, for teams bringing their own node pools. It is a narrower surface, and the README presents it as such.

The Provisioned Control Plane example is separate: control_plane_scaling_config with a tier value. The README lists the valid values as standard, tier-xl, tier-2xl, tier-4xl and tier-8xl. This is for larger workloads that need more control plane capacity. Nothing in the README suggests it changes anything about the data plane, so treat it as a control plane sizing knob and nothing more.

## Where the module is the wrong tool

The module's own documentation draws a boundary. The README states that it aims to document configuring and using the module, and that documentation about EKS itself, including managed node groups, self-managed node groups and Fargate profiles, is better left to AWS and Kubernetes. That is a fair division of labour, but it means the module will not explain why a node group is not joining the cluster. You will be reading the EKS user guide for that.

The second limitation is upgrade coupling. The repository ships a separate upgrade guide for each major version: UPGRADE-17.0.md through UPGRADE-21.0.md. Five guides for five majors is a signal about how often breaking changes land. The README does not document an automated rollback path for a failed module upgrade, and Terraform state does not give you one for free. If your organisation cannot absorb a major version migration on the module's schedule, a thinner hand-written configuration may cost less over time than the module saves.

The third case is scope. If you only need a control plane and plan to manage compute with something outside Terraform, the module's node group, addon and access entry handling is weight you are carrying without using. The same applies if your platform standard is a different provisioning tool entirely and Terraform is only present for a handful of resources.

## How it compares to hand-written resources and to EKS Blueprints

The direct alternative is writing aws_eks_cluster, aws_eks_node_group and aws_eks_access_entry yourself. The difference is not capability, it is ownership of the dependency graph. Hand-written resources give you every argument exactly as the provider exposes it and no upgrade guide to follow, at the cost of wiring IAM roles, security groups and addon ordering yourself. The module makes those choices for you and then asks you to track its major versions.

A second alternative appears in the related searches: terraform aws eks blueprints. EKS Blueprints is a different layer. Where this module creates the cluster and its compute, a blueprints-style approach is about assembling cluster configurations and addon sets on top of a cluster. They are not substitutes. Teams frequently use this module underneath a blueprints layer, which is why the two names show up in the same search results.

A third point of comparison is the Karpenter sub-module inside this repository. The README notes that for the Karpenter sub-module the project adds the access entry on behalf of users, so choosing Karpenter over managed node groups does not push access management back onto you. That is a meaningful difference from assembling Karpenter yourself.

## Maintenance, versioning and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-22, with v21.25.3 released the same day. Releases at that cadence mean the module tracks AWS API changes closely, which cuts both ways: new EKS features appear quickly, and your pinned version drifts from master just as quickly.

The practical upgrade cost is the major version guides. Moving from v20 to v21 means reading docs/UPGRADE-21.0.md and adjusting arguments; the README does not claim the transition is automatic. For patch releases within v21, the version constraint "~> 21.0" from the README's own examples is the intended pattern.

The licence is Apache-2.0, stated in the repository and in the LICENSE file at the top level. That permits commercial use and modification, and it includes a patent grant. It also means the module ships without warranty, so the correctness of what it creates in your account is your responsibility. This is not legal advice; if licence terms matter to your organisation, have counsel read the LICENSE file rather than a summary.

## Conclusion

Adopt it if your cluster, node groups and access entries should live in one Terraform state and you accept the module's release cadence as your upgrade cadence. Do not adopt it if you only need a bare control plane, or if you want to hand-write every aws_eks_* resource and control each argument yourself. Before the first apply, read docs/UPGRADE-21.0.md, check that your required Kubernetes version is accepted by the module's kubernetes_version argument, and confirm whether you need compute_config at all.

## FAQ

### How do I create an EKS cluster with Terraform using this module?

Declare the module with source "terraform-aws-modules/eks/aws" and a version constraint such as "~> 21.0", then supply name, kubernetes_version, vpc_id and subnet_ids. Add an eks_managed_node_groups block if you want compute created alongside the control plane, and run terraform init followed by terraform apply.

### Can Terraform and Kubernetes be used together with this module?

The module assumes they are. It creates the EKS cluster and node groups through Terraform, and the README points readers at the Kubernetes documentation for workload-level questions, so the division is Terraform for cluster infrastructure and kubectl for what runs on it.

### Is this module different from EKS itself?

Yes. EKS is the AWS service; this module is a Terraform wrapper that creates EKS resources. The README states that documentation about EKS features such as managed node groups, self-managed node groups and Fargate profiles is better left to AWS, so the module does not explain the underlying service.

### What is the AWS equivalent of Terraform for provisioning an EKS cluster?

The README does not cover AWS-native provisioning alternatives to Terraform. The module is consumed through the Terraform registry, and the README's examples all use the module block with a source and version.

## Sources

- [License: Apache-2.0](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/LICENSE)
- [Project website](https://registry.terraform.io/modules/terraform-aws-modules/eks/aws)
- [README](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/README.md)
- [Releases](https://github.com/terraform-aws-modules/terraform-aws-eks/releases)
- [terraform-aws-modules/terraform-aws-eks on GitHub](https://github.com/terraform-aws-modules/terraform-aws-eks)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/terraform-aws-modules-terraform-aws-eks