synology-csi

Synology CSI Driver for Kubernetes

The official Container Storage Interface driver for Synology NAS.

Container Images & Kubernetes Compatibility

Driver Name: csi.san.synology.com

The Synology CSI driver supports:

• Access Modes: Read/Write Multiple Pods
• Cloning
• Expansion
• Snapshot

Installation

Prerequisites

• Kubernetes versions 1.19 or above
• Synology NAS running:
  • DSM 7.0 or above
  • DSM UC 3.1 or above
  • DSME 1.0 or above
• Go version 1.21 or above is recommended
• (Optional) Both Volume Snapshot CRDs and the common snapshot controller must be installed in your Kubernetes cluster if you want to use the Snapshot feature

Notice

1. Before installing the CSI driver, make sure you have created and initialized at least one storage pool and one volume on your DSM.
2. Make sure that all the worker nodes in your Kubernetes cluster can connect to your DSM.
3. After you complete the steps below, the full deployment of the CSI driver, including the snapshotter, will be installed. If you don’t need the Snapshot feature, you can install the basic deployment of the CSI driver instead.
4. Since v1.4.0 the driver image runs as a non-root user (USER 1000) to satisfy the Red Hat container certification's RunAsNonRoot requirement. The node component still needs root for mounting, iscsiadm, and the host chroot, so the node DaemonSet in the provided manifests overrides this with securityContext.runAsUser: 0 alongside privileged: true. If you write your own node manifest, keep runAsUser: 0, because privileged: true alone does not change the container's runtime user.

Procedure

1. Clone the git repository. git clone https://github.com/SynologyOpenSource/synology-csi.git

2. Enter the directory. cd synology-csi

3. Copy the client-info-template.yml file. cp config/client-info-template.yml config/client-info.yml

