# kro-run/kro architecture

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

- Interactive diagram: https://gitdiagram.com/kro-run/kro
- Repository: https://github.com/kro-run/kro

## Overview

##### Project type and purpose
- This is a Kubernetes Operator project (“kro”) written in Go, with a companion CLI (`kro`), dynamic controller generation, CRD codegen, and a website.
- Its purpose is to let users define “ResourceGraphDefinition” CRDs that group arbitrary Kubernetes resources and declare their dependencies; kro’s controller machinery then generates the CRDs, spins up dedicated controllers, and reconciles instances by creating/managing the underlying resources in the correct order.

##### File structure
- Top-level `cmd/controller`: the static “kro-controller” manager binary
- Top-level `cmd/kro`: the CLI binary with subcommands (`generate`, `validate`, etc.)
- `api/v1alpha1`: Go types & codegen stubs for the core ResourceGraphDefinition CRD
- `pkg/controller`: reconciliation logic for the static controller
- `pkg/dynamiccontroller`: logic to spawn per-ResourceGraphDefinition microcontrollers
- `pkg/graph`, `pkg/runtime`, `pkg/cel`, `pkg/simpleschema`: the internal engine that parses a RGDef, builds its dependency DAG, evaluates parameters (CEL), and drives reconcile loops
- `config/*` & `helm/`: Kubernetes manifests (CRDs, RBAC, kustomize overlays, Helm chart) for installation
- `examples/`, `test/`: sample RGDefs and e2e/integration tests
- `website/`: static site for docs and examples

##### README for additional insights
- Confirms the key custom resource (“ResourceGraphDefinition”)
- Describes two-phase operation:
a) Apply a RGDef → kro controller registers a new CRD & deploys its microcontroller
b) Create instances of that CRD → the microcontroller reconciles and manages underlying K8s resources

