# ibm/ibm-object-csi-driver-operator architecture

> Architecture diagram of the GitHub repository ibm/ibm-object-csi-driver-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/ibm-object-csi-driver-operator
- Repository: https://github.com/ibm/ibm-object-csi-driver-operator

## Overview

##### Project type and purpose
- This is a Kubernetes Operator built with Kubebuilder in Go.
- It implements a CSI-based object storage plugin (“ibm-object-csi-driver-operator”) that dynamically provisions buckets (COS/S3) as PersistentVolumes and mounts them in Pods via plug-in mounters (rclone, s3fs).

##### File structure
- Top-level:
- api/v1alpha1 – API type definitions (CustomResourceDefinitions for IBMObjectCSI and RecoverStaleVolume)
- controllers/ – Reconcile logic for the two controllers, internal utilities, fake clients for testing
- config/ – Kustomize overlays: CRDs, RBAC, Manager Deployment, Webhooks, Prometheus, sample CRs, scorecard tests
- main.go – Boots the controller manager
- Dockerfile, Makefile, PROJECT – Standard operator build/deploy scripts
- version/ – Version info
- Patterns and frameworks:
- Kubebuilder operator pattern (manager, schemes, controllers, webhooks)
- CSI specification (external-provisioner, external-attacher, node-driver-registrar sidecars implied)
- Kustomize for manifest generation

##### Key insights from README
- Operator watches Kubernetes API for PVC/PV requests backed by custom storage classes.
- Supports multi-cloud (IBM, AWS, GCP) via pluggable “client” parameter and mounters.
- Uses standard CSI sidecar architecture inside Pods (node and controller sidecar containers).

