The csi-scsi-generic CSI driver is the implementation of the Container Storage Interface (CSI) standard to manage volumes on SCSI-connected storage systems in Deckhouse Kubernetes Platform (DKP).

Driver architecture

The following simplifications are made in the diagram:

  • The diagram shows containers in different pods interacting directly with each other. In reality, they communicate via the corresponding Kubernetes Services (internal load balancers). Service names are omitted if they are obvious from the diagram context. Otherwise, the Service name is shown above the arrow.
  • Pods may run multiple replicas. However, each pod is shown as a single replica in the diagram.

The Level 2 C4 architecture of the csi-scsi-generic CSI driver and its interactions with other components of DKP are shown in the following diagram:

CSI driver architecture (csi-scsi-generic)

Driver components

The csi-scsi-generic CSI driver consists of the following components:

  1. Csi-controller (Deployment): Controller Plugin responsible for global volume operations such as creating and deleting volumes, and attaching and detaching volumes from nodes.

    It consists of the following containers:

    • scsi-modules-loader: Init container that loads the Linux kernel module required for iSCSI (iscsi_tcp).

    • controller: Main container implementing CSI driver functionality (capabilities) through the gRPC services Identity Service and Controller Service according to the CSI specification.

    • controller sidecar containers: Kubernetes community-maintained external controllers.

      These controllers are required because the persistent volume controller running in kube-controller-manager (a component of the DKP control plane) does not provide an interface for direct interaction with CSI drivers. External controllers monitor PersistentVolumeClaim resources and call the corresponding CSI driver functions in the controller container. They also perform auxiliary tasks such as retrieving plugin information and capabilities or checking driver health (liveness probe).

      External controllers interact with the controller container over gRPC via Unix sockets.

      The csi-controller includes the following external controllers:

      • Provisioner (external-provisioner): Watches PersistentVolumeClaim resources and calls the RPC methods CreateVolume or DeleteVolume.

      • Attacher (external-attacher): Monitors VolumeAttachment resources after a pod is scheduled to a node.

      • Resizer (external-resizer): Watches updates to PersistentVolumeClaim resources and expands volumes using the ControllerExpandVolume RPC method when a user requests additional storage for a PVC, and the driver supports the EXPAND_VOLUME capability.

      • Livenessprobe: Monitors the health of the CSI driver through the Probe RPC from the Identity Service and exposes the HTTP endpoint /healthz, which is checked by kubelet. If livenessProbe fails, kubelet restarts the csi-controller pod.

  2. Csi-node (DaemonSet): Node Plugin running on all cluster nodes and responsible for local volume mount and unmount operations.

    The plugin has privileged access to the filesystem of each node. On Linux, this requires the CAP_SYS_ADMIN capability. This is necessary to perform mount operations and interact with block devices.

    It consists of the following containers:

    • scsi-modules-loader: Init container that loads the kernel module required for iSCSI (iscsi_tcp).

    • node: Main container implementing CSI driver functionality through the gRPC services Identity Service and Node Service according to the CSI specification.

    • node-driver-registrar: Sidecar container that registers the Node Plugin with kubelet. It calls the RPC methods GetPluginInfo and NodeGetInfo in the node container to retrieve plugin and node information. Communication with the node container occurs over gRPC via a Unix socket.

Driver interactions

The driver interacts with the following components:

  1. Kube-apiserver: Watches PersistentVolume, PersistentVolumeClaim, VolumeAttachment, PendingResizeRequest, SCSIDevice, and SCSITarget resources.

  2. SCSI-connected storage systems: Coordinates the usage of already available SCSI devices, including their binding/cleanup and node attachment.

The following external components interact with the driver:

  1. Kubelet:

    • Checks CSI driver livenessProbe.
    • Registers the Node Plugin.
    • Calls NodeStageVolume, NodeUnstageVolume, NodePublishVolume, and NodeUnpublishVolume RPCs in the Node Plugin.

    Kubelet interacts with the Node Plugin over gRPC via a Unix socket.