# openkruise/kruise architecture

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

- Interactive diagram: https://gitdiagram.com/openkruise/kruise
- Repository: https://github.com/openkruise/kruise

## Overview

##### Project type and purpose
- Kruise is not a traditional web frontend/backend app but a CNCF‑incubating Kubernetes operator and runtime extension.
- Its purpose is to extend Kubernetes by defining new CRDs (CloneSet, SidecarSet, UnitedDeployment, etc.), running controllers (reconciliation loops), admission webhooks, and a node‑side daemon to manage pods, sidecars, and container runtimes.

##### File structure
- apis/ & config/crd/: CRD definitions for custom workloads.
- cmd/daemon & pkg/daemon/: node‑side daemon that interacts with the container runtime via CRI.
- pkg/controller/: control‑plane controllers implementing reconciliation logic for each CRD.
- pkg/webhook/: mutating & validating admission webhook server.
- pkg/client/, pkg/util/: generated clientsets, informers, listers, utility libraries using client‑go/controller‑runtime.
- config/, scripts/: YAML manifests (RBAC, manager, webhook), Helm hooks, Kustomize setups, CI/CD pipelines.

##### Gather additional insights from README
- Kruise runs as a Deployment (manager) in the Kubernetes control plane and as a DaemonSet (daemon) on each node.
- It uses controller‑runtime for controllers and client‑go informers to watch API objects.
- Webhook server handles admission requests before objects are persisted.

a. Kubernetes Control Plane
- kube‑apiserver + etcd (central API storage)
- CRDs (volume) for each Kruise resource
b. Kruise Manager (controller Deployment)
- Controllers (CloneSet, StatefulSet, SidecarSet, etc.)
- Shared informer‑factory, work queues, reconciliation loops
c. Admission Webhook Server
- Mutating & Validating webhook endpoints
- Kube‑apiserver calls webhooks on CREATE/UPDATE
d. Kruise Daemon (node‑side)
- Runs as a DaemonSet on each node
- Interacts with container runtime (CRI shim)
- Handles image pre‑pull, container recreate, probe management
e. Kubernetes Nodes & Pods
- Standard pods + Kruise‑managed pods
- Sidecar injection paths
f. External Clients & Tools
- kubectl / Helm CLI installing manifests
- Helm hook binary (cmd/helm_hook)

##### Relationships & interactions
- User (kubectl/Helm) → API Server → (Mutation webhook) → etcd
- etcd → Informers in Kruise Manager → enqueue reconciliation
- Controllers → API Server → create/update underlying Kubernetes primitives (Pods, Services, PVCs)
- Pod creations → (Mutation webhook) adds sidecar annotations → Pods scheduled to nodes
- Node kubelet runs Kruise Daemon → Daemon monitors container lifecycles, calls CRI plugin
- Metrics & health probes from both manager and daemon expose endpoints for Prometheus

##### Architectural patterns & design principles
- Kubernetes Controller pattern: informer → workqueue → reconcile
- Event‑driven, declarative — state converges to spec
- CRD extension and admission control (mutating/validating)
- Separation of control‑plane logic (stateless Deployment) and node agent (DaemonSet)
- Use of code‑gen for clientsets/informers (pkg/client), Kustomize for manifest composition

##### Relevant technologies & frameworks
- Go, controller‑runtime, client‑go for controllers and clients
- Kubebuilder conventions (CRD scaffolding)
- Kustomize & Helm for packaging CRDs, RBAC, webhook configurations
- Docker images multi‑arch build, CI pipelines (GitHub Actions)
- CRI shim interfaces for container runtime (pkg/daemon/criruntime)

