# cloudposse/terraform-aws-eks-cluster architecture

> Architecture diagram of the GitHub repository cloudposse/terraform-aws-eks-cluster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudposse/terraform-aws-eks-cluster
- Repository: https://github.com/cloudposse/terraform-aws-eks-cluster

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Terraform Modules
    subgraph "Terraform Root Module" 
        direction TB
        TF_main["main.tf"]:::module
        TF_vars["variables.tf"]:::module
        TF_outputs["outputs.tf"]:::module
        TF_iam["iam.tf"]:::module
        TF_sg["security-group.tf"]:::module
        TF_auth["auth.tf"]:::module
        TF_context["context.tf"]:::module
        TF_versions["versions.tf"]:::module
    end

    subgraph "Example Usage (complete)" 
        direction TB
        EX_main["examples/complete/main.tf"]:::child
        EX_vars["examples/complete/variables.tf"]:::child
        EX_outputs["examples/complete/outputs.tf"]:::child
        EX_context["examples/complete/context.tf"]:::child
        EX_versions["examples/complete/versions.tf"]:::child
        EX_fixtures["examples/complete/fixtures.us-east-2.tfvars"]:::child
        EX_vpc_cni["examples/complete/vpc-cni.tf"]:::child
    end

    subgraph "Documentation" 
        direction TB
        DOC1["docs/migration-0.45.x+.md"]:::doc
        DOC2["docs/migration-v1-v2.md"]:::doc
        DOC3["docs/migration-v3-v4.md"]:::doc
        DOC4["docs/targets.md"]:::doc
        DOC5["docs/terraform.md"]:::doc
    end

    subgraph "Automated Tests" 
        direction TB
        TEST_go["test/src/examples_complete_test.go"]:::test
        TEST_mk["test/src/Makefile"]:::test
        TEST_mod["test/src/go.mod"]:::test
        TEST_sum["test/src/go.sum"]:::test
    end

    %% AWS Infrastructure
    subgraph "AWS Infrastructure" 
        direction TB
        VPC["VPC"]:::aws
        Subnets["Public & Private Subnets"]:::aws
        IGW["Internet Gateway"]:::aws
        NAT["NAT Gateway"]:::aws
        EKS["aws_eks_cluster\n(Control Plane)"]:::aws
        IAM_role["aws_iam_role\n(eks_service_role)"]:::aws
        OIDC["aws_iam_openid_connect_provider"]:::aws
        KMS["aws_kms_key & alias"]:::aws
        CW["CloudWatch Log Group"]:::aws
        Addons["aws_eks_addon[]"]:::aws
        RBAC["aws_eks_access_entry/\npolicy_association"]:::aws
        SG_master["Security Group\n(Control Plane)"]:::aws
    end

    subgraph "Worker Node Groups" 
        direction TB
        NodeModule["eks-node-group / eks-workers"]:::worker
        NodeRole["IAM Role (nodes)"]:::worker
        ASG["AutoScalingGroups"]:::worker
        NodeSG["Security Group\n(nodes)"]:::worker
    end

    %% Relationships
    TF_main -->|"depends_on"| VPC
    TF_main -->|"depends_on"| Subnets
    TF_main -->|"create"| EKS
    TF_iam -->|"attach"| IAM_role
    TF_iam -->|"create"| OIDC
    TF_sg -->|"configure"| SG_master
    TF_auth -->|"configure"| RBAC
    TF_context -->|"provider"| AWS["Provider aws"]:::aws
    TF_versions -->|"version constraints"| AWS
    TF_main -->|"enable"| Addons
    TF_main -->|"logging"| CW
    TF_main -->|"encryption"| KMS

    VPC --> Subnets
    VPC --> IGW
    Subnets --> NAT
    Subnets --> EKS
    EKS --> SG_master
    EKS --> IAM_role
    EKS --> OIDC
    EKS --> KMS
    EKS --> CW
    EKS --> Addons
    EKS --> RBAC

    NodeModule -->|"uses endpoint & CA data"| EKS
    NodeModule -->|"attach role"| NodeRole
    NodeModule -->|"attach SG"| NodeSG
    NodeRole -->|"assume"| IAM_role
    ASG --> NodeModule

    EX_main --> TF_main
    EX_vars --> TF_vars
    EX_outputs --> TF_outputs

    %% Click Events
    click TF_main "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/main.tf"
    click TF_vars "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/variables.tf"
    click TF_outputs "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/outputs.tf"
    click TF_iam "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/iam.tf"
    click TF_sg "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/security-group.tf"
    click TF_auth "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/auth.tf"
    click TF_context "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/context.tf"
    click TF_versions "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/versions.tf"

    click EX_main "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/examples/complete/main.tf"
    click EX_vars "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/examples/complete/variables.tf"
    click EX_outputs "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/examples/complete/outputs.tf"
    click EX_context "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/examples/complete/context.tf"
    click EX_versions "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/examples/complete/versions.tf"
    click EX_fixtures "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/examples/complete/fixtures.us-east-2.tfvars"
    click EX_vpc_cni "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/examples/complete/vpc-cni.tf"

    click DOC1 "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/docs/migration-0.45.x+.md"
    click DOC2 "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/docs/migration-v1-v2.md"
    click DOC3 "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/docs/migration-v3-v4.md"
    click DOC4 "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/docs/targets.md"
    click DOC5 "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/docs/terraform.md"

    click TEST_go "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/test/src/examples_complete_test.go"
    click TEST_mk "https://github.com/cloudposse/terraform-aws-eks-cluster/tree/main/test/src/Makefile"
    click TEST_mod "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/test/src/go.mod"
    click TEST_sum "https://github.com/cloudposse/terraform-aws-eks-cluster/blob/main/test/src/go.sum"

    %% Styles
    classDef module fill:#D0E8FF,stroke:#024F9D,color:#024F9D,stroke-width:1px;
    classDef child fill:#E8E2FF,stroke:#5D2D91,color:#5D2D91,stroke-width:1px;
    classDef aws fill:#FFF3C4,stroke:#D8A400,color:#8A5700,stroke-width:1px;
    classDef worker fill:#FDE2E4,stroke:#D00000,color:#9A031E,stroke-width:1px;
    classDef doc fill:#E8F6EF,stroke:#056676,color:#056676,stroke-width:1px;
    classDef test fill:#F0F0F0,stroke:#666666,color:#333333,stroke-width:1px;
```
