Skip to content

tfstack/terraform-aws-eks-basic

BranchesTags

Repository files navigation

terraform-aws-eks-basic

A basic Terraform module for creating and managing Amazon EKS (Elastic Kubernetes Service) clusters. Currently supports EC2 and Fargate; AutoMode is scaffolded only (no AutoMode-specific resources yet).

Features

  • Multi-Compute Support: Supports EC2 and Fargate; AutoMode is scaffolded
  • EC2 Managed Node Groups: Full support for EC2 managed node groups with auto-scaling
  • Fargate Profiles: Supported via fargate_profiles and Fargate IAM role creation
  • AutoMode: Placeholder wiring only; no AutoMode-specific resources yet
  • IRSA Support: OIDC provider setup for IAM Roles for Service Accounts
  • EKS Capabilities: Managed ACK and KRO capabilities (optional, default: disabled)
    • ACK: AWS Controllers for Kubernetes - create AWS resources via Kubernetes manifests
    • KRO: Kube Resource Orchestrator - platform engineering abstractions
    • ArgoCD: Scaffolded only (requires AWS Identity Center setup)
  • Access Management: Automatic EKS access entry creation for cluster admins when capabilities are enabled
  • Optional Addons:
    • EBS CSI Driver (optional, default: disabled)
    • AWS Load Balancer Controller (optional, default: disabled)
  • Comprehensive Testing: Includes Terraform test suite

Prerequisites

Name Version
terraform >= 1.6.0
aws >= 6.0
kubernetes ~> 2.30
helm ~> 2.13
tls ~> 4.0

Usage

Basic Example (EC2)

module "eks" {
  source = "tfstack/eks-basic/aws"

  cluster_name    = "my-eks-cluster"
  cluster_version = "1.28"
  vpc_id          = "vpc-12345678"
  subnet_ids      = ["subnet-12345678", "subnet-87654321"]

  # EC2 compute mode (default)
  compute_mode = ["ec2"]

  # Node group configuration
  node_instance_types = ["t3.medium"]
  node_desired_size   = 2
  node_min_size       = 1
  node_max_size       = 3
  node_disk_size      = 20

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

With Optional Addons

module "eks" {
  source = "tfstack/eks-basic/aws"

  cluster_name    = "my-eks-cluster"
  cluster_version = "1.28"
  vpc_id          = "vpc-12345678"
  subnet_ids      = ["subnet-12345678", "subnet-87654321"]

  compute_mode = ["ec2"]

  # Enable optional addons
  enable_ebs_csi_driver   = true
  enable_aws_lb_controller = true

  tags = {
    Environment = "production"
  }
}

With EKS Capabilities

module "eks" {
  source = "tfstack/eks-basic/aws"

  cluster_name    = "my-eks-cluster"
  cluster_version = "1.28"
  vpc_id          = "vpc-12345678"
  subnet_ids      = ["subnet-12345678", "subnet-87654321"]

  compute_mode = ["ec2"]

  # Enable EKS Capabilities for platform engineering
  enable_ack_capability    = true  # AWS Controllers for Kubernetes
  enable_kro_capability    = true  # Kube Resource Orchestrator
  # enable_argocd_capability = false  # Not supported yet - requires Identity Center

  # Grant cluster admin access to IAM users/roles
  cluster_admin_arns = [
    "arn:aws:iam::123456789012:user/admin-user",
    "arn:aws:iam::123456789012:role/admin-role"
  ]

  tags = {
    Environment = "production"
  }
}

Note: When capabilities are enabled, the cluster uses API_AND_CONFIG_MAP authentication mode. You must specify cluster_admin_arns to grant access to IAM users/roles for kubectl access.

tags = { Environment = "production" } }


### Fargate Example

