[feat] Enable support for encrypted volumes for CSI driver

docs/encrypted-drives.md

@@ -1,4 +1,86 @@
-## 🔒 Encrypted Drives using LUKS
+## 📜 Table of Contents
+
+1. [🔒 Encrypted Block Storage](#encrypted-block-storage)
+    - [Example StorageClass](#example-storageclass-with-blockstorage)
+    - [Example PVC](#example-pvc-for-blockstorage)
+2. [🔒 Encrypted Drives using LUKS](#encrypted-drives-using-luks)
+    - [Example StorageClass with LUKS](#example-storageclass-with-luks)
+    - [Example PVC with LUKS](#example-pvc-with-luks)
+
+**NOTE**: LUKS encryption allows users to bring their own keys and manage them, while BlockStorage encryption is managed by Linode and it's automatically handled on the backend.
+
+### Encrypted Block Storage
+
+**Notes**:
+
+1. **Setting Up Encryption**: In the provided StorageClasses, encryption is activated by specifying `linodebs.csi.linode.com/encrypted: "true"` in the `parameters` field. This signals the CSI driver to provision volumes with encryption enabled, provided encryption is supported in the specified region.
+2. **Retention and Expansion Options**:
+    - The `linode-block-storage-encrypted` StorageClass uses the default `Delete` reclaim policy, meaning that volumes created with this StorageClass will be deleted when the associated PVC is deleted.
+    - In contrast, the `linode-block-storage-retain-encrypted` StorageClass uses the `Retain` policy. This allows the volume to persist even after the PVC is deleted, ensuring data is preserved until manually removed.
+    - Both StorageClasses support volume expansion through the `allowVolumeExpansion: true` setting, allowing users to resize volumes as needed without data loss.
+
+3. **Default StorageClass Annotation**: By marking both StorageClasses with `storageclass.kubernetes.io/is-default-class: "true"`, they’re eligible to act as default classes. However, Kubernetes will only treat one StorageClass as the actual default. Consider applying this annotation only to the preferred default StorageClass.
+4. **Region Compatibility**: Ensure that encryption is supported in the Linode region where the volumes will be created. If encryption is not available in a specific region, the CSI driver will return an error.
+   - To check if the region has encryption capability visit https://techdocs.akamai.com/linode-api/reference/get-regions
+   - For your specific region, check the `capabilities` and see if `Block Storage Encryption` is listed in it.
+5. **Usage in PersistentVolumeClaims (PVCs)**: Use the `storageClassName` field in a PVC to reference the desired StorageClass (`linode-block-storage-encrypted` or `linode-block-storage-retain-encrypted`). Each PVC will inherit the encryption settings defined in the referenced StorageClass.
+
+#### Example StorageClass with BlockStorage
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: linode-block-storage-encrypted
+  namespace: kube-system
+parameters:
+  linodebs.csi.linode.com/encrypted: "true"
+allowVolumeExpansion: true
+provisioner: linodebs.csi.linode.com
+---
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: linode-block-storage-retain-encrypted
+  namespace: kube-system
+parameters:
+  linodebs.csi.linode.com/encrypted: "true"
+allowVolumeExpansion: true
+provisioner: linodebs.csi.linode.com
+reclaimPolicy: Retain
+```
+
+#### Example PVC for BlockStorage
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: csi-example-pvc-encrypted
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+  storageClassName: linode-block-storage-encrypted
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: csi-example-pvc-encrypted-retain
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+  storageClassName: linode-block-storage-retain-encrypted
+```
+
+---
+
+### Encrypted Drives using LUKS
 
 **Notes:**
 
@@ -12,7 +94,7 @@
     The CSI driver is careful to otherwise keep the secret on an ephemeral tmpfs
     mount and otherwise refuses to continue.
 
-#### 🔑 Example StorageClass
+#### Example StorageClass with LUKS
 
 > [!TIP]
 > To use an encryption key per PVC you can make a new StorageClass/Secret
@@ -45,7 +127,7 @@ stringData:
   luksKey: "SECRETGOESHERE"  
 ```
 
-#### 📝 Example PVC
+#### Example PVC with LUKS
 
 ```yaml
 apiVersion: v1
@@ -72,3 +154,4 @@ spec:
       storage: 10Gi
   storageClassName: linode-block-storage-retain-luks
 ```
+---

helm-chart/csi-driver/values.yaml

@@ -10,7 +10,6 @@ enableMetrics: false
 
 # default metrics address port
 metricsPort: 8081
-
 # (OPTIONAL) Label prefix for the Linode Block Storage volumes created by this driver.
 volumeLabelPrefix: ""
 

internal/driver/controllerserver.go

@@ -75,7 +75,7 @@ func (cs *ControllerServer) CreateVolume(ctx context.Context, req *csi.CreateVol
 
 	// Prepare the volume parameters such as name and SizeGB from the request.
 	// This step may involve calculations or adjustments based on the request's content.
-	volName, sizeGB, size, err := cs.prepareVolumeParams(ctx, req)
+	params, err := cs.prepareVolumeParams(ctx, req)
 	if err != nil {
 		metrics.RecordMetrics(metrics.ControllerCreateVolumeTotal, metrics.ControllerCreateVolumeDuration, metrics.Failed, functionStartTime)
 		return &csi.CreateVolumeResponse{}, err
@@ -93,7 +93,7 @@ func (cs *ControllerServer) CreateVolume(ctx context.Context, req *csi.CreateVol
 	}
 
 	// Create the volume
-	vol, err := cs.createAndWaitForVolume(ctx, volName, sizeGB, req.GetParameters()[VolumeTags], sourceVolInfo, accessibilityRequirements)
+	vol, err := cs.createAndWaitForVolume(ctx, params.VolumeName, req.GetParameters(), params.EncryptionStatus, params.TargetSizeGB, sourceVolInfo, params.Region)
 	if err != nil {
 		metrics.RecordMetrics(metrics.ControllerCreateVolumeTotal, metrics.ControllerCreateVolumeDuration, metrics.Failed, functionStartTime)
 		return &csi.CreateVolumeResponse{}, err
@@ -103,7 +103,7 @@ func (cs *ControllerServer) CreateVolume(ctx context.Context, req *csi.CreateVol
 	volContext := cs.createVolumeContext(ctx, req, vol)
 
 	// Prepare and return response
-	resp := cs.prepareCreateVolumeResponse(ctx, vol, size, volContext, sourceVolInfo, contentSource)
+	resp := cs.prepareCreateVolumeResponse(ctx, vol, params.Size, volContext, sourceVolInfo, contentSource)
 
 	// Record function completion
 	metrics.RecordMetrics(metrics.ControllerCreateVolumeTotal, metrics.ControllerCreateVolumeDuration, metrics.Completed, functionStartTime)

internal/driver/controllerserver_helper.go

@@ -80,8 +80,21 @@ const (
 	// devicePathKey is the key used in the publish context map when a volume is
 	// published/attached to an instance.
 	devicePathKey = "devicePath"
+
+	// volumeEncryption is the key used in the context map for encryption
+	VolumeEncryption = Name + "/encrypted"
 )
 
+// Struct to return volume parameters when prepareVolumeParams is called
+
+type VolumeParams struct {
+	VolumeName       string
+	TargetSizeGB     int
+	Size             int64
+	EncryptionStatus string
+	Region           string
+}
+
 // canAttach indicates whether or not another volume can be attached to the
 // Linode with the given ID.
 //
@@ -186,9 +199,9 @@ func (cs *ControllerServer) getContentSourceVolume(ctx context.Context, contentS
 // attemptCreateLinodeVolume creates a Linode volume while ensuring idempotency.
 // It checks for existing volumes with the same label and either returns the existing
 // volume or creates a new one, optionally cloning from a source volume.
-func (cs *ControllerServer) attemptCreateLinodeVolume(ctx context.Context, label string, sizeGB int, tags string, sourceVolume *linodevolumes.LinodeVolumeKey, accessibilityRequirements *csi.TopologyRequirement) (*linodego.Volume, error) {
+func (cs *ControllerServer) attemptCreateLinodeVolume(ctx context.Context, label, tags, volumeEncryption string, sizeGB int, sourceVolume *linodevolumes.LinodeVolumeKey, region string) (*linodego.Volume, error) {
 	log := logger.GetLogger(ctx)
-	log.V(4).Info("Attempting to create Linode volume", "label", label, "sizeGB", sizeGB, "tags", tags)
+	log.V(4).Info("Attempting to create Linode volume", "label", label, "sizeGB", sizeGB, "tags", tags, "encryptionStatus", volumeEncryption, "region", region)
 
 	// List existing volumes with the specified label
 	jsonFilter, err := json.Marshal(map[string]string{"label": label})
@@ -216,7 +229,7 @@ func (cs *ControllerServer) attemptCreateLinodeVolume(ctx context.Context, label
 		return cs.cloneLinodeVolume(ctx, label, sourceVolume.VolumeID)
 	}
 
-	return cs.createLinodeVolume(ctx, label, sizeGB, tags, accessibilityRequirements)
+	return cs.createLinodeVolume(ctx, label, tags, volumeEncryption, sizeGB, region)
 }
 
 // Helper function to extract region from topology
@@ -237,24 +250,16 @@ func getRegionFromTopology(requirements *csi.TopologyRequirement) string {
 
 // createLinodeVolume creates a new Linode volume with the specified label, size, and tags.
 // It returns the created volume or an error if the creation fails.
-func (cs *ControllerServer) createLinodeVolume(ctx context.Context, label string, sizeGB int, tags string, accessibilityRequirements *csi.TopologyRequirement) (*linodego.Volume, error) {
+func (cs *ControllerServer) createLinodeVolume(ctx context.Context, label, tags, encryptionStatus string, sizeGB int, region string) (*linodego.Volume, error) {
 	log := logger.GetLogger(ctx)
-	log.V(4).Info("Creating Linode volume", "label", label, "sizeGB", sizeGB, "tags", tags)
-
-	// Get the region from req.AccessibilityRequirements if it exists. Fall back to the controller's metadata region if not specified.
-	region := cs.metadata.Region
-	if accessibilityRequirements != nil {
-		if topologyRegion := getRegionFromTopology(accessibilityRequirements); topologyRegion != "" {
-			log.V(4).Info("Using region from topology", "region", topologyRegion)
-			region = topologyRegion
-		}
-	}
+	log.V(4).Info("Creating Linode volume", "label", label, "sizeGB", sizeGB, "tags", tags, "encryptionStatus", encryptionStatus, "region", region)
 
 	// Prepare the volume creation request with region, label, and size.
 	volumeReq := linodego.VolumeCreateOptions{
-		Region: region,
-		Label:  label,
-		Size:   sizeGB,
+		Region:     region,
+		Label:      label,
+		Size:       sizeGB,
+		Encryption: encryptionStatus,
 	}
 
 	// If tags are provided, split them into a slice for the request.
@@ -272,6 +277,30 @@ func (cs *ControllerServer) createLinodeVolume(ctx context.Context, label string
 	return result, nil
 }
 
+// isEncryptionSupported is a helper function that checks if the specified region supports volume encryption.
+// It returns true or false based on the support for encryption in that region.
+func (cs *ControllerServer) isEncryptionSupported(ctx context.Context, region string) (bool, error) {
+	log := logger.GetLogger(ctx)
+	log.V(4).Info("Checking if encryption is supported for region", "region", region)
+
+	// Get the specifications of specified region from Linode API
+	regionDetails, err := cs.client.GetRegion(ctx, region)
+	if err != nil {
+		return false, errInternal("failed to fetch region %s: %v", region, err)
+	}
+
+	// Check if encryption is supported in the specified region
+	for _, capability := range regionDetails.Capabilities {
+		if capability == "Block Storage Encryption" {
+			return true, nil
+		}
+	}
+
+	// If the region was found but does not support encryption, return false
+	log.V(4).Info("Encryption not supported in the specified region", "region", region)
+	return false, nil
+}
+
 // cloneLinodeVolume clones a Linode volume using the specified source ID and label.
 // It returns the cloned volume or an error if the cloning fails.
 func (cs *ControllerServer) cloneLinodeVolume(ctx context.Context, label string, sourceID int) (*linodego.Volume, error) {
@@ -403,25 +432,60 @@ func (cs *ControllerServer) validateCreateVolumeRequest(ctx context.Context, req
 // prepareVolumeParams prepares the volume parameters for creation.
 // It extracts the capacity range from the request, calculates the size,
 // and generates a normalized volume name. Returns the volume name and size in GB.
-func (cs *ControllerServer) prepareVolumeParams(ctx context.Context, req *csi.CreateVolumeRequest) (volumeName string, targetSizeGB int, size int64, err error) {
+func (cs *ControllerServer) prepareVolumeParams(ctx context.Context, req *csi.CreateVolumeRequest) (*VolumeParams, error) {
 	log := logger.GetLogger(ctx)
 	log.V(4).Info("Entering prepareVolumeParams()", "req", req)
 	defer log.V(4).Info("Exiting prepareVolumeParams()")
-
+	// By default, encryption is disabled
+	encryptionStatus := "disabled"
 	// Retrieve the capacity range from the request to determine the size limits for the volume.
 	capRange := req.GetCapacityRange()
 	// Get the requested size in bytes, handling any potential errors.
-	size, err = getRequestCapacitySize(capRange)
+	size, err := getRequestCapacitySize(capRange)
 	if err != nil {
-		return "", 0, 0, err
+		return nil, err
+	}
+
+	// Get the region from req.AccessibilityRequirements if it exists. Fall back to the controller's metadata region if not specified.
+	accessibilityRequirements := req.GetAccessibilityRequirements()
+	region := cs.metadata.Region
+	if accessibilityRequirements != nil {
+		if topologyRegion := getRegionFromTopology(accessibilityRequirements); topologyRegion != "" {
+			log.V(4).Info("Using region from topology", "region", topologyRegion)
+			region = topologyRegion
+		}
 	}
 
 	preKey := linodevolumes.CreateLinodeVolumeKey(0, req.GetName())
-	volumeName = preKey.GetNormalizedLabelWithPrefix(cs.driver.volumeLabelPrefix)
-	targetSizeGB = bytesToGB(size)
+	volumeName := preKey.GetNormalizedLabelWithPrefix(cs.driver.volumeLabelPrefix)
+	targetSizeGB := bytesToGB(size)
+
+	// Check if encryption should be enabled
+	if req.GetParameters()[VolumeEncryption] == True {
+		supported, err := cs.isEncryptionSupported(ctx, region)
+		if err != nil {
+			return nil, err
+		}
+		if !supported {
+			return nil, errInternal("Volume encryption is not supported in the %s region", region)
+		}
+		encryptionStatus = "enabled"
+	}
 
-	log.V(4).Info("Volume parameters prepared", "volumeName", volumeName, "targetSizeGB", targetSizeGB)
-	return volumeName, targetSizeGB, size, nil
+	log.V(4).Info("Volume parameters prepared", "parameters", &VolumeParams{
+		VolumeName:       volumeName,
+		TargetSizeGB:     targetSizeGB,
+		Size:             size,
+		EncryptionStatus: encryptionStatus,
+		Region:           region,
+	})
+	return &VolumeParams{
+		VolumeName:       volumeName,
+		TargetSizeGB:     targetSizeGB,
+		Size:             size,
+		EncryptionStatus: encryptionStatus,
+		Region:           region,
+	}, nil
 }
 
 // createVolumeContext creates a context map for the volume based on the request parameters.
@@ -448,12 +512,12 @@ func (cs *ControllerServer) createVolumeContext(ctx context.Context, req *csi.Cr
 
 // createAndWaitForVolume attempts to create a new volume and waits for it to become active.
 // It logs the process and handles any errors that occur during creation or waiting.
-func (cs *ControllerServer) createAndWaitForVolume(ctx context.Context, name string, sizeGB int, tags string, sourceInfo *linodevolumes.LinodeVolumeKey, accessibilityRequirements *csi.TopologyRequirement) (*linodego.Volume, error) {
+func (cs *ControllerServer) createAndWaitForVolume(ctx context.Context, name string, parameters map[string]string, encryptionStatus string, sizeGB int, sourceInfo *linodevolumes.LinodeVolumeKey, region string) (*linodego.Volume, error) {
 	log := logger.GetLogger(ctx)
-	log.V(4).Info("Entering createAndWaitForVolume()", "name", name, "sizeGB", sizeGB, "tags", tags)
+	log.V(4).Info("Entering createAndWaitForVolume()", "name", name, "sizeGB", sizeGB, "tags", parameters[VolumeTags], "encryptionStatus", encryptionStatus, "region", region)
 	defer log.V(4).Info("Exiting createAndWaitForVolume()")
 
-	vol, err := cs.attemptCreateLinodeVolume(ctx, name, sizeGB, tags, sourceInfo, accessibilityRequirements)
+	vol, err := cs.attemptCreateLinodeVolume(ctx, name, parameters[VolumeTags], encryptionStatus, sizeGB, sourceInfo, region)
 	if err != nil {
 		return nil, err
 	}