# kubernetes-sigs/aws-efs-csi-driver architecture

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

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/aws-efs-csi-driver
- Repository: https://github.com/kubernetes-sigs/aws-efs-csi-driver

## Overview

The Amazon EFS CSI Driver exposes Kubernetes CSI identity, controller, and node services for EFS and S3 Files persistent volumes. The main workflow is a Kubernetes volume request handled by the controller, which provisions or resolves filesystem access, followed by node publication that mounts the volume into a pod. The driver also supplies cloud metadata, mount-helper/watchdog behavior, and optional Prometheus metrics. Some subsystem links are documented by the README; unsampled implementation details are not assumed.

Main entry points: [`pkg/driver/driver.go`](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/driver.go) (CSI server), [`pkg/driver/controller.go`](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/controller.go) (Controller service), [`pkg/cloud/metadata.go`](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/metadata.go) (Metadata selection), [`pkg/cloud/cloud.go`](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/cloud.go) (AWS cloud client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CSI runtime"]
  node_main["Process startup<br/>[main.go]"]
  node_driver["CSI server<br/>[driver.go]"]
  node_identity["Identity service<br/>[identity.go]"]
end

subgraph group_provision["Volume provisioning"]
  node_controller["Controller service<br/>[controller.go]"]
  node_fsid["Filesystem ID lookup"]
  node_gid["GID allocation<br/>[gid_allocator.go]"]
end

subgraph group_mount["Node mounting"]
  node_node["Node service<br/>[node.go]"]
  node_mounter["Node mounter<br/>[mounter.go]"]
  node_watchdog["Mount watchdog<br/>[efs_watch_dog.go]"]
end

subgraph group_support["Cloud and observability"]
  node_cloud["AWS cloud client<br/>[cloud.go]"]
  node_metadata["Metadata selection<br/>[metadata.go]"]
  node_ec2meta["EC2 metadata<br/>[ec2_metadata.go]"]
  node_k8smeta["Kubernetes metadata<br/>[k8s_metadata.go]"]
  node_taskmeta["ECS task metadata<br/>[task_metadata.go]"]
  node_metrics["Metrics endpoint<br/>[metrics.go]"]
  node_handlers["AWS API instrumentation<br/>[handlers.go]"]
end

node_kubernetes(("Kubernetes / kubelet"))
node_aws["EFS / S3 Files APIs"]

node_kubernetes -.->|"starts driver"| node_main
node_main -->|"starts server"| node_driver
node_driver -->|"registers service"| node_identity
node_driver -->|"registers service"| node_controller
node_driver -->|"registers service"| node_node
node_kubernetes -.->|"requests volumes"| node_controller
node_controller -->|"provisions access points"| node_cloud
node_controller -->|"mounts filesystem"| node_mounter
node_cloud -->|"calls APIs"| node_aws
node_kubernetes -.->|"publishes volume"| node_node
node_node -.->|"mounts volume"| node_mounter
node_driver -->|"creates client"| node_cloud
node_driver -.->|"starts watchdog"| node_watchdog
node_cloud -->|"selects metadata"| node_metadata
node_metadata -->|"checks IMDS"| node_ec2meta
node_metadata -->|"selects fallback"| node_k8smeta
node_metadata -->|"selects ECS"| node_taskmeta
node_taskmeta -->|"requests task data"| node_kubernetes
node_main -->|"initializes endpoint"| node_metrics
node_handlers -->|"records API calls"| node_metrics
node_controller -.->|"resolves filesystem"| node_fsid
node_controller -.->|"allocates GID"| node_gid

click node_main "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/cmd/main.go"
click node_driver "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/driver.go"
click node_identity "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/identity.go"
click node_controller "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/controller.go"
click node_fsid "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/filesystem_id_finder.go"
click node_gid "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/gid_allocator.go"
click node_cloud "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/cloud.go"
click node_node "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/node.go"
click node_mounter "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/mounter.go"
click node_watchdog "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/efs_watch_dog.go"
click node_metadata "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/metadata.go"
click node_ec2meta "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/ec2_metadata.go"
click node_k8smeta "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/k8s_metadata.go"
click node_taskmeta "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/task_metadata.go"
click node_metrics "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/metrics/metrics.go"
click node_handlers "https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/handlers.go"

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_main,node_driver,node_identity toneBlue
class node_controller,node_fsid,node_gid toneAmber
class node_node,node_mounter,node_watchdog,node_aws toneMint
class node_cloud,node_metadata,node_ec2meta,node_k8smeta,node_taskmeta,node_metrics,node_handlers toneRose
class node_kubernetes toneIndigo
```

## Components

### CSI runtime

- [Process startup](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/cmd/main.go): `cmd/main.go`
- [CSI server](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/driver.go): `pkg/driver/driver.go`
- [Identity service](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/identity.go): `pkg/driver/identity.go`

### Volume provisioning

- [Controller service](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/controller.go): `pkg/driver/controller.go`
- [Filesystem ID lookup](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/filesystem_id_finder.go): `pkg/driver/filesystem_id_finder.go`
- [GID allocation](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/gid_allocator.go): `pkg/driver/gid_allocator.go`

### Node mounting

- [Node service](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/node.go): `pkg/driver/node.go`
- [Node mounter](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/mounter.go): `pkg/driver/mounter.go`
- [Mount watchdog](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/driver/efs_watch_dog.go): `pkg/driver/efs_watch_dog.go`

### Cloud and observability

- [AWS cloud client](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/cloud.go): `pkg/cloud/cloud.go`
- [Metadata selection](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/metadata.go): `pkg/cloud/metadata.go`
- [EC2 metadata](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/ec2_metadata.go): `pkg/cloud/ec2_metadata.go`
- [Kubernetes metadata](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/k8s_metadata.go): `pkg/cloud/k8s_metadata.go`
- [ECS task metadata](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/task_metadata.go): `pkg/cloud/task_metadata.go`
- [Metrics endpoint](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`
- [AWS API instrumentation](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/pkg/cloud/handlers.go): `pkg/cloud/handlers.go`

### Other components

- **Kubernetes / kubelet**
- **EFS / S3 Files APIs**

## Connections

- Kubernetes / kubelet → Process startup: starts driver
- Process startup → CSI server: starts server (evidence: `cmd/main.go`)
- CSI server → Identity service: registers service (evidence: `pkg/driver/driver.go`)
- CSI server → Controller service: registers service (evidence: `pkg/driver/driver.go`)
- CSI server → Node service: registers service (evidence: `pkg/driver/driver.go`)
- Kubernetes / kubelet → Controller service: requests volumes
- Controller service → AWS cloud client: provisions access points (evidence: `pkg/driver/controller.go`)
- Controller service → Node mounter: mounts filesystem (evidence: `pkg/driver/controller.go`)
- AWS cloud client → EFS / S3 Files APIs: calls APIs (evidence: `pkg/cloud/cloud.go`)
- Kubernetes / kubelet → Node service: publishes volume
- Node service → Node mounter: mounts volume
- CSI server → AWS cloud client: creates client (evidence: `pkg/driver/driver.go`)
- CSI server → Mount watchdog: starts watchdog (evidence: `pkg/driver/driver.go`)
- AWS cloud client → Metadata selection: selects metadata (evidence: `pkg/cloud/cloud.go`)
- Metadata selection → EC2 metadata: checks IMDS (evidence: `pkg/cloud/metadata.go`)
- Metadata selection → Kubernetes metadata: selects fallback (evidence: `pkg/cloud/metadata.go`)
- Metadata selection → ECS task metadata: selects ECS (evidence: `pkg/cloud/metadata.go`)
- ECS task metadata → Kubernetes / kubelet: requests task data (evidence: `pkg/cloud/task_metadata.go`)
- Process startup → Metrics endpoint: initializes endpoint (evidence: `cmd/main.go`)
- AWS API instrumentation → Metrics endpoint: records API calls (evidence: `pkg/cloud/handlers.go`)
- Controller service → Filesystem ID lookup: resolves filesystem
- Controller service → GID allocation: allocates GID
