# aws-controllers-k8s/ecs-controller architecture

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

- Interactive diagram: https://gitdiagram.com/aws-controllers-k8s/ecs-controller
- Repository: https://github.com/aws-controllers-k8s/ecs-controller

## Overview

##### Project Type and Purpose
- The README makes it clear that this is an ACK service controller for ECS.
- The project provides Kubernetes custom resources definitions (CRDs) and logic to translate desired states (expressed as Kubernetes objects) into AWS ECS API calls.
- It is a controller running inside a Kubernetes cluster, handling reconciliation loops and leveraging AWS SDKs to manage ECS clusters, services, and task definitions.

##### Key Components from the File Structure
- CRD/API Definitions (apis, config/crd, helm/crds):
– The “apis/v1alpha1” directory contains Go files that define the resource types (cluster, service, task definition, etc.) and metadata used in Kubernetes.
– CRD YAML files in “config/crd” and “helm/crds” describe the Kubernetes resource manifests that enable these new resource types.
- Controller and Reconciliation Logic (cmd/controller, pkg/resource):
– “cmd/controller/main.go” is the entry point for the controller application.
– The “pkg/resource” directory is subdivided into folders for each ECS resource type (cluster, service, task_definition). Here you find functions for delta computation, resource management, and SDK interactions.
- Templates for Code Generation (templates):
– Template files (.tpl) are used to generate hooks for each resource type (for operations like create, update, delete) ensuring consistency in the resource SDK.
- Configuration & Deployment (config, helm, olm):
– The “config” folder holds Kubernetes manifests and kustomizations for deploying the controller (including deployment, RBAC, and service configurations).
– Helm charts in the “helm” directory provide packaging for easier deployment.
– The “olm” directory indicates support for Operator Lifecycle Manager, a Kubernetes operator framework.
- Testing (test/e2e):
– End-to-end tests ensure that the controller functions properly in a live or simulated cluster environment.
- Additional project infrastructure:
– CI/CD workflows (.github/workflows) for automation, licensing, contribution, and governance-related files are standard open-source practices.

a. Main Components:
- Kubernetes API Server / Control Plane:
- Hosts the custom resource definitions and manages the cluster state.
- ACK Service Controller:
- The containerized controller (from cmd/controller) running inside the Kubernetes cluster.
- Contains the reconciliation loop and event handling to keep the state in sync.
- Resource Managers (inside pkg/resource):
- Separate internal components or modules handling ECS clusters, services, and task definitions.
- AWS ECS APIs:
- The external AWS services that the controller interacts with, using the AWS SDK.
- Deployment and Management Tools:
- Helm charts and OLM configurations that package and deploy the controller.
- Code Generation Templates:
- Templates that are used to standardize resource hook generation.
- Testing Framework:
- End-to-end tests verifying the controller’s integration with Kubernetes and AWS.

b. Relationships and Interactions:
- The Kubernetes API server issues events and state changes (for CRDs defined by this controller).
- The ACK service controller (deployed via configuration/helm/olm) listens to these events, using the reconciliation logic in cmd/controller.
- When changes are detected, the controller utilizes resource managers (from pkg/resource) to compare desired and actual states, calling AWS ECS APIs as necessary.
- The generated SDKs and hooks (from templates) help structure these API calls.
- Deployment tools show a clear separation between the operational (runtime controller) and the packaging layer (Helm/OLM).
- The E2E testing suite validates the end-to-end flow from CRD creation to performing AWS ECS operations.

c. Architectural Patterns or Design Principles:
- Reconciliation Loop: The core design of a Kubernetes controller.
- Modularity: Different sub-packages (for cluster, service, task definition) indicate a separation of concerns.
- Code Generation: Use of templates for standardized hook implementations.
- Declarative Configuration: Kubernetes manifests in config/ and helm/ directories support a declarative deployment model.
- Operator Pattern: Integration with OLM and design following the operator framework.

d. Relevant Technologies and Frameworks:
- Go programming language for controller logic.
- Kubernetes Custom Resource Definitions (CRDs) for declaring ECS resources.
- AWS SDK for Go to interact with AWS ECS.
- Helm for deployment packaging.
- OLM for operator lifecycle management.
- CI/CD tooling (GitHub Actions) for build and release pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Control Plane Subgraph
    subgraph "Kubernetes Control Plane"
        A1["K8s API Server"]:::control
        A2["CRD API Definitions (apis/v1alpha1)"]:::control
        A3["CRD Manifests (config/crd/bases)"]:::control
        A4["Helm CRDs (helm/crds)"]:::control
    end

    %% ACK Service Controller Subgraph
    subgraph "ACK Service Controller"
        B1["Controller Entry Point (cmd/controller/main.go)"]:::controller
        B5["Code Generation Templates (templates/hooks)"]:::controller
        B2["ECS Cluster Manager (pkg/resource/cluster)"]:::controller
        B3["ECS Service Manager (pkg/resource/service)"]:::controller
        B4["ECS TaskDefinition Manager (pkg/resource/task_definition)"]:::controller
    end

    %% Deployment & Testing Subgraph
    subgraph "Deployment & Testing"
        D1["K8s Deployment Config (config)"]:::deployment
        D2["Helm Charts (helm)"]:::deployment
        D3["Operator Lifecycle Manager Config (olm)"]:::deployment
        D4["End-to-End Tests (test/e2e)"]:::testing
    end

    %% External AWS ECS APIs
    C1["AWS ECS APIs"]:::external

    %% Relationships within Kubernetes Control Plane
    A2 -->|"defines"| A1
    A3 -->|"integrates"| A1
    A4 -->|"integrates"| A1

    %% Relationship from Kubernetes API Server to Controller
    A1 -->|"triggers_reconcile"| B1

    %% Interactions within ACK Service Controller
    B1 -->|"invokes"| B2
    B1 -->|"invokes"| B3
    B1 -->|"invokes"| B4
    B5 -->|"generates_hooks_for"| B1

    %% Controller interactions with AWS ECS APIs
    B2 -->|"manages"| C1
    B3 -->|"manages"| C1
    B4 -->|"manages"| C1

    %% Deployment & Testing feeding into Controller
    D1 -->|"deploys"| B1
    D2 -->|"deploys"| B1
    D3 -->|"deploys"| B1
    D4 -->|"validates"| B1

    %% Click Events
    click A2 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/apis/v1alpha1"
    click A3 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/config/crd/bases"
    click A4 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/helm/crds"
    click B1 "https://github.com/aws-controllers-k8s/ecs-controller/blob/main/cmd/controller/main.go"
    click B2 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/pkg/resource/cluster"
    click B3 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/pkg/resource/service"
    click B4 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/pkg/resource/task_definition"
    click B5 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/templates/hooks"
    click D1 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/config"
    click D2 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/helm"
    click D3 "https://github.com/aws-controllers-k8s/ecs-controller/blob/main/olm/olmconfig.yaml"
    click D4 "https://github.com/aws-controllers-k8s/ecs-controller/tree/main/test/e2e"

    %% Styles
    classDef control fill:#FFDDCC,stroke:#D2691E,stroke-width:2px;
    classDef controller fill:#CCFFCC,stroke:#008000,stroke-width:2px;
    classDef external fill:#FFE5CC,stroke:#FF8C00,stroke-width:2px;
    classDef deployment fill:#CCE5FF,stroke:#1E90FF,stroke-width:2px;
    classDef testing fill:#E6CCFF,stroke:#800080,stroke-width:2px;
```
