# lablabs/terraform-aws-eks-universal-addon architecture

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

- Interactive diagram: https://gitdiagram.com/lablabs/terraform-aws-eks-universal-addon
- Repository: https://github.com/lablabs/terraform-aws-eks-universal-addon

## Overview

##### Project Type and Purpose
- This is an open-source Terraform module for deploying a “universal addon” into an AWS EKS cluster.
- It provides two main flavors: a plain Helm chart deployment and an ArgoCD Application deployment.
- It also optionally configures IAM roles/policies via IRSA (IAM Roles for Service Accounts) and OIDC providers to give Kubernetes workloads AWS permissions.

##### File Structure Analysis
- Root
- main.tf, variables.tf, outputs.tf – orchestrate module inputs/outputs and call sub-modules.
- addon.tf, addon-irsa.tf, addon-oidc.tf – entry points for the three module entry-points.
- .github/, scripts/, docs/, examples/ – CI/CD definitions, helper scripts, documentation, and sample usage.
- modules/
- modules/addon – core Helm/ArgoCD deployment logic.
- modules/addon-irsa – IRSA IAM role & policy logic.
- modules/addon-oidc – OIDC provider & role logic.
- examples/basic – a standalone Terraform configuration using the module.
- CI/CD and linters under .github/workflows, pre-commit, renovate, etc.

##### Key Architecture Insights from README
- Supports multiple deployment methods: Helm (via Terraform Helm provider), ArgoCD Application (via Kubernetes manifest or Helm-based ArgoCD install).
- IRSA & OIDC sub-modules allow attaching IAM policies to service accounts.
- Uses Terraform >=1.5.0, AWS, Helm & Kubernetes providers, and a utils provider for YAML merging.
- Template-sync GitHub Action keeps scaffold ready for new addons.

a. Main Components
- User/CI: runs “terraform apply” using example/root module.
- Terraform Core: parses .tf files, loads providers, applies modules.
- Providers
- AWS Provider → manages IAM roles, OIDC provider, etc.
- Kubernetes Provider → applies CRDs when using manifest mode.
- Helm Provider → installs Helm chart or ArgoCD application via Helm.
- Sub-modules
- addon module → orchestrates chart installation or ArgoCD manifest.
- addon-irsa module → creates IAM role, attaches policies, annotates SA.
- addon-oidc module → configures OIDC provider, role, policies.
- AWS Account
- EKS Cluster (with OIDC issuer endpoint).
- IAM (roles, policies, OIDC provider).
- Kubernetes Cluster
- Namespaces, ServiceAccount (annotated for IRSA).
- HelmRelease or ArgoCD Application resources.

b. Interactions
1. Terraform → AWS Provider → create IAM roles & OIDC provider (modules/addon-irsa & addon-oidc).
2. Terraform → Kubernetes/Helm Provider → install Helm chart or apply ArgoCD CRD (modules/addon).
3. IAM role annotations on ServiceAccount allow pods to assume AWS permissions at runtime.
4. Optional ArgoCD operator pulls chart from repo and deploys into cluster.

c. Architectural Patterns
- Layered module design: root module delegates to specialized sub-modules (Separation of concerns).
- Infra-as-Code with Provider plugins (AWS/Kubernetes/Helm).
- Template pattern to scaffold new addons via GitHub template-sync.

