# eksctl-io/eksctl architecture

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

- Interactive diagram: https://gitdiagram.com/eksctl-io/eksctl
- Repository: https://github.com/eksctl-io/eksctl

## Overview

eksctl is a Go CLI for provisioning and managing Amazon EKS clusters and related resources. Its main workflow starts with a user command, proceeds through CLI command handling and cluster configuration, then uses EKS and CloudFormation-facing components to create or change AWS resources; cluster credentials are written to kubeconfig. The repository also has distinct capabilities for nodegroups, addons, Auto Mode, identity, and Kubernetes controllers. Edges are limited to relationships shown in the README or sampled source index/excerpts; several feature internals were not sampled.

Main entry points: [`pkg/ctl`](https://github.com/eksctl-io/eksctl/tree/main/pkg/ctl) (Command handlers), [`pkg/cfn/manager`](https://github.com/eksctl-io/eksctl/tree/main/pkg/cfn/manager) (Stack lifecycle), [`pkg/actions/cluster`](https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/cluster) (Cluster actions), [`pkg/eks/tasks.go`](https://github.com/eksctl-io/eksctl/blob/main/pkg/eks/tasks.go) (EKS task orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and configuration"]
  node_cli["Command router<br/>[main.go]"]
  node_commands["Command handlers"]
  node_config["Cluster API config<br/>[v1alpha5]"]
end

subgraph group_provision["Cluster provisioning"]
  node_cluster_actions["Cluster actions"]
  node_eks_tasks["EKS task orchestration<br/>[tasks.go]"]
  node_versioning["Version resolution"]
  node_template_builder["Stack templates"]
  node_stack_manager["Stack lifecycle"]
  node_nodegroups["Nodegroup management"]
end

subgraph group_features["Cluster features"]
  node_addons["Addon management"]
  node_addon_tasks["Addon task orchestration<br/>[tasks.go]"]
  node_auto_mode["Auto Mode roles"]
  node_identity["Identity features"]
  node_access_entries["Access entries"]
  node_pod_identity["Pod identity<br/>[tasks.go]"]
  node_vpc_controller["VPC controller<br/>[vpc_controller.go]"]
end

subgraph group_integrations["Cloud and Kubernetes"]
  node_aws(("AWS services"))
  node_cloudformation[("CloudFormation")]
  node_kubernetes(("Kubernetes API"))
  node_kubeconfig["Cluster credentials"]
end

node_user(("CLI user"))

node_user -->|"runs command"| node_cli
node_cli -->|"routes commands"| node_commands
node_user -->|"requests cluster"| node_cluster_actions
node_commands -.->|"loads config"| node_config
node_commands -.->|"invokes actions"| node_cluster_actions
node_cluster_actions -.->|"orchestrates tasks"| node_eks_tasks
node_eks_tasks -->|"resolves versions"| node_versioning
node_eks_tasks -->|"manages stacks"| node_stack_manager
node_stack_manager -->|"uses templates"| node_template_builder
node_template_builder -->|"defines resources"| node_cloudformation
node_stack_manager -->|"creates stacks"| node_cloudformation
node_eks_tasks -.->|"calls EKS APIs"| node_aws
node_cluster_actions -.->|"manages nodegroups"| node_nodegroups
node_commands -.->|"routes addon commands"| node_addons
node_addons -->|"orchestrates tasks"| node_addon_tasks
node_addon_tasks -->|"manages stacks"| node_stack_manager
node_commands -.->|"routes identity commands"| node_identity
node_identity -.->|"manages access entries"| node_access_entries
node_identity -.->|"manages pod identity"| node_pod_identity
node_pod_identity -->|"manages stacks"| node_stack_manager
node_commands -.->|"routes Auto Mode"| node_auto_mode
node_auto_mode -->|"reads stack template"| node_stack_manager
node_auto_mode -->|"updates IAM roles"| node_aws
node_commands -->|"installs controller"| node_vpc_controller
node_vpc_controller -->|"updates resources"| node_kubernetes
node_cluster_actions -->|"writes credentials"| node_kubeconfig
node_stack_manager -->|"provisions resources"| node_aws

click node_cli "https://github.com/eksctl-io/eksctl/blob/main/cmd/eksctl/main.go"
click node_commands "https://github.com/eksctl-io/eksctl/tree/main/pkg/ctl"
click node_config "https://github.com/eksctl-io/eksctl/tree/main/pkg/apis/eksctl.io/v1alpha5"
click node_cluster_actions "https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/cluster"
click node_eks_tasks "https://github.com/eksctl-io/eksctl/blob/main/pkg/eks/tasks.go"
click node_versioning "https://github.com/eksctl-io/eksctl/blob/main/pkg/eks/versions_manager.go"
click node_template_builder "https://github.com/eksctl-io/eksctl/tree/main/pkg/cfn/builder"
click node_stack_manager "https://github.com/eksctl-io/eksctl/tree/main/pkg/cfn/manager"
click node_nodegroups "https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/nodegroup"
click node_addons "https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/addon"
click node_addon_tasks "https://github.com/eksctl-io/eksctl/blob/main/pkg/actions/addon/tasks.go"
click node_auto_mode "https://github.com/eksctl-io/eksctl/blob/main/pkg/automode/cluster_role_manager.go"
click node_identity "https://github.com/eksctl-io/eksctl/tree/main/pkg/actions"
click node_access_entries "https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/accessentry"
click node_pod_identity "https://github.com/eksctl-io/eksctl/blob/main/pkg/actions/podidentityassociation/tasks.go"
click node_vpc_controller "https://github.com/eksctl-io/eksctl/blob/main/pkg/addons/vpc_controller.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_cli,node_commands,node_config,node_user toneBlue
class node_cluster_actions,node_eks_tasks,node_versioning,node_template_builder,node_stack_manager,node_nodegroups toneAmber
class node_addons,node_addon_tasks,node_auto_mode,node_identity,node_access_entries,node_pod_identity,node_vpc_controller toneMint
class node_aws,node_cloudformation,node_kubernetes,node_kubeconfig toneRose
```

## Components

### CLI and configuration

- [Command router](https://github.com/eksctl-io/eksctl/blob/main/cmd/eksctl/main.go): `cmd/eksctl/main.go`
- [Command handlers](https://github.com/eksctl-io/eksctl/tree/main/pkg/ctl): `pkg/ctl`
- [Cluster API config](https://github.com/eksctl-io/eksctl/tree/main/pkg/apis/eksctl.io/v1alpha5): `pkg/apis/eksctl.io/v1alpha5`

### Cluster provisioning

- [Cluster actions](https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/cluster): `pkg/actions/cluster`
- [EKS task orchestration](https://github.com/eksctl-io/eksctl/blob/main/pkg/eks/tasks.go): `pkg/eks/tasks.go`
- [Version resolution](https://github.com/eksctl-io/eksctl/blob/main/pkg/eks/versions_manager.go): `pkg/eks/versions_manager.go`
- [Stack templates](https://github.com/eksctl-io/eksctl/tree/main/pkg/cfn/builder): `pkg/cfn/builder`
- [Stack lifecycle](https://github.com/eksctl-io/eksctl/tree/main/pkg/cfn/manager): `pkg/cfn/manager`
- [Nodegroup management](https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/nodegroup): `pkg/actions/nodegroup`

### Cluster features

- [Addon management](https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/addon): `pkg/actions/addon`
- [Addon task orchestration](https://github.com/eksctl-io/eksctl/blob/main/pkg/actions/addon/tasks.go): `pkg/actions/addon/tasks.go`
- [Auto Mode roles](https://github.com/eksctl-io/eksctl/blob/main/pkg/automode/cluster_role_manager.go): `pkg/automode/cluster_role_manager.go`
- [Identity features](https://github.com/eksctl-io/eksctl/tree/main/pkg/actions): `pkg/actions`
- [Access entries](https://github.com/eksctl-io/eksctl/tree/main/pkg/actions/accessentry): `pkg/actions/accessentry`
- [Pod identity](https://github.com/eksctl-io/eksctl/blob/main/pkg/actions/podidentityassociation/tasks.go): `pkg/actions/podidentityassociation/tasks.go`
- [VPC controller](https://github.com/eksctl-io/eksctl/blob/main/pkg/addons/vpc_controller.go): `pkg/addons/vpc_controller.go`

### Cloud and Kubernetes

- **AWS services**
- **CloudFormation**
- **Kubernetes API**
- **Cluster credentials**

### Other components

- **CLI user**

## Connections

- CLI user → Command router: runs command (evidence: `cmd/eksctl/main.go`)
- Command router → Command handlers: routes commands (evidence: `cmd/eksctl/main.go`)
- CLI user → Cluster actions: requests cluster (evidence: `README.md`)
- Command handlers → Cluster API config: loads config (evidence: `pkg/ctl/utils/install_vpc_controllers.go`)
- Command handlers → Cluster actions: invokes actions
- Cluster actions → EKS task orchestration: orchestrates tasks
- EKS task orchestration → Version resolution: resolves versions (evidence: `pkg/eks/tasks.go`)
- EKS task orchestration → Stack lifecycle: manages stacks (evidence: `pkg/eks/tasks.go`)
- Stack lifecycle → Stack templates: uses templates (evidence: `pkg/cfn/manager/create_tasks.go`)
- Stack templates → CloudFormation: defines resources (evidence: `README.md`)
- Stack lifecycle → CloudFormation: creates stacks (evidence: `README.md`)
- EKS task orchestration → AWS services: calls EKS APIs
- Cluster actions → Nodegroup management: manages nodegroups
- Command handlers → Addon management: routes addon commands
- Addon management → Addon task orchestration: orchestrates tasks (evidence: `pkg/actions/addon/tasks.go`)
- Addon task orchestration → Stack lifecycle: manages stacks (evidence: `pkg/actions/addon/tasks.go`)
- Command handlers → Identity features: routes identity commands (evidence: `pkg/ctl/create/iamserviceaccount.go`)
- Identity features → Access entries: manages access entries
- Identity features → Pod identity: manages pod identity
- Pod identity → Stack lifecycle: manages stacks (evidence: `pkg/actions/podidentityassociation/tasks.go`)
- Command handlers → Auto Mode roles: routes Auto Mode
- Auto Mode roles → Stack lifecycle: reads stack template (evidence: `pkg/automode/cluster_role_manager.go`)
- Auto Mode roles → AWS services: updates IAM roles (evidence: `pkg/automode/cluster_role_manager.go`)
- Command handlers → VPC controller: installs controller (evidence: `pkg/ctl/utils/install_vpc_controllers.go`)
- VPC controller → Kubernetes API: updates resources (evidence: `pkg/addons/vpc_controller.go`)
- Cluster actions → Cluster credentials: writes credentials (evidence: `README.md`)
- Stack lifecycle → AWS services: provisions resources (evidence: `README.md`)
