# castai/cluster-controller architecture

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

- Interactive diagram: https://gitdiagram.com/castai/cluster-controller
- Repository: https://github.com/castai/cluster-controller

## Overview

##### Project type and purpose
- This is a Go-based Kubernetes cluster controller (CLI) for CAST AI.
- It acts as an operator-style controller that pulls “work” from the CAST AI API, reconciles desired state (e.g., charts, node operations) against the Kubernetes API, and reports back status and metrics.

##### File structure
- Top-level “cmd/…” defines three main binaries:
- controller – the core control loop that watches for CAST AI events and applies changes via Kubernetes.
- monitor – a separate process for cluster monitoring tasks.
- testserver – a fake CAST AI API for e2e tests.
- “internal/…” packages implement the core logic:
- internal/actions – handlers for specific event types (chart upsert, drain node, CSR approval, etc.).
- internal/castai – client for the external CAST AI REST API.
- internal/helm – Helm chart loader and client abstraction.
- internal/config, internal/k8sversion, internal/metrics, internal/monitor, internal/waitext – support, utilities, and metrics registration.
- “health/” exposes a simple healthz endpoint.
- “loadtest/” contains load-testing scenarios.
- “e2e/” holds end-to-end tests and an embedded client and fake server.
- “hack/” scripts for local Kind cluster setup, remote cluster deploys, and load-test deployments.
- CI configs, Dockerfile, Makefile, Go module files at root.

##### Key README insights
- Describes the CLI install and run modes:
- On an existing cluster via helm.
- Locally or in Kind for e2e.
- Points at the helm-charts repo as the source of Kubernetes manifests.
- References load tests and e2e flows that leverage the testserver and loadtest packages.

- CLI entrypoint (cmd/controller)
- CAST AI API (external service)
- Kubernetes API Server (cluster)
- Helm Chart Repository (castai-helm-charts)
- internal modules grouped by function (actions, castai client, helm client, config/health/metrics)
- testserver (e2e fake API)
- loadtest harness
- Controller polls (or streams) CAST AI API → events
- events → internal/actions handlers
- handlers → Kubernetes API (create/update resources via client-go & Helm)
- handlers → metrics registry → Prometheus
- healthz endpoint → Kubernetes probe
- testserver ←→ e2e client (during CI)
- loadtest scenarios → controller API endpoints
c. Architectural patterns & principles:
- Controller pattern (informers, handlers, reconciliation loops)
- Modular design: “internal/…” packages separate concerns (API client, helm, actions, retries).
- Dependency injection via interfaces and mocks (see internal/*/mock folders).
- Retry/backoff logic in internal/waitext.
d. Technologies & frameworks:
- Go modules, client-go for Kubernetes, Helm Go SDK
- Cobra for CLI (cmd/*)
- Prometheus metrics (internal/metrics)
- Kind & Helm for local testing (hack/kind/*)
- GitHub Actions for CI, Docker for container builds

##### Elements
- Blue for external services (CAST AI API, Helm repo)
- Green for in-cluster components (Kubernetes API, Controller)
- Yellow for test harness (testserver, loadtest)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    subgraph "Runtime"
        ControllerCLI["Controller (cmd/controller)"]:::cluster
        MonitorCLI["Monitor (cmd/monitor)"]:::cluster
        Healthz["Health Endpoint"]:::internal
        KubeAPI["Kubernetes API Server"]:::cluster
        Prometheus["Prometheus"]:::external
        ExternalAPI["CAST AI API"]:::external
        HelmRepo["Helm Chart Repository"]:::external

        subgraph "Internal Modules"
            CastAIClient["CAST AI API Client"]:::internal
            Actions["Internal Actions Handlers"]:::internal
            HelmClient["Helm Chart Loader & Client"]:::internal
            Config["Configuration & Version"]:::internal
            K8sVersion["K8s Version Utilities"]:::internal
            Metrics["Metrics Registration & Custom Metrics"]:::internal
            MonitorModule["Cluster Monitor Module"]:::internal
            WaitExt["Retry/Backoff Extensions"]:::internal
        end
    end

    %% CI & Test Components
    subgraph "CI & Test"
        TestServer["Testserver (Fake CAST AI API)"]:::test
        E2EClient["E2E Test Client & Suites"]:::test
        LoadTest["Load-Test Harness & Scenarios"]:::test
    end

    %% Relationships
    ControllerCLI -->|"polls REST"| ExternalAPI
    CastAIClient -->|"REST API calls"| ExternalAPI
    ControllerCLI -->|"via client-go & Helm SDK"| KubeAPI
    ControllerCLI -->|"metrics update"| Metrics
    ControllerCLI -->|"/healthz probe"| Healthz

    MonitorCLI -->|"monitors via client-go"| KubeAPI
    MonitorCLI -->|"metrics update"| Metrics
    MonitorModule --> MonitorCLI

    Actions -->|"uses client"| CastAIClient
    Actions -->|"exec hooks"| HelmClient
    Actions -->|"record metrics"| Metrics
    WaitExt --> Actions
    Config --> ControllerCLI
    Config --> MonitorCLI
    K8sVersion --> ControllerCLI

    Healthz -->|"probed by"| KubeAPI
    Metrics -->|"exposed"| Prometheus
    HelmClient -->|"fetch charts"| HelmRepo

    E2EClient -->|"calls"| TestServer
    LoadTest -->|"drives"| ControllerCLI
    LoadTest -->|"drives"| MonitorCLI

    %% Click Events
    click ControllerCLI "https://github.com/castai/cluster-controller/blob/main/cmd/controller/command.go"
    click MonitorCLI "https://github.com/castai/cluster-controller/blob/main/cmd/monitor/command.go"
    click TestServer "https://github.com/castai/cluster-controller/blob/main/cmd/testserver/command.go"
    click Actions "https://github.com/castai/cluster-controller/tree/main/internal/actions/"
    click CastAIClient "https://github.com/castai/cluster-controller/blob/main/internal/castai/client.go"
    click HelmClient "https://github.com/castai/cluster-controller/blob/main/internal/helm/chart_loader.go"
    click Config "https://github.com/castai/cluster-controller/blob/main/internal/config/config.go"
    click K8sVersion "https://github.com/castai/cluster-controller/blob/main/internal/k8sversion/version.go"
    click Metrics "https://github.com/castai/cluster-controller/blob/main/internal/metrics/register.go"
    click MonitorModule "https://github.com/castai/cluster-controller/blob/main/internal/monitor/monitor.go"
    click WaitExt "https://github.com/castai/cluster-controller/blob/main/internal/waitext/extensions.go"
    click Healthz "https://github.com/castai/cluster-controller/blob/main/health/healthz.go"
    click E2EClient "https://github.com/castai/cluster-controller/blob/main/e2e/client/api.gen.go"
    click LoadTest "https://github.com/castai/cluster-controller/blob/main/loadtest/config.go"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef cluster fill:#90EE90,stroke:#000,stroke-width:1px
    classDef internal fill:#FFA500,stroke:#000,stroke-width:1px
    classDef test fill:#FFFF66,stroke:#000,stroke-width:1px
```