```hcl
module "eks" {
  source = "tfstack/eks-basic/aws"

  cluster_name    = "my-eks-cluster"
  cluster_version = "1.28"
  vpc_id          = "vpc-12345678"
  subnet_ids      = ["subnet-12345678", "subnet-87654321"]

  # Fargate compute mode
  compute_mode = ["fargate"]

  fargate_profiles = {
    default = {
      subnet_ids = ["subnet-12345678"]
      selectors = [
        {
          namespace = "default"
          labels    = {}
        }
      ]
    }
  }

  tags = {
    Environment = "production"
  }
}

Multiple Compute Modes

module "eks" {
  source = "tfstack/eks-basic/aws"

  cluster_name    = "my-eks-cluster"
  cluster_version = "1.28"
  vpc_id          = "vpc-12345678"
  subnet_ids      = ["subnet-12345678", "subnet-87654321"]

  # Use both EC2 and Fargate
  compute_mode = ["ec2", "fargate"]

  # EC2 configuration
  node_instance_types = ["t3.medium"]
  node_desired_size   = 2

  # Fargate configuration
  fargate_profiles = {
    default = {
      subnet_ids = ["subnet-12345678"]
      selectors = [
        {
          namespace = "default"
        }
      ]
    }
  }

  tags = {
    Environment = "production"
  }
}

Examples

Requirements

Name Version
terraform >= 1.6.0
aws >= 6.0
helm ~> 2.13
kubernetes ~> 2.30
tls ~> 4.0

Providers

Name Version
aws 6.28.0
helm 2.17.0
kubernetes 2.38.0
tls 4.1.0

Modules

No modules.

Resources

Name Type
aws_eks_access_entry.cluster_admins resource
aws_eks_access_entry.ec2_nodes resource
aws_eks_access_entry.fargate_pods resource
aws_eks_access_policy_association.cluster_admin_policy resource
aws_eks_addon.ebs_csi_driver resource
aws_eks_addon.pod_identity_agent resource
aws_eks_capability.ack resource
aws_eks_capability.kro resource
aws_eks_cluster.this resource
aws_eks_fargate_profile.default resource
aws_eks_node_group.default resource
aws_iam_openid_connect_provider.eks resource
aws_iam_role.ack_capability resource
aws_iam_role.aws_lb_controller resource
aws_iam_role.ebs_csi_driver resource
aws_iam_role.eks_cluster resource
aws_iam_role.eks_fargate resource
aws_iam_role.eks_nodes resource
aws_iam_role.kro_capability resource
aws_iam_role_policy.aws_lb_controller_waf resource
aws_iam_role_policy.ebs_csi_driver resource
aws_iam_role_policy_attachment.ack_capability resource
aws_iam_role_policy_attachment.aws_lb_controller resource
aws_iam_role_policy_attachment.aws_lb_controller_ec2 resource
aws_iam_role_policy_attachment.eks_cluster_policy resource
aws_iam_role_policy_attachment.eks_fargate_pod_execution_role resource
aws_iam_role_policy_attachment.eks_nodes_cni resource
aws_iam_role_policy_attachment.eks_nodes_ecr resource
aws_iam_role_policy_attachment.eks_nodes_worker resource
helm_release.aws_load_balancer_controller resource
kubernetes_service_account.aws_lb_controller resource
kubernetes_storage_class.ebs_csi_default resource
aws_eks_cluster_auth.this data source
aws_iam_policy_document.ack_capability_assume_role data source
aws_iam_policy_document.aws_lb_controller_assume_role data source
aws_iam_policy_document.ebs_csi_driver_assume_role data source
aws_iam_policy_document.eks_cluster_assume_role data source
aws_iam_policy_document.eks_fargate_assume_role data source
aws_iam_policy_document.eks_nodes_assume_role data source
aws_iam_policy_document.kro_capability_assume_role data source
aws_region.current data source
tls_certificate.eks data source

Inputs

Name Description Type Default Required
access_entry_wait_duration Duration to wait after creating EKS access entries before creating node groups/Fargate profiles. This allows AWS to propagate the access entries. Defaults to 30s. string "30s" no
ack_capability_iam_policy_arns Map of IAM policy ARNs to attach to the ACK capability role. Required for ACK to manage AWS resources (e.g., S3, DynamoDB, IAM). map(string) {} no
ack_capability_role_arn IAM role ARN for ACK capability to create AWS resources. If not provided, AWS will create a default role. string null no
argocd_capability_configuration Configuration JSON for ArgoCD capability. NOTE: ArgoCD not currently supported - requires AWS Identity Center configuration. Scaffolded for future use. string null no
argocd_capability_role_arn IAM role ARN for ArgoCD capability. NOTE: ArgoCD not currently supported - requires AWS Identity Center. Scaffolded for future use. string null no
aws_auth_map_roles List of IAM roles to add to aws-auth ConfigMap for Kubernetes access 
list(object({
    rolearn  = string
    username = string
    groups   = list(string)
  }))
 [] no
aws_auth_map_users List of IAM users to add to aws-auth ConfigMap for Kubernetes access 
list(object({
    userarn  = string
    username = string
    groups   = list(string)
  }))
 [] no
aws_lb_controller_helm_values Additional Helm values for the AWS Load Balancer Controller map(string) {} no
aws_lb_controller_helm_version Version of the AWS Load Balancer Controller Helm chart string "1.7.2" no
cluster_admin_arns List of IAM user/role ARNs to grant cluster admin access via EKS access entries. Only used when capabilities are enabled or cluster_authentication_mode is not CONFIG_MAP. Defaults to empty list. list(string) [] no
cluster_authentication_mode Authentication mode for the EKS cluster. Valid values: CONFIG_MAP, API, API_AND_CONFIG_MAP. Defaults to API_AND_CONFIG_MAP when capabilities are enabled, otherwise CONFIG_MAP. string "CONFIG_MAP" no
cluster_name Name of the EKS cluster string n/a yes
cluster_version Kubernetes version to use for the EKS cluster string n/a yes
compute_mode List of compute modes to enable. Valid values: ec2, fargate, automode list(string) 
[
  "ec2"
]
 no
ebs_csi_driver_version Version of the AWS EBS CSI Driver add-on. If null, uses latest version. string null no
enable_ack_capability Whether to enable AWS Controllers for Kubernetes (ACK) capability bool false no
enable_argocd_capability Whether to enable ArgoCD GitOps capability. NOTE: Not currently supported - requires AWS Identity Center configuration. Scaffolded for future use. bool false no
enable_aws_lb_controller Whether to install AWS Load Balancer Controller bool false no
enable_ebs_csi_driver Whether to install AWS EBS CSI Driver bool false no
enable_kro_capability Whether to enable Kube Resource Orchestrator (KRO) capability bool false no
enable_pod_identity_agent Whether to install EKS Pod Identity Agent add-on bool false no
enabled_cluster_log_types List of control plane logging types to enable list(string) 
[
  "api",
  "audit",
  "authenticator",
  "controllerManager",
  "scheduler"
]
 no
endpoint_public_access Whether the Amazon EKS public API server endpoint is enabled bool true no
fargate_profiles Map of Fargate profiles to create. Key is the profile name. 
map(object({
    subnet_ids = optional(list(string))
    selectors = optional(list(object({
      namespace = string
      labels    = optional(map(string))
    })), [])
    tags = optional(map(string))
  }))
 {} no
kro_capability_role_arn IAM role ARN for KRO capability. If not provided, AWS will create a default role. string null no
node_desired_size Desired number of nodes in the node group number 2 no
node_disk_size Disk size in GiB for worker nodes number 20 no
node_instance_types List of EC2 instance types for the node group list(string) 
[
  "t3.medium"
]
 no
node_labels Key-value map of Kubernetes labels to apply to nodes map(string) {} no
node_max_size Maximum number of nodes in the node group number 3 no
node_min_size Minimum number of nodes in the node group number 1 no
node_remote_access_enabled Whether to enable remote access to nodes bool false no
node_remote_access_security_groups List of security group IDs for remote access list(string) [] no
node_remote_access_ssh_key EC2 SSH key name for remote access string null no
node_subnet_ids Subnet IDs for EKS node groups (should be private subnets only for security). If null, uses subnet_ids. list(string) null no
node_update_max_unavailable Maximum number of nodes unavailable during update number 1 no
pod_identity_agent_version Version of the EKS Pod Identity Agent add-on. If null, uses latest version. string null no
public_access_cidrs List of CIDR blocks that can access the Amazon EKS public API server endpoint list(string) 
[
  "0.0.0.0/0"
]
 no
subnet_ids Subnet IDs for EKS cluster control plane (should include both public and private) list(string) n/a yes
tags Map of tags to apply to all resources map(string) {} no
vpc_id VPC ID where the cluster is deployed string n/a yes

Outputs

Name Description
ack_capability_arn ARN of the ACK capability (when enabled)
argocd_capability_arn ARN of the ArgoCD capability (when enabled). NOTE: ArgoCD not currently supported - scaffolded for future use.
aws_lb_controller_role_arn IAM role ARN for AWS Load Balancer Controller (when enabled)
cluster_arn ARN of the EKS cluster
cluster_auth_token Token to authenticate with the EKS cluster
cluster_ca_certificate Decoded certificate data required to communicate with the cluster
cluster_ca_data Base64 encoded certificate data required to communicate with the cluster
cluster_endpoint Endpoint for EKS control plane
cluster_name Name of the EKS cluster
cluster_version Kubernetes version of the EKS cluster
ebs_csi_driver_role_arn IAM role ARN for EBS CSI Driver (when enabled)
ec2_access_entry_created Whether an access entry was created for EC2 nodes
fargate_access_entry_created Whether an access entry was created for Fargate pods
fargate_profile_arns Map of Fargate profile ARNs (when Fargate mode is enabled)
fargate_role_arn IAM role ARN for Fargate pods (when Fargate mode is enabled)
kro_capability_arn ARN of the KRO capability (when enabled)
node_group_arn ARN of the EKS node group (when EC2 mode is enabled)
node_group_id ID of the EKS node group (when EC2 mode is enabled)
node_group_status Status of the EKS node group (when EC2 mode is enabled)
node_role_arn IAM role ARN for EC2 nodes (when EC2 mode is enabled)
oidc_provider_arn ARN of the EKS OIDC provider
oidc_provider_url URL of the EKS OIDC provider

Connecting to the Cluster

After the cluster is created, configure kubectl:

aws eks update-kubeconfig --name <cluster_name> --region <aws_region>

Verify connection:

kubectl get nodes

Testing

The module includes comprehensive tests using Terraform's test framework. Run tests with:

terraform test

Module Structure

terraform-aws-eks-basic/
├── main.tf              # Core EKS cluster, IAM roles, OIDC provider
├── ec2.tf              # EC2 managed node groups
├── fargate.tf          # Fargate profiles
├── automode.tf         # AutoMode configuration
├── capabilities.tf     # EKS Capabilities (ACK, KRO, ArgoCD)
├── capabilities-iam.tf # IAM roles for EKS Capabilities
├── addons.tf           # Optional addons (EBS CSI, ALB Controller)
├── variables.tf        # Input variables
├── outputs.tf          # Output values
├── versions.tf         # Provider version constraints
├── README.md           # This file
├── tests/
│   └── eks_test.tftest.hcl  # Test suite
└── examples/
    └── basic/          # Basic usage example

License

MIT License - see LICENSE file for details.

About

Simple EKS cluster Terraform module

registry.terraform.io/modules/tfstack/eks-basic/aws/latest

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v1.0.2 Latest
Jan 26, 2026
+ 2 releases

Packages

No packages published

Contributors 2

  •  
  •  

Languages