The csi-scsi-generic module

The module provides a CSI driver for managing volumes using storage systems connected via SCSI.

Supported features:

• Logical Unit Number (LUN) discovery via iSCSI or Fibre Channel
• Creation of PersistentVolume (PV) from pre-provisioned LUNs
• Deletion of a PV and wiping data on the LUN
• Connecting LUN to nodes via iSCSI or Fibre Channel
• Creating multipath devices and mounting them to pods
• Detaching LUN from nodes

Not supported:

• LUN creation on the storage system
• Resizing LUN
• Creating snapshots

System Requirements and Recommendations

Requirements

• A deployed and configured storage system providing access to LUN via iSCSI or Fibre Channel.

• For iSCSI connections:

  • A unique iSCSI Qualified Name (IQN) must be configured on each Kubernetes node in the /etc/iscsi/initiatorname.iscsi file.
  • The multipath-tools package must be installed on nodes.

• For Fibre Channel connections:

  • Fibre Channel Host Bus Adapters (FC HBA) must be installed and available on cluster nodes (/sys/class/fc_host/host*).
  • In the Storage Area Network (SAN), LUN zoning and masking must be configured, providing node initiators with access to the storage target ports.
  • Necessary LUNs must be pre-provisioned on the storage system. The module does not create LUNs.
  • The multipath-tools package must be installed on nodes.

Quick Start

All commands should be executed on a machine with access to the Kubernetes API and administrator rights.

Enabling the Module

• Enable the csi-scsi-generic module. This will ensure that the following happens on all cluster nodes:
  • The CSI driver is registered.
  • Auxiliary pods for the csi-scsi-generic components are launched.

kubectl apply -f - <<EOF
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: csi-scsi-generic
spec:
  enabled: true
  version: 1
EOF

• Wait for the module to transition to the Ready state.

kubectl get module csi-scsi-generic -w

Creating an SCSITarget (iSCSI)

The SCSITarget resource describes connection to a single SCSI target. Under spec, specify one of the connection types: iSCSI or fibreChannel.

The following is a configuration example for connecting via iSCSI. In this example, two SCSITarget resources are created. You can create multiple resources for either the same or different storage systems. This lets you use multipath to improve failover and performance.

kubectl apply -f -<<EOF
apiVersion: storage.deckhouse.io/v1alpha1
kind: SCSITarget
metadata:
  name: hpe-3par-1
spec:
  deviceTemplate:
    metadata:
      labels:
        my-key: some-label-value
  iSCSI:
    auth:
      login: ""
      password: ""
    iqn: iqn.2000-05.com.3pardata:xxxx1
    portals:
    - 192.168.1.1

---
apiVersion: storage.deckhouse.io/v1alpha1
kind: SCSITarget
metadata:
  name: hpe-3par-2
spec:
  deviceTemplate:
    metadata:
      labels:
        my-key: some-label-value
  iSCSI:
    auth:
      login: ""
      password: ""
    iqn: iqn.2000-05.com.3pardata:xxxx2
    portals:
    - 192.168.1.2
EOF

Creating an SCSITarget (Fibre Channel)

For a Fibre Channel connection, define a World Wide Port Name (WWPN) of the target storage ports in the spec.fibreChannel.WWNs field, which expose the necessary LUNs. The module discovers devices by matching the defined WWPNs against paths under /dev/disk/by-path/.

Define the WWPNs in one of the following formats:

• 16 hexadecimal characters (2001c89f1acd6117)
• With colons (20:01:c8:9f:1a:cd:61:17)
• With the 0x prefix (0x2001c89f1acd6117)

Before creating the SCSITarget resource, configure zoning and LUN masking on the SAN so that cluster nodes can access the necessary LUNs.

The module triggers an FC host scan during discovery and volume attach. It does not configure the commutators or log in to targets.

Configuration example with two target storage system ports for multipath:

kubectl apply -f -<<EOF
apiVersion: storage.deckhouse.io/v1alpha1
kind: SCSITarget
metadata:
  name: hpe-3par-fc-1
spec:
  deviceTemplate:
    metadata:
      labels:
        my-key: some-label-value
  fibreChannel:
    WWNs:
    - 2001c89f1acd6117

---
apiVersion: storage.deckhouse.io/v1alpha1
kind: SCSITarget
metadata:
  name: hpe-3par-fc-2
spec:
  deviceTemplate:
    metadata:
      labels:
        my-key: some-label-value
  fibreChannel:
    WWNs:
    - 2001c89f1acd6118
EOF

Before applying the resource verify that FC paths are available on cluster nodes:

# FC hosts present.
ls /sys/class/fc_host/

# Target WWPNs and LUNs available after zoning.
ls -l /dev/disk/by-path/ | grep -E 'fc-|/fc-'

After the SCSITarget is created, the controller discovers available LUNs and creates SCSIDevice objects. Use the same SCSIStorageClass resource and scsiDeviceSelector workflow as for iSCSI.

To verify that the object has been created, run the following command:

kubectl get scsitargets.storage.deckhouse.io <scsitarget name>

An object is considered to be created successfully if it says Created in the corresponding Phase column in the output.

Creating a StorageClass

To create a StorageClass, use the SCSIStorageClass. An example of commands to create such a resource:

kubectl apply -f -<<EOF
apiVersion: storage.deckhouse.io/v1alpha1
kind: SCSIStorageClass
metadata:
  name: scsi-all
spec:
  scsiDeviceSelector:
    matchLabels:
      my-key: some-label-value
  reclaimPolicy: Delete
EOF

Pay attention to the scsiDeviceSelector. This field is used to select the SCSITarget for PV creation based on labels. In the example above, all SCSITargets with the label my-key: some-label-value are selected. This label will be applied to all devices detected within the specified SCSITarget.

• To verify that the object has been created (Phase should be Created), run:

kubectl get scsistorageclasses.storage.deckhouse.io <scsistorageclass name>

PV cleanup

Since the module does not manage the storage system and re-uses pre-provisioned LUNs from SCSI targets, volumes must be cleaned up after a PV is deleted.

The PV cleanup mode is changed automatically and depends on whether the trim operation is supported.

The cleanup process includes the following steps:

1. Checking the trim operation support. It includes analysis of the /sys/block/${device name}/queue/discard_max_bytes file. If the discard_max_bytes size is more than zero, the operation is supported.
2. The cleanup:
   • If trim is supported, the following command is run: blkdiscard ${device name}.
   • If trim is not supported, the following commend is run: blkdiscard -z ${device name}. The -z option means that the device will be zeroed (completely filled with zeroes).