4. Edit config/client-info.yml to configure the connection information for DSM. You can specify one or more storage systems on which the CSI volumes will be created. Change the following parameters as needed:

   • host: The IPv4 address of your DSM.
   • port: The port for connecting to DSM. The default HTTP port is 5000 and 5001 for HTTPS. Only change this if you use a different port.
   • https: Set "true" to use HTTPS for secure connections. Make sure the port is properly configured as well.
   • username, password: The credentials for connecting to DSM.
   • tlsCACert: (Optional) PEM-encoded CA certificate used to verify the DSM HTTPS endpoint. Required when DSM uses a self-signed certificate. The system CA pool is always included, so certificates signed by a trusted CA (e.g. Let's Encrypt) do not need to be specified here.
   • tlsServerName: (Optional) Override the server name used for TLS verification. Required when host is an IP address and the DSM certificate only has DNS SANs (the default for DSM self-signed certificates). Set this to the hostname in the certificate's CN or SAN field (e.g. synology).
   • insecureSkipVerify: (Optional) Set "true" to disable TLS certificate verification entirely. Not recommended — use tlsCACert instead. A warning will be logged on every connection when this is enabled.

5. Install

   • YAML Run ./scripts/deploy.sh run to install the driver. This will be a full deployment, which means you'll be building and running all CSI services as well as the snapshotter. If you want a basic deployment, which doesn't include installing a snapshotter, change the command as instructed below.

     • full: ./scripts/deploy.sh run
     • basic: ./scripts/deploy.sh build && ./scripts/deploy.sh install --basic

     If you don’t need to build the driver locally and want to pull the image from Docker instead, run the command as instructed below.

     • full: ./scripts/deploy.sh install --all
     • basic: ./scripts/deploy.sh install --basic

     Running the bash script will:

     • Create a namespace named "synology-csi". This is where the driver will be installed.
     • Create a secret named "client-info-secret" using the credentials from the client-info.yml you configured in the previous step.
     • Build a local image and deploy the CSI driver.
     • Create a default storage class named "synology-iscsi-storage" that uses the "Retain" policy.
     • Create a volume snapshot class named "synology-snapshotclass" that uses the "Delete" policy. (Full deployment only)

   • HELM (Local Development)

     1. kubectl create ns synology-csi; kubectl label ns synology-csi pod-security.kubernetes.io/enforce=privileged --overwrite
     2. kubectl create secret -n synology-csi generic client-info-secret --from-file=./config/client-info.yml
     3. cd deploy/helm; make up

6. Check if the status of all pods of the CSI driver is Running. kubectl get pods -n synology-csi

CSI Driver Configuration

Storage classes and the secret are required for the CSI driver to function properly. This section explains how to do the following things:

1. Create the storage system secret (This is not mandatory because deploy.sh will complete all the configurations when you configure the config file mentioned previously.)
2. Configure storageclasses
3. Configure volumesnapshotclasses

Creating a Secret

Create a secret to specify the storage system address and credentials (username and password). Usually the config file sets up the secret as well, but if you still want to create the secret or recreate it, follow the instructions below:

1. Edit the config file config/client-info.yml or create a new one like the example shown here:

   复制

   clients:
   - host: 192.168.1.1
     port: 5000
     https: false
     username: 
     password: 
   - host: 192.168.1.2
     port: 5001
     https: true
     username: 
     password: 
     tlsCACert: |
       -----BEGIN CERTIFICATE-----
       
       -----END CERTIFICATE-----

   The clients field can contain more than one Synology NAS. Seperate them with a prefix -.

2. Create the secret using the following command (usually done by deploy.sh):

   bash复制

   kubectl create secret -n  generic client-info-secret --from-file=config/client-info.yml

   • Make sure to replace \ with synology-csi. This is the default namespace. Change it to your custom namespace if needed.
   • If you change the secret name "client-info-secret" to a different one, make sure that all files at deploy/kubernetes// are using the secret name you set.

Creating Storage Classes

Create and apply StorageClasses with the properties you want.

1. Create YAML files using the one at deploy/kubernetes//storage-class.yml as the example, whose content is as below:

   iSCSI Protocol

   复制

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     annotations:
       storageclass.kubernetes.io/is-default-class: "false"
     name: synostorage
   provisioner: csi.san.synology.com
   parameters:
     fsType: 'ext4'
     dsm: '192.168.1.1'
     location: '/volume1'
   reclaimPolicy: Retain
   allowVolumeExpansion: true

   SMB/CIFS Protocol

   Before creating an SMB/CIFS storage class, you must create a secret and specify the DSM user whom you want to give permissions to.

   复制

   apiVersion: v1
   kind: Secret
   metadata:
     name: cifs-csi-credentials
     namespace: default
   type: Opaque
   stringData:
     username:   # DSM user account accessing the shared folder
     password:   # DSM user password accessing the shared folder

   After creating the secret, create a storage class and fill the secret for node-stage-secret. This is a required step if you're using SMB, or there will be errors when staging volumes.

   复制

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: synostorage-smb
   provisioner: csi.san.synology.com
   parameters:
     protocol: "smb"
     dsm: '192.168.1.1'
     location: '/volume1'
     csi.storage.k8s.io/node-stage-secret-name: "cifs-csi-credentials"
     csi.storage.k8s.io/node-stage-secret-namespace: "default"
   reclaimPolicy: Delete
   allowVolumeExpansion: true

   NFS Protocol

   复制

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: synostorage-nfs
   provisioner: csi.san.synology.com
   parameters:
     protocol: "nfs"
     dsm: "192.168.1.1"
     location: '/volume1'
     mountPermissions: '0755'
   mountOptions:
     - nfsvers=4.1
   reclaimPolicy: Delete
   allowVolumeExpansion: true

   NVMe/TCP Protocol

   复制

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: synology-nvme-storage
   provisioner: csi.san.synology.com
   parameters:
     protocol: "nvme" # required for nvme protocol
     # dsm: "192.168.1.1"
     # location: '/volume1'
   reclaimPolicy: Delete
   allowVolumeExpansion: true

2. Configure the StorageClass properties by assigning the parameters in the table. You can also leave blank if you don’t have a preference:

   Name	Type	Description	Default	Supported protocols
   dsm	string	The IPv4 address of your DSM, which must be included in the client-info.yml for the CSI driver to log in to DSM	-	iSCSI, SMB, NFS
   location	string	The location (/volume1, /volume2, ...) on DSM where the LUN for PersistentVolume will be created	-	iSCSI, SMB, NFS
   fsType	string	The formatting file system of the PersistentVolumes when you mount them on the pods. This parameter only works with iSCSI. Supported values are ext4 and xfs; btrfs is no longer supported since v1.4.0 (see the notice below). For SMB, the fsType is always ‘cifs‘.	'ext4'	iSCSI
   protocol	string	The storage backend protocol. Enter ‘iscsi’ to create LUNs, 'nvme' to create NVMe namespaces, or ‘smb‘ or 'nfs' to create shared folders on DSM.	'iscsi'	iSCSI, SMB, NFS, NVMe
   formatOptions	string	Additional options/arguments passed to mkfs.* command. See a linux manual that corre