DOCSEARCHbyAlgolia
Submit Docs

Synology CSI Driver

repository·main·Indexed 20 days ago

https://github.com/synologyopensource/synology-csi

A Container Storage Interface (CSI) driver for Kubernetes that enables interaction with Synology NAS storage. It supports dynamic provisioning, cloning, expansion, and snapshotting of volumes using iSCSI, SMB/CIFS, NFS, and NVMe/TCP protocols. Compatible with Kubernetes 1.20+ and DSM 7.0+.

Tokens
5.7K
Snippets
25
Records
31
Agent score
72%

What's inside synology-csi

  1. Overview of Synology CSI Driver

    main

    The Synology CSI driver is the official Container Storage Interface driver for Synology NAS. It allows Kubernetes clusters to provision and manage storage on Synology systems.

    Key Capabilities:

    • Access Modes: Supports ReadWriteMany (Multiple Pods).
    • Cloning: Create new volumes from existing ones.
    • Expansion: Increase the size of existing volumes.
    • Snapshot: Create point-in-time copies of volumes (requires additional setup).

  2. Features of the Synology CSI Helm Chart

    main

    The Helm chart provides several management capabilities for the Synology CSI Driver:

    • Image Customization: Control images, image pull policies, and tags for all CSI containers.
    • Resource Customization: Configure parameters for StorageClass and VolumeSnapshotClass resources.
    • Workload Scheduling: Customize affinity, nodeSelector, and tolerations for StatefulSet and DaemonSet workloads.
    • Automatic Storage Classes: Automatically installs two storage classes with reclaimPolicy=Delete and reclaimPolicy=Retain.
    • Snapshot Support: Automatically installs a CSI Snapshotter if the VolumeSnapshotClass CRD is detected in the cluster.

  3. Prerequisites for installing Synology CSI Driver

    main

    Before installation, ensure the following requirements are met:

    Kubernetes Requirements:

    Synology NAS Requirements:

    • DSM 7.0 or above, DSM UC 3.1 or above, or DSME 1.0 or above.
    • At least one storage pool and one volume must be created and initialized on the DSM.
    • All Kubernetes worker nodes must have network connectivity to the DSM.

    Development Requirements:

    • Go version 1.21 or above is recommended.

  4. Install the CSI driver via YAML scripts

    main

    You can install the driver using the provided deployment scripts. There are two deployment modes:

    1. Full Deployment

    Includes all CSI services and the snapshotter. Use this if you need the Snapshot feature.

    Build from local source:

    ./scripts/deploy.sh run

    Pull from Docker Hub (no local build):

    ./scripts/deploy.sh install --all

    2. Basic Deployment

    Does not include the snapshotter. Use this if you do not need snapshots.

    Build from local source:

    ./scripts/deploy.sh build && ./scripts/deploy.sh install --basic

    Pull from Docker Hub (no local build):

    ./scripts/deploy.sh install --basic

    What the script does:

    • Creates the synology-csi namespace.
    • Creates a secret named client-info-secret using your client-info.yml.
    • Deploys the CSI driver.
    • Creates a default storage class synology-iscsi-storage (Retain policy).
    • Creates a volume snapshot class synology-snapshotclass (Delete policy) — Full deployment only.
    # Full deployment (build from source)
./scripts/deploy.sh run

# Full deployment (pull from Docker)
./scripts/deploy.sh install --all

# Basic deployment (build from source)
./scripts/deploy.sh build && ./scripts/deploy.sh install --basic

# Basic deployment (pull from Docker)
./scripts/deploy.sh install --basic

  5. Configure StorageClasses for different protocols

    main

    You can provision storage using iSCSI, SMB/CIFS, NFS, or NVMe/TCP protocols by creating a StorageClass with the csi.san.synology.com provisioner.

    iSCSI Protocol

    Used for creating LUNs. Supports fsType and formatOptions.

    SMB/CIFS Protocol

    Requirement: You must first create an Opaque secret containing the DSM user credentials used to access the shared folder. You must then reference this secret in the StorageClass using csi.storage.k8s.io/node-stage-secret-name and csi.storage.k8s.io/node-stage-secret-namespace.

    NFS Protocol

    Used for creating shared folders. Supports mountPermissions (e.g., 0755) and mountOptions (e.g., nfsvers=4.1).

    NVMe/TCP Protocol

    Used for creating NVMe namespaces. Requires protocol: "nvme".

    # Example iSCSI StorageClass
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: synostorage
provisioner: csi.san.synology.com
parameters:
  fsType: 'btrfs'
  dsm: '192.168.1.1'
  location: '/volume1'
  formatOptions: '--nodiscard'
reclaimPolicy: Retain
allowVolumeExpansion: true

  6. Create the storage system secret (client-info-secret)

    main

    The CSI driver requires a secret containing the DSM (DiskStation Manager) addresses and credentials to authenticate with your Synology NAS. While deploy.sh typically handles this, you can create or recreate it manually.

    1. Prepare a config/client-info.yml file with your NAS details:
    clients:
