# csantanapr/terraform-eks-cilium architecture

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

- Interactive diagram: https://gitdiagram.com/csantanapr/terraform-eks-cilium
- Repository: https://github.com/csantanapr/terraform-eks-cilium

## Overview

##### Project Type and Purpose
- This is an “Infrastructure-as-Code” project using Terraform to provision AWS resources (VPC and EKS) and install Cilium with Prefix Delegation.
- The goal is to create a highly available EKS cluster, configure Cilium as the CNI, and enable each node to host >29 pods via AWS Prefix Delegation.

##### File Structure
- Top-level:
- 1_vpc/ – Terraform module to provision the VPC, subnets, route tables, IGW, NAT Gateway, etc.
- 2_eks/ – Terraform module to provision the EKS control plane, node groups, Helm values for Cilium (values_cilium.yaml), and bootstrap settings.
- values.yaml – global Helm overrides.
- Scripts & Config:
- max-pods-calculator.sh – helper to compute pod capacity per instance type.
- .gitignore – standard.

##### Gather Insights from README
- Shows sequence: “terraform apply” in 1_vpc, then in 2_eks with custom vars.
- Describes Cilium components (operator, daemonset, hubble, relay, UI).
- Verifies node allocatable pods > default.
- Uses AWS CLI, kubectl, Terraform CLI, and Cilium CLI.

– Developer Workstation (Terraform CLI, AWS CLI, kubectl, Cilium CLI)
– Terraform State & Modules (1_vpc, 2_eks)
– AWS VPC
- Public Subnets + Internet Gateway
- Private Subnets + NAT Gateway
- Route Tables
– EKS Control Plane (managed by AWS)
– EKS Worker Node Group(s)
– Cilium CNI
- cilium-operator (Deployment)
- cilium DaemonSet (data-plane)
- Hubble components (UI, Relay)
– Sample Application (100 nginx pods)
- Developer Workstation → Terraform → AWS VPC & EKS
- EKS Control Plane ↔ Worker Nodes (Kube API)
- Worker Nodes ↔ AWS Prefix Delegation APIs (to allocate /28 prefixes per node)
- Worker Nodes (Cilium agent) ↔ Cilium operator (control-plane)
- Cilium Data-Plane ↔ Pod networking (VXLAN, IPAM)
- kubectl / Cilium CLI → EKS Control Plane (commands & status checks)
c. Architectural Patterns & Design Principles:
- Infrastructure as Code (IaC) layered modules (VPC first, then EKS)
- Kubernetes control-plane separation from data-plane
- CNI offloading pod networking to AWS Prefix Delegation
- Declarative configuration via Helm values
d. Key Technologies / Frameworks:
- Terraform (modules, providers)
- AWS Services: VPC, EKS, EC2 (Node Groups), IAM, CloudWatch, etc.
- Kubernetes
- Cilium (operator, daemonset, Hubble)
- Helm (values.yaml, values_cilium.yaml)
- AWS CLI, kubectl, Cilium CLI

##### Diagramming Conventions
- IaC layer (Terraform) in blue
- AWS infra layer in orange
- Kubernetes layer in green
- CNI / Cilium layer in purple
- Rectangles for compute (EC2 nodes, pods)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% IaC Layer
    subgraph "IaC Layer"
        direction TB
        Dev["Developer Workstation<br/>(Terraform CLI, AWS CLI,<br/>kubectl, Cilium CLI)"]:::developer
        VPCMod["Terraform 1_vpc Module"]:::iac
        EKSMod["Terraform 2_eks Module"]:::iac
        GlobalVals["Global Helm Overrides<br/>(values.yaml)"]:::iac
        CiliumVals["Cilium Helm Values<br/>(values_cilium.yaml)"]:::iac
        PodCalc["Pod Capacity Calculator<br/>(max-pods-calculator.sh)"]:::iac
        Readme["Project Documentation<br/>(README.md)"]:::iac
        Gitignore["Git Ignore Configuration<br/>(.gitignore)"]:::iac
    end

    %% AWS Infrastructure Layer
    subgraph "AWS Infrastructure" 
        direction TB
        VPC["AWS VPC"]:::aws
        subgraph "VPC Networking"
            direction TB
            PubSub["Public Subnets<br/>+ IGW"]:::aws
            PrivSub["Private Subnets<br/>+ NAT Gateway"]:::aws
            RT["Route Tables"]:::aws
        end
        EKSCP["EKS Control Plane"]:::aws
        Nodes["EKS Worker Node Group"]:::aws
    end

    %% Kubernetes Layer
    subgraph "Kubernetes Layer"
        direction TB
        EKSCP -->|Kube API| Nodes
    end

    %% Cilium CNI Layer
    subgraph "Cilium CNI" 
        direction TB
        CiliumOp["cilium-operator<br/>(Deployment)"]:::cni
        CiliumDS["cilium DaemonSet<br/>(Data-Plane)"]:::cni
        HubbleRelay["Hubble Relay"]:::cni
        HubbleUI["Hubble UI"]:::cni
    end

    %% Sample Application
    App["Sample App<br/>(100 nginx pods)"]:::k8s

    %% Provisioning Flow
    Dev -->|"terraform apply"| VPCMod
    Dev -->|"terraform apply"| EKSMod
    VPCMod -->|provisions| VPC
    VPC --> PubSub
    VPC --> PrivSub
    VPC --> RT
    EKSMod -->|provisions| EKSCP
    EKSMod -->|provisions| Nodes

    %% Runtime Flow
    Nodes -->|"AWS Prefix Delegation"| AWSIPAM["AWS IPAM"]:::aws
    Nodes -->|"runs Cilium agent"| CiliumOp
    CiliumOp -->|"controls"| CiliumDS
    CiliumDS -.->|"pod networking (VXLAN/IPAM)"| App
    Dev -->|kubectl / Cilium CLI| EKSCP
    Dev -->|kubectl apply| App

    %% Group relationships
    Nodes --- CiliumDS
    CiliumDS --- HubbleRelay
    HubbleRelay --- HubbleUI

    %% Click Events
    click VPCMod "https://github.com/csantanapr/terraform-eks-cilium/tree/main/1_vpc/"
    click EKSMod "https://github.com/csantanapr/terraform-eks-cilium/tree/main/2_eks/"
    click CiliumVals "https://github.com/csantanapr/terraform-eks-cilium/blob/main/2_eks/values_cilium.yaml"
    click GlobalVals "https://github.com/csantanapr/terraform-eks-cilium/blob/main/values.yaml"
    click PodCalc "https://github.com/csantanapr/terraform-eks-cilium/blob/main/max-pods-calculator.sh"
    click Readme "https://github.com/csantanapr/terraform-eks-cilium/blob/main/README.md"
    click Gitignore "https://github.com/csantanapr/terraform-eks-cilium/blob/main/.gitignore"

    %% Styles
    classDef iac fill:#D6E9F8,stroke:#4A7EBB,color:#000;
    classDef aws fill:#FAD7A0,stroke:#E59866,color:#000;
    classDef k8s fill:#D5F5E3,stroke:#52BE80,color:#000;
    classDef cni fill:#E8DAEF,stroke:#A569BD,color:#000;
    classDef developer fill:#AED6F1,stroke:#2980B9,color:#000;
```
