# awslabs/cdk-eks-blueprints architecture

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

- Interactive diagram: https://gitdiagram.com/awslabs/cdk-eks-blueprints
- Repository: https://github.com/awslabs/cdk-eks-blueprints

## Overview

##### Project type and purpose
- This is a TypeScript-based AWS CDK library (“eks‐blueprints”) that provides a prescriptive, extensible framework for provisioning and bootstrapping Amazon EKS clusters with add-ons, teams, GitOps pipelines, and operational tooling.
- It’s not a user-facing web app but an Infrastructure-as-Code (IaC) framework packaged as an NPM module. It exposes constructs, builders, plug-in add-ons, resource providers, cluster providers, and pipelines to automate the creation of fully operational EKS clusters.

##### File structure
- Top-level:
- bin/main.ts – example CDK entrypoint for users
- lib/ – core library code subdivided into logical modules (addons, builders, cluster-providers, pipelines, resource-providers, spi, stacks, teams, utils)
- examples/ – sample projects showing how to consume the library
- docs/ and mkdocs.yml – site documentation source
- ci/ and .github/workflows – continuous integration and documentation pipelines
- test/ – unit tests validating each add-on, provider, and utility
- Configuration: package.json, tsconfig.json, cdk.json, Makefile, devcontainer/ – developer tooling
- The “spi” directory defines extension contracts (ClusterAddOn, TeamContract, etc.), indicating a plug-in architecture.

##### README-driven insights
- The library uses a Builder pattern (`EksBlueprint.builder()…build(app, name)`) to assemble clusters with configurable add-ons, cluster providers (e.g., managed node groups, Fargate), resource providers (VPC, IAM, S3), and team namespaces/policies.
- It provisions AWS constructs via CDK → CloudFormation and then installs Kubernetes add-ons (ArgoCD, Calico, Metrics Server, etc.) into the cluster for GitOps and ops automation.

## Diagram (Mermaid)

