# kanisterio/kanister architecture

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

- Interactive diagram: https://gitdiagram.com/kanisterio/kanister
- Repository: https://github.com/kanisterio/kanister

## Overview

##### Project type and purpose
- Kanister is an _open-source, Kubernetes-centric data protection workflow management tool_.
- It implements the Kubernetes Operator pattern (CRDs + controllers), provides a CLI/SDK, and integrates with object stores (S3, Azure, GCS) and backup engines (Kopia).

##### File structure
- Top-level “cmd/” folders hold executables:
- cmd/controller → the Kanister Operator (runs controllers/reconcilers)
- cmd/kanctl → CLI for users to create ActionSets, Blueprints, Profiles, etc.
- cmd/kando → an alternative CLI for event-driven use
- cmd/reposervercontroller → a specialized controller for the RepositoryServer CRD
- “pkg/apis” defines the CRDs (Blueprint, ActionSet, Profile, RepositoryServer).
- “pkg/controllers” and “pkg/controller” contain the reconciliation loops.
- “pkg/function” holds the atomic data-operation functions that run in Job pods.
- “pkg/datamover” abstracts data transfer (push/pull) to object stores.
- “pkg/client” is the Kubernetes client-go code for CRD types.
- “pkg/kanx” implements a gRPC service (kanx server) for synchronous execution.
- “pkg/kopia” provides Kopia integration.
- The “helm/kanister-operator” and “docker” folders contain deployment assets.

##### README for additional insights
- Kanister exposes Custom Resources (Blueprint, ActionSet, Profile, RepositoryServer)
- Users define Blueprints (workflows), instantiate ActionSets, and Kanister’s controllers execute them asynchronously via Job pods or synchronously via ExecStream.
- The operator handles security (RBAC), metrics, and events.

##### Final advice
- Be as granular as reasonable: break out each CRD and its reconciler, the datamover abstraction, kopia integration, and the synchronous ExecStream path.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Tools"
        Kanctl["kanctl CLI"]:::user
        Kanctl_pkg["kanctl SDK"]:::user
        Kando["kando CLI"]:::user
        Kando_pkg["kando SDK"]:::user
        ClientGO["client-go Libraries"]:::user
    end

    API["Kubernetes API Server"]:::controlplane

    subgraph "Operator Deployment"
        CM_main["Controller Manager (main)"]:::controlplane
        CM_core["Controller Manager (core)"]:::controlplane
        Webhook["Validating Webhook"]:::controlplane
        subgraph "Reconcilers"
            Recon_common["Reconciler Core"]:::controlplane
            RS_reconc["RepositoryServer Reconciler"]:::controlplane
        end
    end

    subgraph "Data Plane"
        subgraph "Job Pods"
            Func["Function Execution"]:::dataplane
            DataMover["Data Mover"]:::dataplane
            Kopia["Kopia Integration"]:::dataplane
        end
        RepoServer["RepositoryServer"]:::dataplane
    end

    ObjectStore["Object Store (S3/Azure/GCS)"]:::external
    Metrics["Prometheus & Events"]:::external
    Helm["Helm Charts"]:::external
    Docker["Docker Assets"]:::external

    %% Flows
    Kanctl -->|"create CRDs"| API
    Kando -->|"create CRDs"| API
    ClientGO -->|"interact with CRDs"| API

    API -->|"events"| CM_main
    CM_main --> CM_core
    CM_main --> Webhook
    CM_core --> Recon_common
    Recon_common --> RS_reconc
    Recon_common -->|"spawn Jobs"| Func
    Recon_common -->|"manage RepoServer"| RepoServer

    Func -->|"invoke"| DataMover
    DataMover -->|"push/pull"| ObjectStore
    Func <-->|"sidecar"| Kopia
    Kopia -->|"store data"| ObjectStore

    RepoServer -->|"store data"| ObjectStore

    CM_main -->|"metrics & events"| Metrics

    Helm -->|"deploy Operator"| CM_main
    Docker -->|"build image"| CM_main

    %% Click Events
    click CM_main "https://github.com/kanisterio/kanister/blob/master/cmd/controller/main.go"
    click CM_core "https://github.com/kanisterio/kanister/blob/master/pkg/controller/controller.go"
    click RS_reconc "https://github.com/kanisterio/kanister/blob/master/pkg/controllers/repositoryserver/repositoryserver_controller.go"
    click Kanctl "https://github.com/kanisterio/kanister/blob/master/cmd/kanctl/main.go"
    click Kanctl_pkg "https://github.com/kanisterio/kanister/tree/master/pkg/kanctl"
    click Kando "https://github.com/kanisterio/kanister/blob/master/cmd/kando/main.go"
    click Kando_pkg "https://github.com/kanisterio/kanister/tree/master/pkg/kando"
    click ReposerverController "https://github.com/kanisterio/kanister/blob/master/cmd/reposervercontroller/main.go"
    click CRDs_types "https://github.com/kanisterio/kanister/blob/master/pkg/apis/cr/v1alpha1/types.go"
    click CRDs_yaml "https://github.com/kanisterio/kanister/blob/master/pkg/customresource/*.yaml"
    click Recon_common "https://github.com/kanisterio/kanister/blob/master/pkg/controller/controller.go"
    click Func "https://github.com/kanisterio/kanister/blob/master/pkg/function/*.go"
    click DataMover "https://github.com/kanisterio/kanister/blob/master/pkg/datamover/datamover.go"
    click ClientGO "https://github.com/kanisterio/kanister/tree/master/pkg/client"
    click Kanx_proto "https://github.com/kanisterio/kanister/blob/master/pkg/kanx/kanx.proto"
    click Kanx_server "https://github.com/kanisterio/kanister/blob/master/pkg/kanx/server.go"
    click Kanx_client "https://github.com/kanisterio/kanister/blob/master/pkg/kanx/client.go"
    click Kopia "https://github.com/kanisterio/kanister/tree/master/pkg/kopia"
    click Helm "https://github.com/kanisterio/kanister/tree/master/helm/kanister-operator"
    click Docker "https://github.com/kanisterio/kanister/tree/master/docker/controller/Dockerfile"

    %% Styles
    classDef user fill:#FFD966,stroke:#E69138,color:#000000;
    classDef controlplane fill:#93C47D,stroke:#6AA84F,color:#000000;
    classDef dataplane fill:#76A5AF,stroke:#45818E,color:#FFFFFF;
    classDef external fill:#E06666,stroke:#CC0000,color:#FFFFFF;
```
