Architecture

SolAr is implemented as a Kubernetes Extension API Server integrated with the Kubernetes API Aggregation Layer. This architectural approach provides several advantages over Custom Resource Definitions (CRDs), including dedicated storage isolation, custom API implementation flexibility, and reduced risk to the hosting cluster's control plane.

graph LR
    subgraph UI["User Interface Layer"]
        User["User / Operator"]
        Kubectl["kubectl"]
        GitOps["GitOps Tools"]
        User --> Kubectl
        GitOps --> Kubectl
    end

    subgraph CP["Control Plane"]
        K8sAPI["K8s API Server"]
        APIAgg["API Aggregation"]
        K8sAPI <--> APIAgg
    end

    subgraph DP["Data Plane"]
        subgraph SolArAPI["SolAr API"]
            SOLARAPI["SolAr API Server"]
            SOLARETCD["SolAr etcd"]
            SOLARAPI <--> SOLARETCD
        end
        subgraph Controllers["SolAr Controller Manager"]
            TargetCtrl["Target Controller"]
            ReleaseCtrl["Release Controller"]
            ProfileCtrl["Profile Controller"]
            RenderTaskCtrl["RenderTask Controller"]
        end
        Discovery["solar-discovery"]
        RenderJob["RenderTask Jobs"]
    end

    subgraph ES["External Services"]
        subgraph US["Upstream"]
            SrcReg["Source Registries<br/>OCI / S3 / Helm"]
        end
        subgraph DS["Downstream"]
            DstReg["Render Registries<br/>OCI"]
        end
    end

    subgraph TC["Target Cluster"]
        Flux["Flux"]
        App["Deployed App"]
        Flux --> App
    end

    Kubectl -->|"API requests"| K8sAPI
    APIAgg -->|"proxies solar.* requests"| SOLARAPI

    ProfileCtrl -->|"watches Profiles +<br/>Targets, creates<br/>ReleaseBindings"| SOLARAPI
    ReleaseCtrl -->|"validates Release →<br/>ComponentVersion"| SOLARAPI
    TargetCtrl -->|"reads ReleaseBindings,<br/>Registries, Releases, CVs;<br/>creates RenderTasks"| SOLARAPI
    RenderTaskCtrl -->|"watches RenderTasks,<br/>reads PushSecret,<br/>updates status"| SOLARAPI
    RenderTaskCtrl -->|"creates + manages Jobs"| RenderJob

    Discovery -->|"scans"| SrcReg
    Discovery -->|"writes Components +<br/>ComponentVersions"| K8sAPI
    RenderJob -->|"pushes charts"| DstReg

    Flux -->|"pulls charts"| DstReg
    Flux -->|"pulls images"| SrcReg

Hold "Alt" / "Option" to enable pan & zoom

Architecture: SolAr System Components and Data Flow

The system follows a layered architecture where users interact through kubectl (or GitOps tools), requests flow through the Kubernetes API aggregation layer to the SolAr API Server. Controllers reconcile the declared resources and drive the rendering pipeline.

Key Design Decisions:

• Extension API Server architecture provides dedicated storage isolation in a separate etcd instance
• Declarative, Kubernetes-native API for GitOps compatibility

Resource Model and Dependencies

graph TB
    subgraph "Catalog Resources"
        Component["Component"]
        ComponentVersion["ComponentVersion"]
    end

    subgraph "Deployment Resources"
        Release["Release"]
        Target["Target"]
        Profile["Profile"]
    end

    subgraph "Binding Resources"
        ReleaseBinding["ReleaseBinding"]
        RegistryBinding["RegistryBinding"]
        Registry["Registry"]
    end

    subgraph "Internal Resources"
        RenderTask["RenderTask"]
    end

    SolArDiscovery["solar-discovery<br/>(standalone)"] -->|"discovers"| ComponentVersion
    SolArDiscovery -->|"discovers"| Component

    ComponentVersion -->|"references"| Component
    Release -->|"references"| ComponentVersion

    Profile -->|"references"| Release
    Profile -->|"creates"| ReleaseBinding

    ReleaseBinding -->|"binds"| Release
    ReleaseBinding -->|"binds"| Target

    Target -->|"references"| Registry
    RegistryBinding -->|"grants access"| Registry
    RegistryBinding -->|"binds"| Target
    Target -->|"creates"| RenderTask

    Registry -->|"provides credentials<br/>and hostname"| RenderTask

Hold "Alt" / "Option" to enable pan & zoom

Resource Roles

• Component / ComponentVersion — catalog entries discovered from OCI registries by solar-discovery.
• Release — declares which ComponentVersion to deploy and with what configuration.
• Target — represents a deployment target (cluster). References a Registry via renderRegistryRef for pushing rendered charts.
• Registry — stores OCI registry hostname and push credentials (solarSecretRef).
• RegistryBinding — grants a specific Target permission to use a specific Registry for chart pushing.
• ReleaseBinding — declares that a Release should be deployed to a Target. Created manually or automatically by the Profile controller.
• Profile — matches Targets by label selector and automatically creates ReleaseBindings for a given Release.
• RenderTask — internal resource created by the Target controller to drive chart rendering jobs.

Controllers

• Rendering pipeline — how Targets, Releases, and RenderTasks produce deployable Helm charts
• Release controller — validates Release → ComponentVersion references
• Profile controller — automates ReleaseBinding creation via label selectors
• Target controller — orchestrates the rendering pipeline per target cluster
• RenderTask controller — lifecycle of individual RenderTask resources

Discovery

• Discovery pipeline — how solar-discovery scans OCI registries and writes Component and ComponentVersion resources