# abukalam2909/eks_eso_poc architecture

> Architecture diagram of the GitHub repository abukalam2909/eks_eso_poc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abukalam2909/eks_eso_poc
- Repository: https://github.com/abukalam2909/eks_eso_poc

## Overview

This repository is an infrastructure-as-code POC for delivering AWS Secrets Manager values to pods in a private EKS cluster. The main workflow is rotation in Secrets Manager, ESO retrieval through AWS identity and private endpoints, synchronization into an encrypted Kubernetes Secret, and read-only mounting by the app. Separate branches harden network access, operator access, pod policy, and secret access monitoring. Edges reflect the README’s architecture and controls; most implementation files were not sampled, so their internal wiring is not asserted.

Main entry points: [`kubernetes/eso/values.yaml`](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/eso/values.yaml) (ESO controller), [`kubernetes/app/externalsecret.yaml`](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/externalsecret.yaml) (Kubernetes Secret), [`terraform/endpoints.tf`](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/endpoints.tf) (VPC endpoints), [`terraform/admin_host.tf`](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/admin_host.tf) (SSM admin host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_aws["AWS secrets and identity"]
  node_secrets[("Secrets Manager")]
  node_app_role["App IAM role<br/>[iam_app.tf]"]
  node_kms["KMS encryption<br/>[kms.tf]"]
end

subgraph group_network["Private network and cluster"]
  node_eks["Private EKS<br/>[eks.tf]"]
  node_endpoints["VPC endpoints<br/>[endpoints.tf]"]
  node_admin["SSM admin host<br/>[admin_host.tf]"]
  node_netpol["Network policies<br/>[networkpolicy.yaml]"]
  node_eso_netpol["ESO network policy<br/>[networkpolicy.yaml]"]
end

subgraph group_delivery["Kubernetes secret delivery"]
  node_eso["ESO controller<br/>[values.yaml]"]
  node_reader_sa["Secret-reader SA"]
  node_external_secret["ExternalSecret"]
  node_secret_store["SecretStore<br/>[secretstore.yaml]"]
  node_k8s_secret[("Kubernetes Secret")]
  node_app["App pod<br/>[deployment.yaml]"]
end

subgraph group_policy["Access and admission controls"]
  node_rbac["ESO RBAC<br/>[rbac.yaml]"]
  node_gatekeeper["Gatekeeper policies"]
  node_constraints["Policy constraints"]
  node_namespace["App namespace<br/>[namespaces.yaml]"]
end

subgraph group_operations["Rotation and detection"]
  node_rotation["Rotation Lambda<br/>[app.py]"]
  node_rotation_config["Rotation schedule<br/>[rotation.tf]"]
  node_cloudtrail["CloudTrail<br/>[cloudtrail.tf]"]
  node_detection["Secret-read alert<br/>[detection.tf]"]
end

node_operator(("Operator"))

node_operator -->|"tunnels through"| node_admin
node_admin -->|"accesses privately"| node_eks
node_rotation_config -->|"schedules"| node_rotation
node_rotation -->|"rotates value"| node_secrets
node_eso -->|"mints token for"| node_reader_sa
node_reader_sa -->|"assumes role"| node_app_role
node_eso -->|"reads through"| node_endpoints
node_endpoints -->|"connects privately"| node_secrets
node_eso -->|"syncs value"| node_k8s_secret
node_secret_store -->|"targets"| node_secrets
node_external_secret -->|"references"| node_secret_store
node_k8s_secret -->|"mounts read-only"| node_app
node_kms -->|"encrypts at rest"| node_k8s_secret
node_netpol -->|"restricts traffic"| node_app
node_eso_netpol -->|"restricts traffic"| node_eso
node_rbac -->|"limits permissions"| node_eso
node_gatekeeper -->|"enforces constraints"| node_constraints
node_constraints -->|"guards workload"| node_namespace
node_cloudtrail -->|"feeds alerting"| node_detection
node_detection -->|"alerts on unexpected reads"| node_secrets

click node_app_role "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/iam_app.tf"
click node_kms "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/kms.tf"
click node_eks "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/eks.tf"
click node_endpoints "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/endpoints.tf"
click node_admin "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/admin_host.tf"
click node_eso "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/eso/values.yaml"
click node_reader_sa "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/serviceaccounts.yaml"
click node_external_secret "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/externalsecret.yaml"
click node_secret_store "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/secretstore.yaml"
click node_k8s_secret "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/externalsecret.yaml"
click node_app "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/deployment.yaml"
click node_netpol "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/networkpolicy.yaml"
click node_eso_netpol "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/eso/networkpolicy.yaml"
click node_rbac "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/eso/rbac.yaml"
click node_gatekeeper "https://github.com/abukalam2909/eks_eso_poc/tree/main/kubernetes/gatekeeper/templates/custom"
click node_constraints "https://github.com/abukalam2909/eks_eso_poc/tree/main/kubernetes/gatekeeper/constraints"
click node_namespace "https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/namespaces.yaml"
click node_rotation "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/rotation_lambda/app.py"
click node_rotation_config "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/rotation.tf"
click node_cloudtrail "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/cloudtrail.tf"
click node_detection "https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/detection.tf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_secrets,node_app_role,node_kms toneBlue
class node_eks,node_endpoints,node_admin,node_netpol,node_eso_netpol toneAmber
class node_eso,node_reader_sa,node_external_secret,node_secret_store,node_k8s_secret,node_app toneMint
class node_rbac,node_gatekeeper,node_constraints,node_namespace toneRose
class node_rotation,node_rotation_config,node_cloudtrail,node_detection,node_operator toneIndigo
```

## Components

### AWS secrets and identity

- **Secrets Manager**
- [App IAM role](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/iam_app.tf): `terraform/iam_app.tf`
- [KMS encryption](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/kms.tf): `terraform/kms.tf`

### Private network and cluster

- [Private EKS](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/eks.tf): `terraform/eks.tf`
- [VPC endpoints](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/endpoints.tf): `terraform/endpoints.tf`
- [SSM admin host](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/admin_host.tf): `terraform/admin_host.tf`
- [Network policies](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/networkpolicy.yaml): `kubernetes/app/networkpolicy.yaml`
- [ESO network policy](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/eso/networkpolicy.yaml): `kubernetes/eso/networkpolicy.yaml`

### Kubernetes secret delivery

- [ESO controller](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/eso/values.yaml): `kubernetes/eso/values.yaml`
- [Secret-reader SA](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/serviceaccounts.yaml): `kubernetes/app/serviceaccounts.yaml`
- [ExternalSecret](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/externalsecret.yaml): `kubernetes/app/externalsecret.yaml`
- [SecretStore](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/secretstore.yaml): `kubernetes/app/secretstore.yaml`
- [Kubernetes Secret](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/externalsecret.yaml): `kubernetes/app/externalsecret.yaml`
- [App pod](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/app/deployment.yaml): `kubernetes/app/deployment.yaml`

### Access and admission controls

- [ESO RBAC](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/eso/rbac.yaml): `kubernetes/eso/rbac.yaml`
- [Gatekeeper policies](https://github.com/abukalam2909/eks_eso_poc/tree/main/kubernetes/gatekeeper/templates/custom): `kubernetes/gatekeeper/templates/custom`
- [Policy constraints](https://github.com/abukalam2909/eks_eso_poc/tree/main/kubernetes/gatekeeper/constraints): `kubernetes/gatekeeper/constraints`
- [App namespace](https://github.com/abukalam2909/eks_eso_poc/blob/main/kubernetes/namespaces.yaml): `kubernetes/namespaces.yaml`

### Rotation and detection

- [Rotation Lambda](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/rotation_lambda/app.py): `terraform/rotation_lambda/app.py`
- [Rotation schedule](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/rotation.tf): `terraform/rotation.tf`
- [CloudTrail](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/cloudtrail.tf): `terraform/cloudtrail.tf`
- [Secret-read alert](https://github.com/abukalam2909/eks_eso_poc/blob/main/terraform/detection.tf): `terraform/detection.tf`

### Other components

- **Operator**

## Connections

- Operator → SSM admin host: tunnels through (evidence: `README.md`)
- SSM admin host → Private EKS: accesses privately (evidence: `README.md`)
- Rotation schedule → Rotation Lambda: schedules (evidence: `README.md`)
- Rotation Lambda → Secrets Manager: rotates value (evidence: `README.md`)
- ESO controller → Secret-reader SA: mints token for (evidence: `README.md`)
- Secret-reader SA → App IAM role: assumes role (evidence: `README.md`)
- ESO controller → VPC endpoints: reads through (evidence: `README.md`)
- VPC endpoints → Secrets Manager: connects privately (evidence: `README.md`)
- ESO controller → Kubernetes Secret: syncs value (evidence: `README.md`)
- SecretStore → Secrets Manager: targets (evidence: `README.md`)
- ExternalSecret → SecretStore: references (evidence: `README.md`)
- Kubernetes Secret → App pod: mounts read-only (evidence: `README.md`)
- KMS encryption → Kubernetes Secret: encrypts at rest (evidence: `README.md`)
- Network policies → App pod: restricts traffic (evidence: `README.md`)
- ESO network policy → ESO controller: restricts traffic (evidence: `README.md`)
- ESO RBAC → ESO controller: limits permissions (evidence: `README.md`)
- Gatekeeper policies → Policy constraints: enforces constraints (evidence: `README.md`)
- Policy constraints → App namespace: guards workload (evidence: `README.md`)
- CloudTrail → Secret-read alert: feeds alerting (evidence: `README.md`)
- Secret-read alert → Secrets Manager: alerts on unexpected reads (evidence: `README.md`)