a. Main components
- User & CI/CD: invokes `kro` CLI or applies manifests
- Kubernetes API Server (backed by etcd)
- Static kro-controller Manager
- Dynamic Microcontrollers (one per ResourceGraphDefinition)
- Dependency Engine (graph builder, CEL evaluator)
- Underlying Kubernetes Resources (Deployments, Services, ConfigMaps, CRDs)
- Codegen & Build pipelines (GitHub Actions)
- Helm/Kustomize overlays (installation artifacts)
b. Relationships & interactions
1. User runs `kro generate/validate` → local manifests → `kubectl apply` → API Server
2. Static kro-controller watches RGDef CRs → upon new RGDef:
- Run codegen to emit a new CRD
- Register the new CRD with API Server
- Deploy a dynamic controller deployment (pod) for that CRD
3. Dynamic controller watches Instances of its CRD → on reconcile:
- Parsing via Dependency Engine (pkg/graph + pkg/runtime + CEL)
- Compute ordered list of child resources
- Use client-go to Create/Update/Delete each resource in correct order
4. API Server persists everything to etcd
c. Architectural patterns & principles
- Operator pattern (controller runtime, reconcile loops)
- Microcontroller per custom resource (dynamic controller generation)
- Event-driven architecture (watch + reconcile)
- Dependency graph / DAG pattern for ordering operations
- Kubernetes-native extension (CRDs, RBAC, Kustomize, Helm)
d. Key technologies
- Go + controller-runtime + client-go
- CEL (expression evaluation for parameters)
- Kustomize (& `config/` overlays)
- Helm (packaging & distribution)
- GitHub Actions (CI: unit, integration, e2e, image publish)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & CI/CD Layer
    subgraph "User & CI/CD" 
        direction TB
        KroCLI["kro CLI"]:::cli
        CI["GitHub Actions"]:::ci
    end

    %% Control Plane
    subgraph "Control Plane"
        direction TB
        APIServer["API Server\n(etcd)"]:::api
        StaticCtrl["Static Controller\nManager"]:::controller
        CRDDef["ResourceGraphDefinition CRD"]:::crd
    end

    %% Dynamic Runtime
    subgraph "Dynamic Runtime"
        direction TB
        DynCtrl["Dynamic Controller Pod\n(for RGDef X)"]:::controller
        subgraph "Dependency Engine"
            direction TB
            GraphBuilder["Graph Builder"]:::engine
            DAG["DAG Module"]:::engine
            CRDGen["CRD Generation"]:::engine
            Schema["Schema & FieldPath"]:::engine
            Parser["Parser & CEL"]:::engine
            Emulator["Emulator"]:::engine
        end
        Underlying["Underlying K8s Resources"]:::infra
    end

    %% Installation Artifacts
    subgraph "Installation Artifacts"
        direction TB
        Config["Kustomize Overlays\n(config/)"]:::infra
        HelmChart["Helm Chart\n(helm/)"]:::infra
    end

    %% Examples & Tests & Website
    subgraph "Examples / Tests / Website"
        direction TB
        Examples["examples/"]:::infra
        E2E["test/e2e/"]:::infra
        Integration["test/integration/"]:::infra
        Website["website/"]:::infra
    end

    %% Codegen & CI
    Codegen["codegen.go"]:::infra
    CI -->|"triggers build/tests"| KroCLI
    CI -->|"triggers build/tests"| StaticCtrl

    %% Flows
    KroCLI -->|"apply manifests"| APIServer
    APIServer -->|"watch RGDef CRs"| StaticCtrl
    StaticCtrl -->|"create CRD & deploy controller"| APIServer
    StaticCtrl -->|"spawns"| DynCtrl
    DynCtrl -->|"watch Instances"| APIServer
    DynCtrl -->|"uses"| GraphBuilder
    DynCtrl -->|"uses"| DAG
    DynCtrl -->|"uses"| CRDGen
    DynCtrl -->|"uses"| Schema
    DynCtrl -->|"uses"| Parser
    DynCtrl -->|"uses"| Emulator
    DynCtrl -->|"manage"| Underlying

    %% Click Events
    click KroCLI "https://github.com/kro-run/kro/tree/main/cmd/kro"
    click StaticCtrl "https://github.com/kro-run/kro/blob/main/cmd/controller/main.go"
    click CRDDef "https://github.com/kro-run/kro/blob/main/api/v1alpha1/resourcegraphdefinition_types.go"
    click CRDDef "https://github.com/kro-run/kro/blob/main/api/v1alpha1/zz_generated.deepcopy.go"
    click CRDDef "https://github.com/kro-run/kro/blob/main/api/v1alpha1/groupversion_info.go"
    click CRDDef "https://github.com/kro-run/kro/blob/main/api/v1alpha1/conditions.go"
    click ControllerLogic "https://github.com/kro-run/kro/blob/main/pkg/controller/resourcegraphdefinition/controller.go"
    click ControllerLogic "https://github.com/kro-run/kro/blob/main/pkg/controller/resourcegraphdefinition/controller_reconcile.go"
    click ControllerLogic "https://github.com/kro-run/kro/blob/main/pkg/controller/resourcegraphdefinition/controller_status.go"
    click ControllerLogic "https://github.com/kro-run/kro/blob/main/pkg/controller/resourcegraphdefinition/controller_cleanup.go"
    click ControllerLogic "https://github.com/kro-run/kro/tree/main/pkg/controller/instance"
    click DynControllerLogic "https://github.com/kro-run/kro/blob/main/pkg/dynamiccontroller/dynamic_controller.go"
    click DynControllerLogic "https://github.com/kro-run/kro/blob/main/pkg/dynamiccontroller/metrics.go"
    click GraphBuilder "https://github.com/kro-run/kro/blob/main/pkg/graph/builder.go"
    click DAG "https://github.com/kro-run/kro/blob/main/pkg/graph/dag/dag.go"
    click CRDGen "https://github.com/kro-run/kro/blob/main/pkg/graph/crd/crd.go"
    click CRDGen "https://github.com/kro-run/kro/blob/main/pkg/graph/crd/defaults.go"
    click Schema "https://github.com/kro-run/kro/tree/main/pkg/graph/schema/"
    click Schema "https://github.com/kro-run/kro/tree/main/pkg/graph/fieldpath/"
    click Parser "https://github.com/kro-run/kro/tree/main/pkg/graph/parser/"
    click Parser "https://github.com/kro-run/kro/blob/main/pkg/cel/environment.go"
    click Parser "https://github.com/kro-run/kro/tree/main/pkg/cel/library/"
    click Emulator "https://github.com/kro-run/kro/blob/main/pkg/graph/emulator/emulator.go"
    click Emulator "https://github.com/kro-run/kro/blob/main/pkg/graph/resource.go"
    click Runtime "https://github.com/kro-run/kro/blob/main/pkg/runtime/runtime.go"
    click Runtime "https://github.com/kro-run/kro/blob/main/pkg/runtime/resolver/resolver.go"
    click SimpleSchema "https://github.com/kro-run/kro/blob/main/pkg/simpleschema/simplerschema.go"
    click SimpleSchema "https://github.com/kro-run/kro/blob/main/pkg/simpleschema/atomic.go"
    click SimpleSchema "https://github.com/kro-run/kro/blob/main/pkg/simpleschema/transform.go"
    click ClientUtils "https://github.com/kro-run/kro/blob/main/pkg/client/crd.go"
    click ClientUtils "https://github.com/kro-run/kro/blob/main/pkg/client/set.go"
    click ClientUtils "https://github.com/kro-run/kro/blob/main/pkg/client/fake/fake.go"
    click Metadata "https://github.com/kro-run/kro/tree/main/pkg/metadata/"
    click Requeue "https://github.com/kro-run/kro/blob/main/pkg/requeue/requeue.go"
    click Config "https://github.com/kro-run/kro/tree/main/config/crd"
    click Config "https://github.com/kro-run/kro/tree/main/config/rbac"
    click Config "https://github.com/kro-run/kro/tree/main/config/manager"
    click HelmChart "https://github.com/kro-run/kro/blob/main/helm/Chart.yaml"
    click HelmChart "https://github.com/kro-run/kro/blob/main/helm/crds/kro.run_resourcegraphdefinitions.yaml"
    click HelmChart "https://github.com/kro-run/kro/tree/main/helm/templates/"
    click Examples "https://github.com/kro-run/kro/tree/main/examples/"
    click E2E "https://github.com/kro-run/kro/tree/main/test/e2e"
    click Integration "https://github.com/kro-run/kro/tree/main/test/integration"
    click Website "https://github.com/kro-run/kro/tree/main/website/"
    click Codegen "https://github.com/kro-run/kro/blob/main/codegen.go"
    click CI "https://github.com/kro-run/kro/tree/main/.github/workflows/"

    %% Styles
    classDef cli fill:#9cf,stroke:#333,stroke-width:1px;
    classDef ci fill:#bbf,stroke:#333,stroke-width:1px;
    classDef api fill:#cfc,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef controller fill:#fc9,stroke:#333,stroke-width:1px;
    classDef crd fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
    classDef engine fill:#fe9,stroke:#333,stroke-width:1px;
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px;
```
