# xorps/kube2iam architecture

> Architecture diagram of the GitHub repository xorps/kube2iam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xorps/kube2iam
- Repository: https://github.com/xorps/kube2iam

## Overview

##### Main Components Identification

a. Core Components:
- kube2iam DaemonSet (runs on each worker node)
- Kubernetes API Server
- AWS EC2 Metadata API
- AWS STS (Security Token Service)
- AWS IAM Roles

b. Supporting Components:
- iptables rules
- Pod annotations
- Namespace restrictions
- Metrics endpoint
- Health checks

##### Specific Elements

**┌─ Worker Node ──────────────────┐**
- ┌─ kube2iam pod ─────────────┐ │
- Host Network Mode        │ │
- iptables rules          │ │
- Metrics endpoint        │ │
- ┘ │
- ┌─ Application Pods ──────────┐ │
- IAM Role Annotations     │ │
- ┘ │
- ┘

b. Authentication Flow Section:
**┌─ Authentication Flow ───────────┐**
- 1. Pod requests credentials    │
- 2. kube2iam intercepts request │
- 3. Validates annotations      │
- 4. Assumes IAM role          │
- 5. Returns temp credentials   │
- ┘

##### Important Interactions

- iptables redirection of metadata API requests (169.254.169.254)
- Role assumption process through AWS STS
- Namespace restriction validation
- Metrics collection path

##### Technical Details

- Port numbers (8181 for main service)
- Network interfaces (docker0, etc.)
- Annotation formats
- IAM role ARN patterns

##### Implementation Notes

- Rectangles for services
- Hexagons for AWS services
- Circles for endpoints
- Diamonds for decision points

- AWS components (orange)
- Kubernetes components (blue)
- Network components (green)
- Security components (red)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph AWS["AWS Cloud Services"]
        IAM[IAM Roles]:::aws
        STS[Security Token Service]:::aws
        EC2Meta[EC2 Metadata API]:::aws
    end

    subgraph K8s["Kubernetes Cluster"]
        API[Kubernetes API Server]:::k8s
        
        subgraph WNode["Worker Node"]
            direction TB
            K2IAM[kube2iam DaemonSet]:::core
            IPT[iptables Rules]:::network
            AppPod[Application Pods]:::app
            MetricsEP[Metrics Endpoint]:::monitoring
        end
    end

    subgraph Components["Core Components"]
        direction TB
        Server[Server Component]:::core
        IAMManager[IAM Role Manager]:::core
        PodMgr[Pod Manager]:::core
        NsMgr[Namespace Manager]:::core
        RoleMapper[Role Mapper]:::core
        K8sInt[Kubernetes Integration]:::core
    end

    subgraph Security["Security & Config"]
        direction TB
        RBAC[RBAC Rules]:::security
        SecPol[Security Policies]:::security
        HelmCfg[Helm Configuration]:::config
    end

    %% Relationships
    IAM --> STS
    STS --> K2IAM
    AppPod --> IPT
    IPT --> K2IAM
    K2IAM --> EC2Meta
    K2IAM --> API
    K2IAM --> MetricsEP
    Server --> K2IAM
    IAMManager --> K2IAM
    PodMgr --> K2IAM
    NsMgr --> K2IAM
    RoleMapper --> K2IAM
    K8sInt --> API
    RBAC --> K2IAM
    SecPol --> K2IAM
    HelmCfg --> K2IAM

    %% Click Events
    click K2IAM "https://github.com/xorps/kube2iam/blob/master/charts/kube2iam/templates/daemonset.yaml"
    click IAMManager "https://github.com/xorps/kube2iam/blob/master/iam/iam.go"
    click IPT "https://github.com/xorps/kube2iam/blob/master/iptables/iptables.go"
    click PodMgr "https://github.com/xorps/kube2iam/blob/master/pod.go"
    click NsMgr "https://github.com/xorps/kube2iam/blob/master/namespace.go"
    click Server "https://github.com/xorps/kube2iam/blob/master/server/server.go"
    click MetricsEP "https://github.com/xorps/kube2iam/blob/master/metrics/metrics.go"
    click RoleMapper "https://github.com/xorps/kube2iam/blob/master/mappings/mapper.go"
    click K8sInt "https://github.com/xorps/kube2iam/blob/master/k8s/k8s.go"
    click RBAC "https://github.com/xorps/kube2iam/blob/master/charts/kube2iam/templates/clusterrole.yaml"
    click SecPol "https://github.com/xorps/kube2iam/blob/master/charts/kube2iam/templates/podsecuritypolicy.yaml"
    click HelmCfg "https://github.com/xorps/kube2iam/blob/master/charts/kube2iam/values.yaml"

    %% Styling
    classDef aws fill:#FF9900,stroke:#232F3E,color:white
    classDef k8s fill:#326CE5,stroke:#254B99,color:white
    classDef core fill:#2E7D32,stroke:#1B5E20,color:white
    classDef network fill:#0288D1,stroke:#01579B,color:white
    classDef app fill:#7B1FA2,stroke:#4A148C,color:white
    classDef monitoring fill:#F57C00,stroke:#E65100,color:white
    classDef security fill:#C62828,stroke:#B71C1C,color:white
    classDef config fill:#455A64,stroke:#263238,color:white
```