##### Detail is vital
- Every major Kubernetes object: CRDs, CRs, ServiceAccount, Roles, RoleBindings, Manager Deployment, DaemonSet, CSI sidecars, external endpoints, Secrets.
- Reconciliation loop inside the operator (watch → reconcile → status update).
- Distinguish data flow (CSI RPC calls, S3 API calls) from control flow (CRD events → operator actions).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane Components
    subgraph "Control Plane" 
        style ControlPlane fill:#cce5ff,stroke:#004085,stroke-width:2px
        APIServer["API Server"]:::controlplane
        Etcd["etcd"]:::controlplane
        ControllerManager["kube-controller-manager"]:::controlplane
    end

    %% Custom Definitions and Resources
    subgraph "Custom Definitions & Resources"
        style CRDs fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
        CRD1["IBMObjectCSI CRD"]:::crd
        CRD2["RecoverStaleVolume CRD"]:::crd
        CR1["IBMObjectCSI CR"]:::cr
        CR2["RecoverStaleVolume CR"]:::cr
    end

    %% Operator Deployment
    subgraph "Operator Deployment (Manager Pod)" 
        style Operator fill:#d4edda,stroke:#155724,stroke-width:2px
        Manager["Controller Manager"]:::operator
        subgraph Controllers
            IBMController["IBMObjectCSIController"]:::operator
            RecoverController["RecoverStaleVolumeController"]:::operator
            CSIControllerSyncer["CSIController Syncer"]:::operator
            CSINodeSyncer["CSINode Syncer"]:::operator
        end
        subgraph Utilities
            CRUtils["CR Utils"]:::util
            StaticGen["Static Resource Generator"]:::util
            CommonInternal["Common Shared Logic"]:::util
            UtilCommon["Util Common"]:::util
            BoolPtr["BoolPtr Utils"]:::util
            FakeClients["Fake Clients"]:::util
        end
        Boot["main.go"]:::util
    end

    %% CSI Components
    subgraph "CSI Components"
        style CSI fill:#fff3cd,stroke:#856404,stroke-width:2px
        CSIControllerDeployment["CSI Controller Deployment"]:::csipods
        CSIDaemonSet["CSI Node DaemonSet"]:::csipods
        Rclone["rclone-mounter"]:::csipods
        S3fs["s3fs-mounter"]:::csipods
    end

    %% External Storage
    subgraph "External Object Storage"
        style Storage fill:#ffe5b4,stroke:#cc8400,stroke-width:2px
        IBMCOS["IBM COS / S3"]:::storage
        AWSS3["AWS S3"]:::storage
        GCPStorage["GCP Storage"]:::storage
    end

    %% Configuration Manifests
    subgraph "Configuration Manifests"
        style Config fill:#e2e3ff,stroke:#4f5d94,stroke-width:2px
        ManagerYAML["Operator Deployment Manifest"]:::config
        RBAC["RBAC Manifests"]:::config
        KustomizeCRD["CRD Kustomization"]:::config
        KustomizeDefault["Default Kustomization"]:::config
        PrometheusCFG["Prometheus Overlay"]:::config
        Samples["Sample CRs"]:::config
        CSIManifests["CSI Aggregated Manifests"]:::config
        DockerfileNode["Dockerfile"]:::config
        MakefileNode["Makefile"]:::config
        PROJECTNode["PROJECT"]:::config
        Version["Version Info"]:::config
    end

    %% User Interaction and Workflow
    User["User (kubectl)"]:::user
    User -->|"apply PVC/StorageClass"| APIServer
    APIServer -->|"store CR"| Etcd
    Etcd -->|"watch events"| ControllerManager
    ControllerManager -->|"invoke reconcile"| Manager
    Manager -->|reconcile CRs| IBMController
    Manager -->|reconcile CRs| RecoverController
    IBMController -->|create CSI resources| CSIControllerDeployment
    RecoverController -->|cleanup volumes| CSIDaemonSet
    CSIControllerSyncer -->|sync controller| CSIControllerDeployment
    CSINodeSyncer -->|sync node| CSIDaemonSet

    %% CSI Data Flow
    subgraph "CSI Data Plane"
        style DataPlane fill:#f8f9fa,stroke:#6c757d,stroke-width:1px
        Kubelet["kubelet"]:::controlplane
        CSIControllerDeployment -->|"gRPC"| CSIDaemonSet
        Kubelet -->|"gRPC"| CSIDaemonSet
        CSIDaemonSet -->|"mount call"| Rclone
        CSIDaemonSet -->|"mount call"| S3fs
        CSIControllerDeployment -->|"API calls"| IBMCOS
        CSIControllerDeployment -->|"API calls"| AWSS3
        CSIControllerDeployment -->|"API calls"| GCPStorage
    end

    %% CRDs and CR Clicks
    click CRD1 "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/crd/bases/objectdriver.csi.ibm.com_ibmobjectcsis.yaml"
    click CRD2 "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/crd/bases/objectdriver.csi.ibm.com_recoverstalevolumes.yaml"
    click CR1 "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/samples/csi_v1alpha1_ibmobjectcsi.yaml"
    click CR2 "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/samples/csi_v1alpha1_recoverstalevolume.yaml"

    %% API Types Clicks
    click IBMController "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/ibmobjectcsi_controller.go"
    click RecoverController "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/recoverstalevolume_controller.go"
    click CSIControllerSyncer "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/syncer/csi_controller.go"
    click CSINodeSyncer "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/syncer/csi_node.go"
    click CRUtils "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/internal/crutils/common.go"
    click StaticGen "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/internal/crutils/static_resource_generator.go"
    click CommonInternal "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/internal/common/common.go"
    click UtilCommon "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/util/common/common.go"
    click BoolPtr "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/controllers/util/boolptr.go"
    click FakeClients "https://github.com/ibm/ibm-object-csi-driver-operator/tree/main/controllers/fake/"
    click Boot "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/main.go"
    click ManagerYAML "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/manager/manager.yaml"
    click RBAC "https://github.com/ibm/ibm-object-csi-driver-operator/tree/main/config/rbac/"
    click KustomizeCRD "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/crd/kustomization.yaml"
    click KustomizeDefault "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/default/kustomization.yaml"
    click PrometheusCFG "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/prometheus/monitor.yaml"
    click CSIManifests "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/config/manifests/kustomization.yaml"
    click DockerfileNode "https://github.com/ibm/ibm-object-csi-driver-operator/tree/main/Dockerfile"
    click MakefileNode "https://github.com/ibm/ibm-object-csi-driver-operator/tree/main/Makefile"
    click PROJECTNode "https://github.com/ibm/ibm-object-csi-driver-operator/tree/main/PROJECT"
    click Version "https://github.com/ibm/ibm-object-csi-driver-operator/blob/main/version/version.go"

    %% Styles
    classDef controlplane fill:#cce5ff,stroke:#004085,color:#004085
    classDef operator fill:#d4edda,stroke:#155724,color:#155724
    classDef csipods fill:#fff3cd,stroke:#856404,color:#856404
    classDef storage fill:#ffe5b4,stroke:#cc8400,color:#cc8400
    classDef crd fill:#e2e3e5,stroke:#6c757d,color:#6c757d,shape:parallelogram
    classDef cr fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef util fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef config fill:#e2e3ff,stroke:#4f5d94,color:#4f5d94
    classDef user fill:#ffffff,stroke:#000000,stroke-width:1px
```
