# thinkparq/beegfs-csi-driver architecture

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

- Interactive diagram: https://gitdiagram.com/thinkparq/beegfs-csi-driver
- Repository: https://github.com/thinkparq/beegfs-csi-driver

## Overview

##### Project Type & Purpose
- This is a Kubernetes Container Storage Interface (CSI) driver—written in Go—for exposing BeeGFS parallel file systems to container workloads.
- It includes:
- A CSI plugin (Controller, Node, Identity gRPC servers)
- A Kubernetes Operator for day-1/day-2 lifecycle (installation, upgrades)
- Supporting CLI tools, manifests, and E2E tests

##### Key Directories & Architectural Roles
- cmd/beegfs-csi-driver: entrypoint for the CSI driver’s Controller/Node daemons
- pkg/beegfs: core driver logic (controllerserver, nodeserver, identityserver, configuration, thread safety)
- operator/: Kubernetes Operator code (CRDs, controllers, manifests, OLM bundle)
- deploy/k8s: Kustomize bases & overlays for raw kubectl installation
- examples/, docs/: usage patterns, StorageClass/PVC examples, operator vs kubectl deploy guides
- test/e2e & test/nomad: end-to-end validation harnesses for Kubernetes and Nomad

##### Main Components to Sketch
a. Kubernetes Control Plane
- API Server
- CustomResourceDefinitions (BeeGFSDriver CRD managed by Operator)
b. BeeGFS CSI Driver
- Controller plugin (runs as Deployment in beegfs-csi namespace)
- Node plugin (DaemonSet, one pod per node)
- Identity plugin (often co-located with Controller)
c. Kubernetes Operator
- Watches BeeGFSDriver CRD
- Reconciles driver installation, configuration, upgrades via OLM
d. BeeGFS File System
- Management/Metadata/Storage nodes (external cluster)
- The driver communicates via TCP/RDMA to these nodes
e. CSI Sidecar Containers (if diagramming full sidecar pattern)
- External-attacher, external-provisioner, liveness-probe, snapshotter (depending on supported sidecars)

##### Interactions & Data Flows
- (Control Plane) User issues `kubectl apply -k deploy/k8s/...` or Operator CR → K8s API
- Operator reconciler reads CR → updates Kustomize overlays → deploys CSI driver components
- Controller plugin registers with CSI endpoint via gRPC to Kubelet sidecar → advertises CSI capabilities
- Node plugin mounts BeeGFS shares on host → uses beegfs-client DKMS modules
- PVC bind flow:
1. User creates PVC (StorageClass referencing CSI driver)
2. provisioner sidecar calls Controller’s CreateVolume
4. Node’s NodePublishVolume mounts the directory on worker

##### Architectural Patterns & Principles
- CSI standard gRPC plugin pattern (Controller/Node/Identity separation)
- Operator pattern (Kubernetes native lifecycle management via CRDs)
- Kustomize overlay pattern for environment-specific manifests (default, dev, examples)
- Separation of concerns: core driver logic in pkg/, entrypoints in cmd/, orchestration in operator/