```mermaid
graph TD
UserCDK["User CDK App / CLI"]:::typescript

subgraph "eks-blueprints Library"
  direction TB
  Builder["Builder & Fluent API"]:::typescript
  click Builder "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/builders/index.ts"
  SPI["SPI Contracts"]:::typescript
  click SPI "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/spi/addon-contracts.ts"

  subgraph "Builders Modules"
    direction TB
    AutoModeB["AutoMode Builder"]:::typescript
    click AutoModeB "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/builders/automode-builder.ts"
    BedrockB["Bedrock Builder"]:::typescript
    click BedrockB "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/builders/bedrock-builder.ts"
    GPUB["GPU Builder"]:::typescript
    click GPUB "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/builders/gpu-builder.ts"
    GravitonB["Graviton Builder"]:::typescript
    click GravitonB "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/builders/graviton-builder.ts"
    ObservB["Observability Builder"]:::typescript
    click ObservB "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/builders/observability-builder.ts"
    WindowsB["Windows Builder"]:::typescript
    click WindowsB "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/builders/windows-builder.ts"
  end

  subgraph "Add-On Plug-ins"
    direction TB
    ArgoCD["Add-On: ArgoCD"]:::k8s
    click ArgoCD "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/addons/argocd/index.ts"
    Calico["Add-On: Calico"]:::k8s
    click Calico "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/addons/calico/index.ts"
    Metrics["Add-On: Metrics Server"]:::k8s
    click Metrics "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/addons/metrics-server/index.ts"
    ALB["Add-On: AWS LB Controller"]:::k8s
    click ALB "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/addons/aws-loadbalancer-controller/index.ts"
    XRay["Add-On: X-Ray"]:::k8s
    click XRay "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/addons/xray/index.ts"
  end

  subgraph "Cluster Providers"
    direction TB
    CoreCP["Cluster Provider"]:::typescript
    click CoreCP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/index.ts"
    ASGCP["ASG Cluster Provider"]:::typescript
    click ASGCP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/asg-cluster-provider.ts"
    FargateCP["Fargate Cluster Provider"]:::typescript
    click FargateCP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/fargate-cluster-provider.ts"
    GenericCP["Generic Cluster Provider"]:::typescript
    click GenericCP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/generic-cluster-provider.ts"
    GenericCP2["Generic CP v2"]:::typescript
    click GenericCP2 "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/generic-cluster-provider-v2.ts"
    ImportCP["Import Cluster Provider"]:::typescript
    click ImportCP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/import-cluster-provider.ts"
    MNGCP["Managed Node Group CP"]:::typescript
    click MNGCP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/mng-cluster-provider.ts"
    AutoModeCP["AutoMode CP"]:::typescript
    click AutoModeCP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/cluster-providers/automode-cluster-provider.ts"
  end

  subgraph "Resource Providers"
    direction TB
    RPIndex["Resource Providers"]:::typescript
    click RPIndex "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/index.ts"
    VPC["VPC"]:::aws
    click VPC "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/vpc.ts"
    IAM["IAM"]:::aws
    click IAM "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/iam.ts"
    S3RP["S3"]:::aws
    click S3RP "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/s3.ts"
    EFS["EFS"]:::aws
    click EFS "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/efs.ts"
    KMS["KMS Key"]:::aws
    click KMS "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/kms-key.ts"
    HZone["Hosted Zone"]:::aws
    click HZone "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/hosted-zone.ts"
    Cert["Certificate"]:::aws
    click Cert "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/certificate.ts"
    IPV6V["IPv6 VPC"]:::aws
    click IPV6V "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/ipv6-vpc.ts"
    IPV6I["IPv6 IAM"]:::aws
    click IPV6I "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/resource-providers/ipv6-iam.ts"
  end

  subgraph "Pipelines"
    direction TB
    Pipelines["Pipelines"]:::typescript
    click Pipelines "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/pipelines/index.ts"
    CodePipeline["CodePipeline Integrations"]:::external
    click CodePipeline "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/pipelines/code-pipeline.ts"
  end

  subgraph "Stacks & Constructs"
    direction TB
    Stacks["Stacks"]:::typescript
    click Stacks "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/stacks/index.ts"
    EKSCons["EKS Blueprint Construct"]:::typescript
    click EKSCons "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/stacks/eks-blueprint-construct.ts"
    EKSStack["EKS Blueprint Stack"]:::typescript
    click EKSStack "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/stacks/eks-blueprint-stack.ts"
  end

  subgraph "Teams"
    direction TB
    Teams["Teams"]:::typescript
    click Teams "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/teams/index.ts"
    AWSBatch["AWS Batch Team"]:::typescript
    click AWSBatch "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/teams/aws-batch/aws-batch-on-eks-team.ts"
    BedrockTeam["Bedrock Team"]:::typescript
    click BedrockTeam "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/teams/bedrock-team/bedrock-team.ts"
    EMRTeam["EMR on EKS Team"]:::typescript
    click EMRTeam "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/teams/emr-on-eks-team.ts"
  end

  Utils["Utilities"]:::typescript
  click Utils "https://github.com/awslabs/cdk-eks-blueprints/blob/main/lib/utils/index.ts"
end

subgraph "AWS CDK + CloudFormation"
  direction TB
  CDKEngine["AWS CDK Engine"]:::external
  CFN["AWS CloudFormation"]:::aws
end

subgraph "Deployed Environment"
  direction TB
  VPCsvc["VPC"]:::aws
  IAMsvc["IAM"]:::aws
  S3svc["S3"]:::aws
  EksSvc["EKS Cluster"]:::aws
  subgraph "Kubernetes Cluster"
    direction TB
    ArgoRuntime["ArgoCD Runtime"]:::k8s
    CalicoRT["Calico Runtime"]:::k8s
    MetricsRT["Metrics Server"]:::k8s
    ALBRT["AWS LB Controller Pod"]:::k8s
    XRayRT["X-Ray Daemon"]:::k8s
  end
end

GitRepo["Git Repository"]:::external
CI["CI/CD Pipeline"]:::external

UserCDK -->|imports & invokes| Builder
Builder -->|uses| SPI
Builder -->|plugs in| ArgoCD
Builder -->|plugs in| Calico
Builder -->|plugs in| Metrics
Builder -->|plugs in| ALB
Builder -->|plugs in| XRay
Builder -->|selects| CoreCP
Builder -->|selects| RPIndex
Builder -->|configures| Teams
Builder -->|uses utils| Utils
Builder -->|defines constructs in| Stacks
Builder -->|adds pipelines| Pipelines

Builder --> CDKEngine
CDKEngine --> CFN
CFN --> VPCsvc
CFN --> IAMsvc
CFN --> S3svc
CFN --> EksSvc

EksSvc -->|installs| ArgoRuntime
EksSvc -->|installs| CalicoRT
EksSvc -->|installs| MetricsRT
EksSvc -->|installs| ALBRT
EksSvc -->|installs| XRayRT

GitRepo -->|triggers| CI
CI -->|runs CDK App| UserCDK
CI -->|syncs| ArgoRuntime

classDef typescript fill:#D0E8FF,stroke:#0366D6;
classDef aws fill:#FFEBCD,stroke:#D2691E;
classDef k8s fill:#E6FFED,stroke:#22863A;
classDef external fill:#F0F0F0,stroke:#666666;
```