d. Technologies & Libraries
- Terraform core, AWS provider (~>5), Kubernetes provider (>=2.20), Helm provider (>=2.6).
- cloudposse/utils for deep_merge_yaml.
- GitHub Actions and pre-commit for CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Example Usage
    subgraph "Example Usage" 
        direction TB
        ExMain["main.tf"]:::example
        ExBase["base.tf"]:::example
        ExProviders["providers.tf"]:::example
        ExVersions["versions.tf"]:::example
        ExLock[".terraform.lock.hcl"]:::example
    end

    %% User/CI
    UserCI["User / CI"]:::external

    %% Terraform Core
    subgraph "Root Terraform Module" 
        direction TB
        TFMain["main.tf"]:::terraform
        TFVars["variables.tf"]:::terraform
        TFOut["outputs.tf"]:::terraform
        AddonEntry["addon.tf"]:::terraform
        IRSAEntry["addon-irsa.tf"]:::terraform
        OIDCEntry["addon-oidc.tf"]:::terraform
    end

    %% Providers
    subgraph "Terraform Providers" 
        direction TB
        AWSProv["AWS Provider"]:::aws
        K8sProv["Kubernetes Provider"]:::k8s
        HelmProv["Helm Provider"]:::k8s
    end

    %% Sub-modules
    subgraph "modules/addon" 
        direction TB
        AddonHelm["helm.tf"]:::terraform
        AddonArgo["argo.tf"]:::terraform
        AddonArgoHelm["argo-helm.tf"]:::terraform
        AddonVars["variables.tf"]:::terraform
        AddonOut["outputs.tf"]:::terraform
        AddonVal["validations.tf"]:::terraform
        AddonVer["versions.tf"]:::terraform
    end

    subgraph "modules/addon-irsa" 
        direction TB
        IRSAIam["iam-irsa.tf"]:::terraform
        IPRole["iam-pod-identity.tf"]:::terraform
        IRSAOut["outputs.tf"]:::terraform
        IRSAVars["variables.tf"]:::terraform
        IRSAVld["validations.tf"]:::terraform
        IRSAMig["migrations.tf"]:::terraform
        IRSAVer["versions.tf"]:::terraform
    end

    subgraph "modules/addon-oidc" 
        direction TB
        OIDCIAM["iam.tf"]:::terraform
        OIDCOut["outputs.tf"]:::terraform
        OIDCVars["variables.tf"]:::terraform
        OIDCVal["validations.tf"]:::terraform
        OIDCVer["versions.tf"]:::terraform
    end

    %% AWS Account
    subgraph "AWS Account" 
        direction TB
        EKS["EKS Cluster"]:::aws
        IAM["IAM Roles & Policies"]:::aws
        OIDCProv["OIDC Provider"]:::aws
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster" 
        direction TB
        NSSA["Namespace & ServiceAccount"]:::k8s
        K8sRelease["HelmRelease / ArgoCD Application"]:::k8s
    end

    %% CI/CD and Utilities
    subgraph "CI/CD & Linters" 
        direction TB
        WFValidate[".github/workflows/validate.yaml"]:::ci
        WFPre[".github/workflows/pre-commit.yaml"]:::ci
        WFRelease[".github/workflows/release-drafter.yaml"]:::ci
        WFRenovate[".github/workflows/renovate.yaml"]:::ci
        WFTemplate[".github/workflows/template-sync.yaml"]:::ci
    end

    subgraph "Documentation" 
        direction TB
        DocsInputs["docs/.inputs.md"]:::docs
        DocsAddon["docs/.addon.md"]:::docs
        DocsFooter["docs/.footer.md"]:::docs
    end

    subgraph "Scripts" 
        direction TB
        SyncScript["scripts/sync-variables.py"]:::scripts
    end

    %% Connections
    ExMain -->|invokes| TFMain
    UserCI -->|runs terraform apply| TFMain
    TFMain --> AWSProv
    TFMain --> K8sProv
    TFMain --> HelmProv

    AWSProv -->|create IAM Role & Policy| IRSAIam
    AWSProv -->|create OIDC Provider| OIDCIAM
    AWSProv -->|provision resources| EKS
    AWSProv -->|manage| IAM
    AWSProv -->|configure| OIDCProv

    K8sProv -->|apply manifest| AddonArgo
    HelmProv -->|install Helm chart| AddonHelm

    AddonHelm -->|deploy chart| K8sRelease
    AddonArgo -->|deploy ArgoCD App| K8sRelease

    IRSAIam -->|annotate SA| NSSA
    IPRole -->|attach identity| NSSA

    OIDCIAM -->|configure| OIDCProv
    OIDCOut -->|outputs| OIDCProv

    %% Styles and classes
    classDef terraform fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef aws fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef k8s fill:#E8F5E9,stroke:#388E3C,color:#388E3C;
    classDef external fill:#F3F4F6,stroke:#9CA3AF,color:#374151;
    classDef example fill:#F0F9FF,stroke:#0366d6,color:#0366d6;
    classDef ci fill:#FFF8E1,stroke:#F9A825,color:#F9A825;
    classDef docs fill:#ECEFF1,stroke:#607D8B,color:#455A64;
    classDef scripts fill:#FBE9E7,stroke:#D84315,color:#BF360C;

    %% Click events
    click TFMain "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/main.tf"
    click TFVars "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/variables.tf"
    click TFOut "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/outputs.tf"
    click AddonEntry "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/addon.tf"
    click IRSAEntry "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/addon-irsa.tf"
    click OIDCEntry "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/addon-oidc.tf"

    click AddonHelm "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon/helm.tf"
    click AddonArgo "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon/argo.tf"
    click AddonArgoHelm "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon/argo-helm.tf"
    click AddonVars "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon/variables.tf"
    click AddonOut "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon/outputs.tf"
    click AddonVal "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon/validations.tf"
    click AddonVer "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon/versions.tf"

    click IRSAIam "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-irsa/iam-irsa.tf"
    click IPRole "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-irsa/iam-pod-identity.tf"
    click IRSAOut "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-irsa/outputs.tf"
    click IRSAVars "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-irsa/variables.tf"
    click IRSAVld "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-irsa/validations.tf"
    click IRSAMig "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-irsa/migrations.tf"
    click IRSAVer "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-irsa/versions.tf"

    click OIDCIAM "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-oidc/iam.tf"
    click OIDCOut "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-oidc/outputs.tf"
    click OIDCVars "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-oidc/variables.tf"
    click OIDCVal "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-oidc/validations.tf"
    click OIDCVer "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/modules/addon-oidc/versions.tf"

    click ExMain "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/examples/basic/main.tf"
    click ExBase "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/examples/basic/base.tf"
    click ExProviders "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/examples/basic/providers.tf"
    click ExVersions "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/examples/basic/versions.tf"
    click ExLock "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/examples/basic/.terraform.lock.hcl"

    click WFValidate "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/.github/workflows/validate.yaml"
    click WFPre "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/.github/workflows/pre-commit.yaml"
    click WFRelease "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/.github/workflows/release-drafter.yaml"
    click WFRenovate "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/.github/workflows/renovate.yaml"
    click WFTemplate "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/.github/workflows/template-sync.yaml"

    click DocsInputs "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/docs/.inputs.md"
    click DocsAddon "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/docs/.addon.md"
    click DocsFooter "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/docs/.footer.md"

    click SyncScript "https://github.com/lablabs/terraform-aws-eks-universal-addon/blob/main/scripts/sync-variables.py"
```