- host: 192.168.1.1
  port: 5000
  https: false
  username: <username>
  password: <password>
- host: 192.168.1.2
  port: 5001
  https: true
  username: <username>
  password: <password>
    1. Create the secret in Kubernetes using kubectl:
    kubectl create secret -n synology-csi generic client-info-secret --from-file=config/client-info.yml

    Note: If you use a custom namespace, replace synology-csi with your namespace. If you rename client-info-secret, you must update all files in deploy/kubernetes/<k8s version>/ to match the new name.

  7. Create VolumeSnapshotClasses

    main

    To enable volume snapshots, create a VolumeSnapshotClass using the csi.san.synology.com driver.

    Parameters:

    • description (string): Description of the snapshot on DSM. Defaults to "".
    • is_locked (string): Whether to lock the snapshot on DSM. Default: 'false'. Supports iSCSI, SMB, and NFS.

    Note: For Kubernetes v1.20 and above, use apiVersion: snapshot.storage.k8s.io/v1. For older versions, use v1beta1.

    apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: synology-snapshotclass
  annotations:
    storageclass.kubernetes.io/is-default-class: "false"
driver: csi.san.synology.com
deletionPolicy: Delete

  8. Prerequisites for Synology CSI Driver

    main

    Before installing the Synology CSI Driver, ensure the following requirements are met:

    • Helm: Installed and configured.
    • Synology Diskstation: Must have the SAN Manager package installed (DSM 7+).
    • Kubernetes: Version 1.20 or later.
    • Node Configuration: iscsiadm must be installed on every cluster node.
    • kubectl: Installed and configured to connect to your cluster.
    • CSI Snapshotter (Optional): If you want to use VolumeSnapshotClass features, ensure the CSI Snapshotter is installed in your cluster.

  9. Build and manually install the CSI driver

    main

    If you are not using the default Docker Hub images, you can build and install the driver manually.

    Building

    • CSI Driver: make
    • synocli dev tool: make synocli (output at bin/synocli)
    • Unit Tests: make test
    • Docker Image: ./scripts/deploy.sh build

    Installation

    To use locally built images, ensure imagePullPolicy: IfNotPresent is set in all csi-plugin containers within deploy/kubernetes/<k8s version>/.

    • Full Installation (including snapshotter): ./scripts/deploy.sh install --all
    • Basic Installation (without snapshotter): ./scripts/deploy.sh install --basic

    Uninstallation

    Ensure no Kubernetes resources are using storage managed by the driver before running:

    ./scripts/uninstall.sh
    # Install all pods
./scripts/deploy.sh install --all

# Install basic pods (no snapshotter)
./scripts/deploy.sh install --basic

  10. Configure DSM connection in client-info.yml

    main

    The driver requires a configuration file to connect to your Synology NAS.

    1. Clone the repository: git clone https://github.com/SynologyOpenSource/synology-csi.git
    2. Navigate to the directory: cd synology-csi
    3. Create the config file from the template: cp config/client-info-template.yml config/client-info.yml
    4. Edit config/client-info.yml with the following parameters:
      • host: The IPv4 address of your DSM.
      • port: The DSM connection port (default HTTP: 5000, HTTPS: 5001).
      • https: Set to true if using HTTPS.
      • username: DSM credentials.
      • password: DSM credentials.
    git clone https://github.com/SynologyOpenSource/synology-csi.git
cd synology-csi
cp config/client-info-template.yml config/client-info.yml

  11. Install the CSI driver via Helm (Local Development)

    main

    For local development, use the Helm deployment process:

    1. Create the namespace and apply required security labels: kubectl create ns synology-csi; kubectl label ns synology-csi pod-security.kubernetes.io/enforce=privileged --overwrite
    2. Create the secret from your configuration: kubectl create secret -n synology-csi generic client-info-secret --from-file=./config/client-info.yml
    3. Deploy using make: cd deploy/helm; make up
    kubectl create ns synology-csi; kubectl label ns synology-csi pod-security.kubernetes.io/enforce=privileged --overwrite
kubectl create secret -n synology-csi generic client-info-secret --from-file=./config/client-info.yml
cd deploy/helm; make up

  12. Install the Synology CSI Chart via Helm

    main

    To install the Synology CSI Driver in a Kubernetes cluster, use the official Helm chart.

    1. Add the Helm repository:
      helm repo add synology-csi-chart https://christian-schlichtherle.github.io/synology-csi-chart
helm repo update
    2. Install the chart:
      helm install <release-name> synology-csi-chart/synology-csi

    To uninstall the driver, run:

    helm delete <release-name>
    helm repo add synology-csi-chart https://christian-schlichtherle.github.io/synology-csi-chart
helm repo update
helm install <release-name> synology-csi-chart/synology-csi