How cloudposse/terraform-aws-eks-cluster works
Project Type and Purpose
• This is a Terraform “root” module (terraform-aws-eks-cluster) whose purpose is to provision a fully configured Amazon EKS (Elastic Kubernetes Service) control‐plane on AWS, including IAM roles, security groups, logging, encryption, and integration with add-ons (e.g., VPC CNI, CoreDNS).
File Structure Analysis
• Top‐Level Terraform files (main.tf, variables.tf, outputs.tf, iam.tf, security-group.tf, auth.tf, context.tf, versions.tf) define the core AWS EKS cluster, IAM roles/policies, security groups, logging, KMS encryption, and inputs/outputs.
• examples/complete shows a consuming root‐module invocation wiring together Label, VPC, Subnets, Node Groups, and this EKS cluster module.
• docs/ contains migration guides and target-specific documentation.
• test/src contains automated end-to-end tests (bats, Terratest).
a. Terraform Root Module
• Provider: aws (>=5.74), tls (>=3.1).
• Child Modules (in examples):
• cloudposse/label → generates naming context
• cloudposse/vpc/aws → VPC, IGW
• cloudposse/dynamic-subnets/aws → Public & Private Subnets, NAT Gateway
• cloudposse/eks-node-group/aws (or eks-workers) → Worker node AutoScalingGroups
• Resources in this module:
• aws_eks_cluster (Control Plane)
• aws_iam_role + aws_iam_role_policy_attachment (EKS service role)
• aws_iam_openid_connect_provider (OIDC)
• aws_kms_key & aws_kms_alias (Cluster encryption)
• aws_cloudwatch_log_group (Control plane logging)
• aws_eks_addon[] (CNI, CoreDNS, kube-proxy)
• aws_eks_access_entry & aws_eks_access_policy_association (RBAC via AWS API)
• Security group rules for master security group ingress (from CIDRs & worker SGs)
b. AWS Infrastructure
• VPC with public and private subnets
• Internet Gateway & NAT Gateway for outbound connectivity
• EKS Control Plane in private subnets (endpoint_public_access / private_access settings)
• Managed Security Group attached to control plane ENIs
• IAM OIDC Provider & IAM Role for control plane
• KMS key for etcd encryption
• CloudWatch log group for control-plane logs
c. Worker Node Groups (External Modules)
• Managed Node Groups (eks-node-group) or Self-Managed (eks-workers) in private subnets
• IAM Role for nodes, associated with cluster via access_entries_for_nodes
• AutoScalingGroups, Launch Templates, Security Groups
d. -On Integrations
• EKS Add-ons (vpc-cni, kube-proxy, coredns) installed post‐cluster creation
• Dependencies (addons_depends_on → node groups)
Relationships & Data Flows
• “Create VPC” → VPC
• “Create Subnets” → Subnets & NAT Gateway
• “Create EKS Cluster” → EKS Control Plane
• “Attach IAM Role” → IAM (Service Role, OIDC Provider)
• “Enable Add-ons” → EKS Add-on API
• “Configure Logging” → CloudWatch
• “Configure Encryption” → KMS
• “Configure Access Entries” → EKS RBAC via AWS API
• That Worker Modules consume cluster endpoint, CA data, SG ID
Architectural Patterns & Principles
• Declarative Infrastructure as Code (Terraform)
• Separation of concerns: network, compute (control plane vs. nodes), IAM, logging, encryption, RBAC
• Immutable control plane vs. autoscaling worker pools
• Dependency management via Terraform (depends_on for addon install order)
• Modular design: core cluster module + reusable component modules
Essential Elements
• Component boundaries (Terraform module vs. AWS)
• Provider block (aws) and version requirement
• Clear labels for each AWS resource & module
• Annotations for key Terraform variables/outputs (e.g., subnet_ids, cluster_endpoint, node_role_arn)