# crossplane-contrib/provider-aws architecture

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

- Interactive diagram: https://gitdiagram.com/crossplane-contrib/provider-aws
- Repository: https://github.com/crossplane-contrib/provider-aws

## Overview

##### Project type and purpose
- This is a Kubernetes “infrastructure provider” plugin (provider-aws) for the Crossplane control plane.
- It defines Custom Resource Definitions (CRDs) for dozens of AWS services, implements controllers that reconcile those CRDs, and uses AWS SDK calls to provision real AWS resources.
- It also includes code‐generation pipelines, example manifests, packaging configuration (Helm/OCI), and CI/CD workflows.

##### File structure
- Top‐level directories:
- apis – Go types and generated deep‐copy, managed‐resource, resolver code defining CRDs and schema for each AWS service.
- pkg/clients – AWS client wrappers and fakes.
- pkg/controller – Individual controller setup, reconcile logic and conversion for each CRD.
- cmd/provider – The main binary that starts the controller manager.
- package/crds – Packaged YAML CRD manifests for installation.
- examples – Example Kubernetes YAMLs showing how users create CRs.
- cluster – Local and image build scripts for running integration tests or deploying on a cluster.
- templates & CODE_GENERATION.md – Code‐gen templates and instructions for adding new APIs.
- .github, Makefile, workflows – CI/CD pipelines, linting, release automation.

##### README for additional insights
- Confirms that this repo produces:
- CRDs modeling AWS infrastructure
- Controllers that provision AWS resources
- Crossplane portable abstractions implementations
- References a code‐generation pipeline and crossplane.io docs for installation/deployment.

a. Main components
- Kubernetes API Server (+ CustomResourceDefinitions)
- provider-aws Controller Manager (a Go binary running controller‐runtime)
– api schemata (types from apis/)
– controllers (pkg/controller/…)
– AWS client layer (pkg/clients)
- AWS Public APIs (one per AWS service domain)
- Crossplane Core (separate control‐plane that delegates to providers)
- Code Generation Toolchain (generate.go, templates/)
- CI/CD pipelines (GitHub workflows, Makefile)
- User Workstation (kubectl + crossplane CLI applying example CRs)