##### Technologies & Frameworks to Label
- Go modules (go.mod, go.sum)
- gRPC / CSI spec
- Kubernetes CRD API (apiextensions)
- Kustomize (bases, overlays, patches)
- Container images (Dockerfile in root and operator/)
- Nomad support (deploy/nomad, test/nomad)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        UserCLI["kubectl CLI"]:::cli
        Chwrap["chwrap"]:::cli
    end

    %% Control Plane
    subgraph "Kubernetes Control Plane"
        APIServer["API Server"]:::control
        Etcd["etcd"]:::storage
        BeeGFSCRD["BeeGFSDriver CRD"]:::crd
    end

    %% Operator Layer
    subgraph "Kubernetes Operator"
        OpMain["operator/main.go"]:::operator
        OpAPI["operator/api/v1/beegfsdriver_types.go"]:::operator
        OpController["operator/controllers/beegfsdriver_controller.go"]:::operator
        OpConfig["operator/config/manifests"]:::manifest
        OpBundle["operator/bundle"]:::manifest
    end

    %% CSI Plugin Layer
    subgraph "CSI Plugin Layer"
        subgraph "Controller Pod"
            Controller["beegfs-csi-controller"]:::csi
            ExtProv["external-provisioner"]:::sidecar
            ExtAttach["external-attacher"]:::sidecar
            Liveness["liveness-probe"]:::sidecar
            Identity["identity-server"]:::csi
        end
        subgraph "pkg/beegfs"
            CSImpl["controllerserver.go"]:::code
            NSImpl["nodeserver.go"]:::code
            IDImpl["identityserver.go"]:::code
            ConfigPkg["config.go"]:::code
            CtlPkg["beegfs_ctl.go"]:::code
            UtilPkg["beegfs_util.go"]:::code
            TS["thread_safe.go"]:::code
        end
        subgraph "Node DaemonSet"
            Node["beegfs-csi-node"]:::csi
        end
    end

    %% Storage Layer
    subgraph "Storage Layer"
        BeeGFSFS["BeeGFS Storage Cluster"]:::external
    end

    %% Manifest and Examples
    subgraph "Manifests & Examples"
        KustomizeBases["deploy/k8s/bases"]:::manifest
        KustomizeOverlays["deploy/k8s/overlays"]:::manifest
        NomadDeploy["deploy/nomad"]:::manifest
        ExamplesK8s["examples/k8s"]:::example
        ExamplesNomad["examples/nomad"]:::example
        E2EK8s["test/e2e"]:::test
        E2ENomad["test/nomad"]:::test
        Docs["docs"]:::docs
    end

    %% Repository Root
    subgraph "Repository Root"
        RootDockerfile["Dockerfile"]:::docker
        OpDockerfile["operator/Dockerfile"]:::docker
        GoMod["go.mod"]:::code
        GoSum["go.sum"]:::code
    end

    %% Connections
    UserCLI --> APIServer
    Chwrap --> Node
    APIServer --> BeeGFSCRD
    APIServer --> OpMain
    OpMain -->|"watches"| BeeGFSCRD
    OpMain -->|"reconciles"| OpController
    OpController -->|"deploys"| Controller
    OpController -->|"deploys"| Node
    Controller --> CSImpl
    Controller --> IDImpl
    Node --> NSImpl
    CSImpl --> BeeGFSFS
    NSImpl --> BeeGFSFS
    Identity --> APIServer
    ExtProv --> Controller
    ExtAttach --> Controller
    Liveness --> Controller

    %% Click Events
    click Controller "https://github.com/thinkparq/beegfs-csi-driver/blob/master/cmd/beegfs-csi-driver/main.go"
    click Chwrap "https://github.com/thinkparq/beegfs-csi-driver/blob/master/cmd/chwrap/main.go"
    click CSImpl "https://github.com/thinkparq/beegfs-csi-driver/blob/master/pkg/beegfs/controllerserver.go"
    click NSImpl "https://github.com/thinkparq/beegfs-csi-driver/blob/master/pkg/beegfs/nodeserver.go"
    click IDImpl "https://github.com/thinkparq/beegfs-csi-driver/blob/master/pkg/beegfs/identityserver.go"
    click ConfigPkg "https://github.com/thinkparq/beegfs-csi-driver/blob/master/pkg/beegfs/config.go"
    click CtlPkg "https://github.com/thinkparq/beegfs-csi-driver/blob/master/pkg/beegfs/beegfs_ctl.go"
    click UtilPkg "https://github.com/thinkparq/beegfs-csi-driver/blob/master/pkg/beegfs/beegfs_util.go"
    click TS "https://github.com/thinkparq/beegfs-csi-driver/blob/master/pkg/beegfs/thread_safe.go"
    click OpMain "https://github.com/thinkparq/beegfs-csi-driver/blob/master/operator/main.go"
    click OpAPI "https://github.com/thinkparq/beegfs-csi-driver/blob/master/operator/api/v1/beegfsdriver_types.go"
    click OpController "https://github.com/thinkparq/beegfs-csi-driver/blob/master/operator/controllers/beegfsdriver_controller.go"
    click OpConfig "https://github.com/thinkparq/beegfs-csi-driver/tree/master/operator/config/manifests"
    click OpBundle "https://github.com/thinkparq/beegfs-csi-driver/tree/master/operator/bundle"
    click KustomizeBases "https://github.com/thinkparq/beegfs-csi-driver/tree/master/deploy/k8s/bases"
    click KustomizeOverlays "https://github.com/thinkparq/beegfs-csi-driver/tree/master/deploy/k8s/overlays"
    click NomadDeploy "https://github.com/thinkparq/beegfs-csi-driver/tree/master/deploy/nomad"
    click ExamplesK8s "https://github.com/thinkparq/beegfs-csi-driver/tree/master/examples/k8s"
    click ExamplesNomad "https://github.com/thinkparq/beegfs-csi-driver/tree/master/examples/nomad"
    click E2EK8s "https://github.com/thinkparq/beegfs-csi-driver/tree/master/test/e2e"
    click E2ENomad "https://github.com/thinkparq/beegfs-csi-driver/tree/master/test/nomad"
    click Docs "https://github.com/thinkparq/beegfs-csi-driver/tree/master/docs"
    click RootDockerfile "https://github.com/thinkparq/beegfs-csi-driver/tree/master/Dockerfile"
    click OpDockerfile "https://github.com/thinkparq/beegfs-csi-driver/tree/master/operator/Dockerfile"
    click GoMod "https://github.com/thinkparq/beegfs-csi-driver/blob/master/go.mod"
    click GoSum "https://github.com/thinkparq/beegfs-csi-driver/blob/master/go.sum"

    %% Styles
    classDef cli fill:#EFEFFF,stroke:#8888FF,stroke-width:1px
    classDef control fill:#FFF0F0,stroke:#FF8888,stroke-width:1px
    classDef storage fill:#F0FFF0,stroke:#88FF88,stroke-width:1px
    classDef external fill:#F0FFFF,stroke:#00CCCC,stroke-width:1px
    classDef crd fill:#FFFFE0,stroke:#CCCC00,stroke-width:1px
    classDef operator fill:#FFF0FF,stroke:#CC88CC,stroke-width:1px
    classDef csi fill:#F5F5F5,stroke:#888888,stroke-width:1px
    classDef sidecar fill:#F0F5FF,stroke:#8888FF,stroke-width:1px
    classDef manifest fill:#FFF5E0,stroke:#FFA500,stroke-width:1px
    classDef example fill:#E8F0FF,stroke:#6699FF,stroke-width:1px
    classDef test fill:#FFEFEF,stroke:#FF6666,stroke-width:1px
    classDef docs fill:#F8F8E8,stroke:#CCCC99,stroke-width:1px
    classDef docker fill:#E8FFE8,stroke:#55AA55,stroke-width:1px
    classDef code fill:#F0F0F0,stroke:#AAAAAA,stroke-width:1px
```