##### Be very detailed
- Pkg/client informers funneling events into work queues.
- DaemonSet pod on each node, linking to CRI factory abstraction and container runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Tier
    subgraph "External / User Tier"
        direction TB
        KB["kubectl CLI"]:::clients
        HC["Helm CLI"]:::clients
    end

    %% Kubernetes Cluster Boundary
    subgraph "Kubernetes Cluster"
        direction TB

        %% Control Plane Tier
        subgraph "Control Plane Tier"
            direction TB
            APIS["kube-apiserver"]:::control
            ETCD["etcd"]:::storage
            CRDS["CustomResourceDefinitions"]:::storage
            CRDS --> ETCD
            ETCD -->|stores CRDs| APIS

            %% Admission Webhook
            subgraph "Admission Webhook Server"
                direction TB
                WSVC["Service"]:::control
                WDEP["Deployment"]:::control
                WSRV["Webhook Server"]:::control
            end
            APIS -->|"admission request"| WSVC
            WSVC --> WDEP
            WDEP --> WSRV
            WSRV -->|admission response| APIS

            %% Kruise Manager
            subgraph "Kruise Manager Deployment"
                direction TB
                MDEP["Deployment"]:::control
                INF["Shared Informer Factory"]:::control
                WQ["Work Queues"]:::control
                REC["Reconciliation Loops"]:::control
                subgraph "Controllers"
                    direction TB
                    CS["CloneSet Controller"]:::control
                    SS["SidecarSet Controller"]:::control
                    UD["UnitedDeployment Controller"]:::control
                    %% ...other controllers
                end
                MDEP --> INF
                INF --> WQ
                WQ --> REC
                REC --> APIS
                REC -->|"api calls"| APIS
                REC --> CS
                REC --> SS
                REC --> UD
            end

        end

        %% Node Tier
        subgraph "Node Tier"
            direction TB
            KUBELET["kubelet"]:::node
            DS["Kruise DaemonSet Pod"]:::node
            CRI["Container Runtime (CRI)"]:::node
            KUBELET --> DS
            DS -->|cri calls| CRI
        end
    end

    %% External interactions
    KB -->|kubectl api calls| APIS
    HC -->|helm install| APIS

    %% CRD definitions mapping
    click CRDS "https://github.com/openkruise/kruise/tree/master/config/crd/bases/"
    click CRDS "https://github.com/openkruise/kruise/tree/master/apis/"

    %% Kruise Manager mappings
    click MDEP "https://github.com/openkruise/kruise/blob/master/main.go"
    click CS "https://github.com/openkruise/kruise/tree/master/pkg/controller/"
    click SS "https://github.com/openkruise/kruise/tree/master/pkg/controller/"
    click UD "https://github.com/openkruise/kruise/tree/master/pkg/controller/"

    %% Webhook mappings
    click WSRV "https://github.com/openkruise/kruise/blob/master/pkg/webhook/server.go"
    click WSVC "https://github.com/openkruise/kruise/blob/master/config/webhook/manifests.yaml"

    %% Daemon mappings
    click DS "https://github.com/openkruise/kruise/blob/master/cmd/daemon/main.go"
    click DS "https://github.com/openkruise/kruise/tree/master/pkg/daemon/"

    %% Clientsets & utils mappings
    click INF "https://github.com/openkruise/kruise/tree/master/pkg/client/"
    click INF "https://github.com/openkruise/kruise/blob/master/pkg/util/client/client.go"

    %% Helm hook mapping
    click HC "https://github.com/openkruise/kruise/blob/master/cmd/helm_hook/main.go"
    click HC "https://github.com/openkruise/kruise/tree/master/Dockerfile_helm_hook"

    %% Manager & RBAC mapping
    click MDEP "https://github.com/openkruise/kruise/blob/master/config/manager/manager.yaml"
    click MDEP "https://github.com/openkruise/kruise/tree/master/config/rbac/"

    %% Webhook patch mapping
    click WDEP "https://github.com/openkruise/kruise/blob/master/config/default/manager_webhook_patch.yaml"
    click CRDS "https://github.com/openkruise/kruise/tree/master/config/crd/patches/"

    %% Metrics & health mapping
    click ETCD "https://github.com/openkruise/kruise/blob/master/config/prometheus/monitor.yaml"
    click DS "https://github.com/openkruise/kruise/blob/master/pkg/daemon/util/healthz.go"

    %% Feature gates mapping
    click REC "https://github.com/openkruise/kruise/blob/master/pkg/features/kruise_features.go"

    %% Scheme registration mapping
    click MDEP "https://github.com/openkruise/kruise/blob/master/apis/addtoscheme_*.go"

    %% Styles
    classDef control fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef node fill:#ccffcc,stroke:#33cc33,color:#000;
    classDef storage fill:#ffe5b4,stroke:#ff9933,color:#000;
    classDef clients fill:#e0e0e0,stroke:#888,color:#000;
    classDef default stroke:#333,stroke-width:1px;
```
