# awslabs/amazon-eks-ami architecture

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

- Interactive diagram: https://gitdiagram.com/awslabs/amazon-eks-ami
- Repository: https://github.com/awslabs/amazon-eks-ami

## Overview

The repository README describes building EKS-optimized AMIs; the supplied source focuses on nodeadm, the node bootstrap/configuration runtime. Its main workflow loads and validates NodeConfig, enriches it with instance details, applies system configuration, and configures and runs containerd and kubelet. Separate commands check or dump configuration, while internal tools handle boot-time networking. Several subsystems are represented by tree paths or index references rather than inspected implementation, so their connections are omitted or marked unverified.

Main entry points: [`nodeadm/cmd/nodeadm/init/init.go`](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/init/init.go) (Bootstrap init), [`nodeadm/cmd/nodeadm/main.go`](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/main.go) (nodeadm CLI), [`nodeadm/cmd/nodeadm/config/root.go`](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/root.go) (Config commands), [`nodeadm/cmd/nodeadm/config/check.go`](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/check.go) (Config check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Nodeadm commands"]
  node_nodeadm["nodeadm CLI<br/>[main.go]"]
  node_init["Bootstrap init<br/>[init.go]"]
  node_configcmd["Config commands<br/>[root.go]"]
  node_configcheck["Config check<br/>[check.go]"]
  node_configdump["Config dump<br/>[dump.go]"]
  node_internaltools["Internal tools<br/>[main.go]"]
end

subgraph group_configuration["Configuration"]
  node_configprovider["Config providers"]
  node_publicconfig["Public NodeConfig"]
  node_internalapi["Internal config<br/>[types.go]"]
  node_bridge["Config conversion"]
  node_validation["Config validation<br/>[validation.go]"]
end

subgraph group_bootstrap["Node bootstrap"]
  node_daemonmanager["Daemon manager<br/>[manager.go]"]
  node_containerd["Containerd setup<br/>[daemon.go]"]
  node_kubelet["Kubelet setup<br/>[daemon.go]"]
end

subgraph group_system["System integration"]
  node_systemaspects["System aspects<br/>[aspect.go]"]
  node_ebsstorage["EBS storage<br/>[ebs_storage.go]"]
  node_instanceenv["Instance environment<br/>[environment.go]"]
  node_imds["EC2 metadata<br/>[imds.go]"]
  node_bootnetwork["Boot network hook<br/>[hook.go]"]
  node_udevnetwork["Udev network manager<br/>[net_manager.go]"]
  node_networkmanager["Network manager<br/>[networkmanager.go]"]
end

node_operator(("Node operator"))
node_configoutput["Serialized config"]

node_operator -->|"runs"| node_nodeadm
node_nodeadm -->|"registers"| node_init
node_nodeadm -->|"registers"| node_configcmd
node_configcmd -.->|"registers"| node_configcheck
node_configcmd -.->|"registers"| node_configdump
node_init -->|"validates"| node_validation
node_init -->|"creates"| node_daemonmanager
node_init -->|"configures and runs"| node_containerd
node_init -->|"configures and runs"| node_kubelet
node_init -->|"sets up"| node_systemaspects
node_init -.->|"loads through"| node_configprovider
node_init -.->|"enriches from"| node_imds
node_systemaspects -.->|"includes"| node_ebsstorage
node_systemaspects -.->|"includes"| node_instanceenv
node_configcheck -->|"parses"| node_configprovider
node_configcheck -->|"validates"| node_validation
node_configdump -->|"encodes with"| node_bridge
node_configdump -->|"writes"| node_configoutput
node_bridge -->|"converts to"| node_publicconfig
node_bridge -->|"converts to"| node_internalapi
node_configprovider -->|"decodes to"| node_internalapi
node_operator -->|"runs"| node_internaltools
node_internaltools -->|"registers"| node_bootnetwork
node_internaltools -->|"registers"| node_udevnetwork
node_bootnetwork -->|"reads identity"| node_imds
node_bootnetwork -->|"uses cache path"| node_networkmanager
node_udevnetwork -->|"reads metadata"| node_imds
node_udevnetwork -->|"selects manager"| node_networkmanager

click node_nodeadm "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/main.go"
click node_init "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/init/init.go"
click node_configcmd "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/root.go"
click node_configcheck "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/check.go"
click node_configdump "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/dump.go"
click node_configprovider "https://github.com/awslabs/amazon-eks-ami/tree/main/nodeadm/internal/configprovider"
click node_publicconfig "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/api/v1alpha1/nodeconfig_types.go"
click node_internalapi "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/api/types.go"
click node_bridge "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/api/bridge/zz_generated.conversion.go"
click node_validation "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/api/validation.go"
click node_daemonmanager "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/daemon/manager.go"
click node_containerd "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/containerd/daemon.go"
click node_kubelet "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/kubelet/daemon.go"
click node_systemaspects "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/system/aspect.go"
click node_ebsstorage "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/system/ebs_storage.go"
click node_instanceenv "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/system/environment.go"
click node_imds "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/aws/imds/imds.go"
click node_internaltools "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm-internal/main.go"
click node_bootnetwork "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm-internal/boot-book/hook.go"
click node_udevnetwork "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm-internal/udev/net_manager.go"
click node_networkmanager "https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/networkmanager/networkmanager.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_nodeadm,node_init,node_configcmd,node_configcheck,node_configdump,node_internaltools toneBlue
class node_configprovider,node_publicconfig,node_internalapi,node_bridge,node_validation toneAmber
class node_daemonmanager,node_containerd,node_kubelet toneMint
class node_systemaspects,node_ebsstorage,node_instanceenv,node_imds,node_bootnetwork,node_udevnetwork,node_networkmanager toneRose
class node_operator,node_configoutput toneIndigo
```

## Components

### Nodeadm commands

- [nodeadm CLI](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/main.go): `nodeadm/cmd/nodeadm/main.go`
- [Bootstrap init](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/init/init.go): `nodeadm/cmd/nodeadm/init/init.go`
- [Config commands](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/root.go): `nodeadm/cmd/nodeadm/config/root.go`
- [Config check](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/check.go): `nodeadm/cmd/nodeadm/config/check.go`
- [Config dump](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm/config/dump.go): `nodeadm/cmd/nodeadm/config/dump.go`
- [Internal tools](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm-internal/main.go): `nodeadm/cmd/nodeadm-internal/main.go`

### Configuration

- [Config providers](https://github.com/awslabs/amazon-eks-ami/tree/main/nodeadm/internal/configprovider): `nodeadm/internal/configprovider`
- [Public NodeConfig](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/api/v1alpha1/nodeconfig_types.go): `nodeadm/api/v1alpha1/nodeconfig_types.go`
- [Internal config](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/api/types.go): `nodeadm/internal/api/types.go`
- [Config conversion](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/api/bridge/zz_generated.conversion.go): `nodeadm/internal/api/bridge/zz_generated.conversion.go`
- [Config validation](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/api/validation.go): `nodeadm/internal/api/validation.go`

### Node bootstrap

- [Daemon manager](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/daemon/manager.go): `nodeadm/internal/daemon/manager.go`
- [Containerd setup](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/containerd/daemon.go): `nodeadm/internal/containerd/daemon.go`
- [Kubelet setup](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/kubelet/daemon.go): `nodeadm/internal/kubelet/daemon.go`

### System integration

- [System aspects](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/system/aspect.go): `nodeadm/internal/system/aspect.go`
- [EBS storage](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/system/ebs_storage.go): `nodeadm/internal/system/ebs_storage.go`
- [Instance environment](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/system/environment.go): `nodeadm/internal/system/environment.go`
- [EC2 metadata](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/aws/imds/imds.go): `nodeadm/internal/aws/imds/imds.go`
- [Boot network hook](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm-internal/boot-book/hook.go): `nodeadm/cmd/nodeadm-internal/boot-book/hook.go`
- [Udev network manager](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/cmd/nodeadm-internal/udev/net_manager.go): `nodeadm/cmd/nodeadm-internal/udev/net_manager.go`
- [Network manager](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/networkmanager/networkmanager.go): `nodeadm/internal/networkmanager/networkmanager.go`

### Other components

- **Node operator**
- **Serialized config**

## Connections

- Node operator → nodeadm CLI: runs (evidence: `nodeadm/cmd/nodeadm/main.go`)
- nodeadm CLI → Bootstrap init: registers (evidence: `nodeadm/cmd/nodeadm/main.go`)
- nodeadm CLI → Config commands: registers (evidence: `nodeadm/cmd/nodeadm/main.go`)
- Config commands → Config check: registers
- Config commands → Config dump: registers
- Bootstrap init → Config validation: validates (evidence: `nodeadm/cmd/nodeadm/init/init.go`)
- Bootstrap init → Daemon manager: creates (evidence: `nodeadm/cmd/nodeadm/init/init.go`)
- Bootstrap init → Containerd setup: configures and runs (evidence: `nodeadm/cmd/nodeadm/init/init.go`)
- Bootstrap init → Kubelet setup: configures and runs (evidence: `nodeadm/cmd/nodeadm/init/init.go`)
- Bootstrap init → System aspects: sets up (evidence: `nodeadm/cmd/nodeadm/init/init.go`)
- Bootstrap init → Config providers: loads through
- Bootstrap init → EC2 metadata: enriches from
- System aspects → EBS storage: includes
- System aspects → Instance environment: includes
- Config check → Config providers: parses (evidence: `nodeadm/cmd/nodeadm/config/check.go`)
- Config check → Config validation: validates (evidence: `nodeadm/cmd/nodeadm/config/check.go`)
- Config dump → Config conversion: encodes with (evidence: `nodeadm/cmd/nodeadm/config/dump.go`)
- Config dump → Serialized config: writes (evidence: `nodeadm/cmd/nodeadm/config/dump.go`)
- Config conversion → Public NodeConfig: converts to (evidence: `nodeadm/internal/api/bridge/zz_generated.conversion.go`)
- Config conversion → Internal config: converts to (evidence: `nodeadm/internal/api/bridge/zz_generated.conversion.go`)
- Config providers → Internal config: decodes to (evidence: `nodeadm/internal/configprovider/file.go`)
- Node operator → Internal tools: runs (evidence: `nodeadm/cmd/nodeadm-internal/main.go`)
- Internal tools → Boot network hook: registers (evidence: `nodeadm/cmd/nodeadm-internal/main.go`)
- Internal tools → Udev network manager: registers (evidence: `nodeadm/cmd/nodeadm-internal/main.go`)
- Boot network hook → EC2 metadata: reads identity (evidence: `nodeadm/cmd/nodeadm-internal/boot-book/hook.go`)
- Boot network hook → Network manager: uses cache path (evidence: `nodeadm/cmd/nodeadm-internal/boot-book/hook.go`)
- Udev network manager → EC2 metadata: reads metadata (evidence: `nodeadm/cmd/nodeadm-internal/udev/net_manager.go`)
- Udev network manager → Network manager: selects manager (evidence: `nodeadm/cmd/nodeadm-internal/udev/net_manager.go`)