# aws/eks-anywhere architecture

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

- Interactive diagram: https://gitdiagram.com/aws/eks-anywhere
- Repository: https://github.com/aws/eks-anywhere

## Overview

##### Project type and purpose
- Amazon EKS Anywhere is a Go-based CLI plus Kubernetes operator (“controller-manager”) that enables on-premises Kubernetes cluster lifecycle management.
- Key roles: the user CLI (eksctl-anywhere & eks-a-tool), CRD definitions, controller manager logic (reconciliation loops), provider plugins (CloudStack, Nutanix, Snow, vSphere, Docker, Tinkerbell), and auxiliary components (OIDC server, GitOps integration via Flux).

##### High-level structure
- Top-level “cmd/…” directories hold CLI entry points.
- “config/…” holds Kustomize manifests for CRDs, RBAC, and controller deployment.
- “controllers/…” contains Kubernetes controller implementations.
- “pkg/…” houses core libraries: API object definitions, provider implementations, cluster-API glue, bootstrap logic, workflows, utilities.
- “internal/…” holds private modules (AWS SDK, OIDC server).
- “manager/…” builds the controller-manager image.
- “config/crd” and “config/default” → CRD YAML and default patches.
- “cmd/integration_test” → end-to-end test harness.

##### Main components
A. User CLI Layer
- eksctl-anywhere & eks-a-tool binaries
- Parses user flags, builds ClusterConfig objects (pkg/api → pkg/cluster), writes CRDs to management cluster.
B. Kubernetes Control Plane (Management Cluster)
- API Server + etcd
- Custom Resource Definitions (CRDs) for Cluster, MachineConfigs, DataCenterConfigs, FluxConfig, OIDCConfig, Bundles
- Admission Webhooks (config/webhook)
C. Controller-Manager Deployment
- Controllers: ClusterController, MachineDeploymentController, NodeUpgradeController, ControlPlaneUpgradeController, etc.
- Provider Reconcilers (cloudstack, nutanix, snow, vsphere, docker, tinkerbell)
- Bootstrapper & Conformance runner (pkg/bootstrapper, pkg/conformance)
- GitOps integrator (pkg/gitops/flux)
- OIDC server (internal/pkg/oidc)
D. External Provider APIs
- CloudStack REST API, Nutanix Prism API, AWS Snow API, vSphere vCenter, Docker�d, Tinkerbell services
- AWS IAM for EKS IAMAuthenticator (pkg/awsiam)
E. Supporting Services & Repos
- Container registries (docker, ECR)
- Git repos for Flux
- S3 buckets (pkg/s3)
- Bundle storage (bundles of EKS-D, etc.)

##### Interaction flow
1. Operator runs CLI → constructs Cluster CR & associated objects → writes them to the management cluster API server over kubeconfig.
2. Controllers watch CRs → reconciliation loops pick up new/changed CRs.
3. Provider plugins perform API calls to provision VMs, networks, load balancers, bootstrap Kubernetes on nodes.
4. Bootstrapper injects core EKS-D components (etcd, kube-apiserver, kubelet).
5. Flux GitOps deploys add-ons if requested (pkg/gitops/flux).
6. For upgrades/conformance: node-upgrader controllers or conformance controllers execute in pods.
7. OIDC server may serve discovery/keys for cluster identity.

