How thinkparq/beegfs-csi-driver works
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)