# k0rdent/kcm architecture

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

- Interactive diagram: https://gitdiagram.com/k0rdent/kcm
- Repository: https://github.com/k0rdent/kcm

## Overview

##### Project type and purpose
- k0rdent Cluster Manager (KCM) is a Kubernetes “operator” / controller suite delivered as a Helm chart.
- Its purpose is to install CRDs and controllers on a management Kubernetes cluster, then reconcile Management and ClusterDeployment objects to drive multi-cluster provisioning across multiple cloud providers via Cluster-API and Helm charts.

##### File structure
- api/v1alpha1 and api/v1beta1: definitions of all CRDs (Management, ClusterDeployment, Credential, Template, TemplateChain, etc.).
- cmd/main.go: entry point, sets up controller-runtime manager.
- internal/controller: one sub-package per CRD, each implements a Reconciler for the controller pattern.
- internal/webhook: validating/mutating admission webhooks for CRD objects.
- internal/helm: wrapper around the Helm Go client for chart operations.
- internal/metrics, internal/telemetry: emit Prometheus metrics and usage events.
- templates/… and templates/provider/…: Helm charts for cluster templates and provider installations.
- config/dev, mkdocs.yml, hack/…: sample manifests & automation scripts.
- test and test/e2e: unit and end-to-end test suites.

##### README for additional insights
- Describes the key Custom Resources (Management, ClusterDeployment) and their life cycle.
- Recommends installation via Helm, with CRDs, Deployment, Webhooks, and ServiceAccount installed into kcm-system.
- Shows the reconciliation loop: user creates a ClusterDeployment → Helm release in kcm-system installs provider chart → cloud infra is provisioned → status conditions on the CRD are updated.

##### Detail
- Both webhooks (validating/mutating) and controllers.
- Metric endpoint and telemetry client as side-cars or modules.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Plane"
        CLI["kubectl/helm CLI"]:::user
    end

    subgraph "Control Plane"
        subgraph "API & Storage"
            APIServer["K8s API Server"]:::control
            Etcd["etcd"]:::control
        end
        CRDv1alpha1["CRDs v1alpha1"]:::control
        CRDv1beta1["CRDs v1beta1"]:::control

        subgraph "KCM Controller Manager"
            CM["kcm-controller-manager"]:::kcm
            Controllers["Controllers (Reconcilers)"]:::kcm
            Webhooks["Webhooks (Admission Controllers)"]:::kcm
            HelmClient["Helm Client Wrapper"]:::kcm
            Metrics["Metrics Module"]:::kcm
            Telemetry["Telemetry Module"]:::kcm
        end
    end

    subgraph "Data Plane"
        HelmRepo["Helm Repository (OCI/GCR)"]:::external
        ChildRelease["Child Helm Releases"]:::external
        subgraph "Cloud Provider APIs"
            AWS["AWS API"]:::external
            Azure["Azure API"]:::external
            GCP["GCP API"]:::external
            vSphere["vSphere API"]:::external
            OpenStack["OpenStack API"]:::external
            IPAM["IPAM Providers"]:::external
        end
    end

    CLI -->|"create CRD / install chart"| APIServer
    APIServer -->|"Watch CRD events"| Controllers
    APIServer -->|"Validate / Mutate"| Webhooks
    Webhooks -->|"Admission Decision"| APIServer
    Controllers -->|"Reconcile: Read/Write CRD"| APIServer
    Controllers -->|"Install/Upgrade Chart"| HelmClient
    HelmClient -->|"Pull Chart"| HelmRepo
    HelmClient -->|"Deploy Release"| ChildRelease
    ChildRelease -->|"Provision infra"| AWS
    ChildRelease -->|"Provision infra"| Azure
    ChildRelease -->|"Provision infra"| GCP
    ChildRelease -->|"Provision infra"| vSphere
    ChildRelease -->|"Provision infra"| OpenStack
    ChildRelease -->|"Provision infra"| IPAM
    Controllers -->|"Update Status"| APIServer
    Controllers -->|"Emit metrics"| Metrics
    Controllers -->|"Emit events"| Telemetry

    click CM "https://github.com/k0rdent/kcm/blob/main/cmd/main.go"
    click CRDv1alpha1 "https://github.com/k0rdent/kcm/tree/main/api/v1alpha1/"
    click CRDv1beta1 "https://github.com/k0rdent/kcm/tree/main/api/v1beta1/"
    click Controllers "https://github.com/k0rdent/kcm/tree/main/internal/controller/"
    click Webhooks "https://github.com/k0rdent/kcm/tree/main/internal/webhook/"
    click HelmClient "https://github.com/k0rdent/kcm/tree/main/internal/helm/"
    click Metrics "https://github.com/k0rdent/kcm/blob/main/internal/metrics/metrics.go"
    click Telemetry "https://github.com/k0rdent/kcm/tree/main/internal/telemetry/"

    classDef user fill:#ADD8E6,stroke:#333
    classDef control fill:#90EE90,stroke:#333
    classDef kcm fill:#FFA500,stroke:#333
    classDef external fill:#D3D3D3,stroke:#333
```