##### Architectural patterns & principles
- Kubernetes Operator pattern: declarative CRDs + controller loops.
- Plugin-based provider abstraction: pkg/providers and pkg/clusterapi glue enabling swap-in of multiple infrastructures.
- Separation of concerns: CLI vs. controllers vs. provider modules.
- GitOps extension via Flux integration.
- Use of build scripts and Kustomize for packaging and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User CLI Layer
    subgraph "User CLI Layer"
        CLI1["eksctl-anywhere (CLI)"]:::cli
        CLI2["eks-a-tool (CLI)"]:::cli
    end

    %% Kubernetes Control Plane
    subgraph "Kubernetes Control Plane"
        APISERVER["API Server + etcd"]:::core
        CRDS["CRD Definitions"]:::core
        WEBHOOK["Admission Webhooks"]:::core
    end

    %% Controller-Manager Deployment
    subgraph "Controller-Manager (Reconciler Pods)"
        CMENTRY["manager/main.go"]:::controllers
        subgraph "Core Controllers"
            ClusterCtrl["ClusterController"]:::controllers
            MachineCtrl["MachineDeploymentController"]:::controllers
            NodeUpgrade["NodeUpgradeController"]:::controllers
            CPUpgrade["ControlPlaneUpgradeController"]:::controllers
        end
        subgraph "Provider Reconcilers"
            CSRec["CloudStack Reconciler"]:::providers
            NTRec["Nutanix Reconciler"]:::providers
            SnowRec["Snow Reconciler"]:::providers
            VSRec["vSphere Reconciler"]:::providers
            DockRec["Docker Reconciler"]:::providers
            TinkRec["Tinkerbell Reconciler"]:::providers
        end
        BS["Bootstrapper"]:::controllers
        Conf["Conformance Runner"]:::controllers
        Flux["Flux GitOps Integrator"]:::controllers
        OIDC["OIDC Server"]:::controllers
    end

    %% External Services
    subgraph "External Services"
        CSAPI["CloudStack API"]:::external
        NTAPI["Nutanix Prism API"]:::external
        SnowAPI["AWS Snow API"]:::external
        VSAPI["vSphere vCenter"]:::external
        DockerAPI["Docker Daemon"]:::external
        TinkAPI["Tinkerbell Services"]:::external
        IAM["AWS IAM"]:::external
        Registry["Container Registry"]:::external
        GitRepo["Git Repository"]:::external
        S3["S3 Buckets"]:::external
    end

    %% Interactions
    CLI1 -->|"creates CRs"| APISERVER
    CLI2 -->|"creates CRs"| APISERVER
    APISERVER -->|serves| ClusterCtrl
    APISERVER -->|serves| MachineCtrl
    APISERVER -->|serves| NodeUpgrade
    APISERVER -->|serves| CPUpgrade
    ClusterCtrl -->|calls| CSRec
    ClusterCtrl -->|calls| NTRec
    ClusterCtrl -->|calls| SnowRec
    ClusterCtrl -->|calls| VSRec
    ClusterCtrl -->|calls| DockRec
    ClusterCtrl -->|calls| TinkRec
    BS -->|injects EKS-D| APISERVER
    Flux -->|watches| GitRepo
    Flux -->|applies| APISERVER
    NodeUpgrade -->|executes| Conf
    Conf -->|stores| S3
    CSRec -->|REST calls| CSAPI
    NTRec -->|REST calls| NTAPI
    SnowRec -->|API calls| SnowAPI
    VSRec -->|API calls| VSAPI
    DockRec -->|calls| DockerAPI
    TinkRec -->|calls| TinkAPI
    ClusterCtrl -->|uses| IAM
    OIDC -->|serves discovery| ClusterCtrl
    OIDC -->|serves discovery| NodeUpgrade
    OIDC -->|serves discovery| CPUpgrade

    %% CRD & Webhook connections
    CRDS -->|deployed via| APISERVER
    WEBHOOK -->|validates| APISERVER

    %% Click Events
    click CLI1 "https://github.com/aws/eks-anywhere/tree/main/cmd/eksctl-anywhere"
    click CLI2 "https://github.com/aws/eks-anywhere/tree/main/cmd/eks-a-tool"
    click CRDS "https://github.com/aws/eks-anywhere/blob/main/config/crd/bases/*.yaml"
    click CRDS "https://github.com/aws/eks-anywhere/tree/main/pkg/api/v1alpha1"
    click WEBHOOK "https://github.com/aws/eks-anywhere/tree/main/config/webhook"
    click CMENTRY "https://github.com/aws/eks-anywhere/blob/main/manager/main.go"
    click ClusterCtrl "https://github.com/aws/eks-anywhere/blob/main/controllers/*.go"
    click MachineCtrl "https://github.com/aws/eks-anywhere/blob/main/controllers/*.go"
    click NodeUpgrade "https://github.com/aws/eks-anywhere/blob/main/controllers/*.go"
    click CPUpgrade "https://github.com/aws/eks-anywhere/blob/main/controllers/*.go"
    click CSRec "https://github.com/aws/eks-anywhere/tree/main/pkg/providers/cloudstack/reconciler"
    click NTRec "https://github.com/aws/eks-anywhere/tree/main/pkg/providers/nutanix/reconciler"
    click SnowRec "https://github.com/aws/eks-anywhere/tree/main/pkg/providers/snow/reconciler"
    click VSRec "https://github.com/aws/eks-anywhere/tree/main/pkg/providers/vsphere/reconciler"
    click DockRec "https://github.com/aws/eks-anywhere/tree/main/pkg/providers/docker/reconciler"
    click TinkRec "https://github.com/aws/eks-anywhere/tree/main/pkg/providers/tinkerbell/reconciler"
    click BS "https://github.com/aws/eks-anywhere/tree/main/pkg/bootstrapper"
    click Conf "https://github.com/aws/eks-anywhere/tree/main/pkg/conformance"
    click Flux "https://github.com/aws/eks-anywhere/tree/main/pkg/gitops/flux"
    click OIDC "https://github.com/aws/eks-anywhere/tree/main/internal/pkg/oidc"
    click S3 "https://github.com/aws/eks-anywhere/tree/main/internal/pkg/s3"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef core fill:#d4edda,stroke:#333,stroke-width:1px
    classDef controllers fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef providers fill:#e0ccff,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
```