b. Relationships and interactions
- User → kubectl: applies CR YAML from examples/ or generated CRDs.
- API Server → CRDs stored in etcd; notifies controller manager via informers.
- Controller Manager
– Watches CRs → reads desired state
– Calls pkg/clients → AWS SDK calls to create/update/delete AWS resources
– Updates CR status/conditions back into Kubernetes
- Crossplane Core → may call provider-aws as an “Extension” via the same API+controllers.
- Code‐Gen Toolchain → reads generator-config.yaml in apis/*, outputs new types/controllers.
- CI/CD Workflow → builds container images, runs tests, pushes CRD YAML to package/.

c. Architectural patterns and design principles
- Kubernetes Operator pattern (watch → reconcile loop).
- Separation of concerns:
– api types (apis/)
– control logic (pkg/controller/)
– infrastructure client abstraction (pkg/clients/)
- Code generation for boilerplate & consistent APIs.
- Test-driven: each client and controller has unit tests and integration test scripts in cluster/local.
- GitHub Actions for CI, keeping release cadence.

d. Key technologies, frameworks, libraries
- Go + controller-runtime
- Kubernetes API machinery (client-go, code-generator)
- AWS Go SDK v2 (wrapped in pkg/clients)
- GitHub Actions, Makefile
- Crossplane’s plugin and code‐generation pipelines

##### Be detailed and capture essential elements
- Break out controllers by service group if zoomed in (e.g., apis/ec2 + pkg/controller/ec2).
- Common client abstraction layer under all controllers.
- Code‐generation pipeline as a separate flow feeding into apis/ and pkg/controller/.
- CI/CD workflows building and pushing container images and CRD packages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Workstation
    User["User Workstation<br/>(kubectl, crossplane CLI)"]:::user

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        APIServer["Kubernetes API Server<br/>& CustomResourceDefinitions"]:::k8s
        CRDs["Packaged CRD Manifests"]:::k8s
        ControllerMgr["provider-aws Controller Manager"]:::k8s
    end

    %% Controller Manager Internals
    subgraph "Controller Manager Components"
        direction TB
        APITypes["Kubernetes API Schemas (CRD Types)"]:::k8s
        Controllers["Controller Implementations"]:::k8s
        Clients["AWS Client Abstraction Layer"]:::aws
        Features["Feature Flags Registry"]:::k8s
        Utils["Utility Libraries"]:::k8s
        Version["Version Information"]:::k8s
        TestHarness["End-to-End Test Harness"]:::k8s
    end

    %% External Systems
    crossplane["Crossplane Core"]:::k8s
    AWSAPI["AWS Public APIs"]:::aws

    %% Toolchain and CI/CD
    subgraph "Toolchain & CI/CD"
        direction TB
        CodeGen["Code Generation Toolchain"]:::tool
        Templates["Templates"]:::tool
        Instructions["CODE_GENERATION.md"]:::tool
        CI["CI/CD Pipelines"]:::tool
        Workflows["GitHub Actions Workflows"]:::tool
        Make["Makefile"]:::tool
    end

    %% Cluster bootstrap
    ClusterScripts["Local Cluster Bootstrapping<br/>and Image Build Scripts"]:::tool
    Examples["Example Manifests for Users"]:::k8s

    %% Relations
    User -->|"apply CR YAML"| APIServer
    User -->|"apply examples"| Examples
    Examples -->|renders CRs| APIServer
    APIServer -->|"notifies via informers"| ControllerMgr
    ControllerMgr --> APITypes
    ControllerMgr --> Controllers
    ControllerMgr --> Clients
    ControllerMgr --> Features
    ControllerMgr --> Utils
    ControllerMgr --> Version
    ControllerMgr --> TestHarness
    Controllers --> Clients
    ControllerMgr -->|"SDK Calls"| AWSAPI
    ControllerMgr -->|"update CR Status"| APIServer
    crossplane -->|"delegates via CRDs"| ControllerMgr

    CodeGen -->|"generates types/controllers"| APITypes
    CodeGen --> APITypes
    CodeGen --> Controllers

    CI -->|build/push images| ClusterScripts
    CI -->|package CRDs| CRDs

    %% Click Events
    click APITypes "https://github.com/crossplane-contrib/provider-aws/tree/master/apis/"
    click CodeGen "https://github.com/crossplane-contrib/provider-aws/blob/master/apis/generate.go"
    click Templates "https://github.com/crossplane-contrib/provider-aws/tree/master/templates/"
    click Instructions "https://github.com/crossplane-contrib/provider-aws/blob/master/CODE_GENERATION.md"
    click Clients "https://github.com/crossplane-contrib/provider-aws/tree/master/pkg/clients/"
    click Controllers "https://github.com/crossplane-contrib/provider-aws/blob/master/pkg/controller/aws.go"
    click Controllers "https://github.com/crossplane-contrib/provider-aws/tree/master/pkg/controller/"
    click Version "https://github.com/crossplane-contrib/provider-aws/blob/master/pkg/version/version.go"
    click Features "https://github.com/crossplane-contrib/provider-aws/blob/master/pkg/features/features.go"
    click Utils "https://github.com/crossplane-contrib/provider-aws/tree/master/pkg/utils/"
    click TestHarness "https://github.com/crossplane-contrib/provider-aws/blob/master/pkg/test/crds.go"
    click Examples "https://github.com/crossplane-contrib/provider-aws/tree/master/examples/"
    click ClusterScripts "https://github.com/crossplane-contrib/provider-aws/tree/master/cluster/"
    click CI "https://github.com/crossplane-contrib/provider-aws/tree/master/Makefile"
    click Workflows "https://github.com/crossplane-contrib/provider-aws/tree/master/.github/workflows/"
    click CRDs "https://github.com/crossplane-contrib/provider-aws/tree/master/package/crds/"

    %% Styles
    classDef k8s fill:#e0f7fa,stroke:#006064,color:#006064
    classDef aws fill:#e3f2fd,stroke:#0d47a1,color:#0d47a1
    classDef tool fill:#eeeeee,stroke:#424242,color:#424242
    classDef user fill:#fff9c4,stroke:#f57f17,color:#f57f17
```
