Synology CSI Driver

https://github.com/synologyopensource/synology-csi
Admin
The official Container Storage Interface driver for Synology NAS, supporting iSCSI, SMB, NFS...
Tokens:3,968
Snippets:58
Trust Score:8.6
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone and Initialize Repository

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Initial steps to prepare the local environment for driver installation.

```bash
git clone https://github.com/SynologyOpenSource/synology-csi.git
```

```bash
cd synology-csi
```

```bash
cp config/client-info-template.yml config/client-info.yml
```

--------------------------------

### Installation Commands

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Scripts to deploy the CSI driver components to the Kubernetes cluster.

```bash
./scripts/deploy.sh install --all
```

```bash
./scripts/deploy.sh install --basic
```

```bash
./scripts/deploy.sh --help
```

--------------------------------

### Install from Source using Makefile

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Installs the Helm chart from a local source directory using the provided Makefile.

```bash
$ make up
```

```bash
$ make
```

--------------------------------

### Get Helm Release Details

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/templates/NOTES.txt

Command to retrieve all details about the installed Helm release.

```bash
helm get all {{ .Release.Name }} --namespace {{ .Release.Namespace }}
```

--------------------------------

### Install the Chart

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Installs the Synology CSI chart in a Kubernetes cluster.

```bash
helm install <release-name> synology-csi-chart/synology-csi
```

--------------------------------

### Define Client Configuration

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Example YAML structure for defining Synology NAS client connection details in the client-info.yml file.

```yaml
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>
```

--------------------------------

### Verify Driver Installation

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Check the status of the CSI driver pods to ensure successful deployment.

```bash
kubectl get pods -n synology-csi
```

--------------------------------

### Define VolumeSnapshotClass

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Example YAML configuration for a VolumeSnapshotClass resource.

```yaml
apiVersion: snapshot.storage.k8s.io/v1beta1    # v1 for kubernetes v1.20 and above
kind: VolumeSnapshotClass
metadata:
  name: synology-snapshotclass
  annotations:
    storageclass.kubernetes.io/is-default-class: "false"
driver: csi.san.synology.com
deletionPolicy: Delete
# parameters:
#   description: 'Kubernetes CSI'
#   is_locked: 'false'
```

--------------------------------

### Example Secret for Client Info

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

An example of a Kubernetes Secret containing client connection parameters and credentials for accessing a Synology Diskstation.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: <release-name>-client-info
data:
  client-info.yaml: |-
    Y2xpZW50czoKLSBob3N0OiAxOTIuMTY4LjEuMQogIGh0dHBzOiBmYWxzZQogIHBhc3N3b3JkOiBwYXNzd29yZAogIHBvcnQ6IDUwMDAKICB1c2VybmFtZTogdXNlcm5hbWU KLSBob3N0OiAxOTIuMTY4LjEuMQogIGh0dHBzOiBmYWxzZQogIHBhc3N3b3JkOiBwYXNzd29yZAogIHBvcnQ6IDUwMDEKICB1c2VybmFtZTogdXNlcm5hbWU=
```

--------------------------------

### Check Helm Release Status

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/templates/NOTES.txt

Command to check the status of the installed Helm release.

```bash
helm status {{ .Release.Name }} --namespace {{ .Release.Namespace }}
```

--------------------------------

### Get Plugin Container Logs

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Retrieves the logs from the 'plugin' container within the controller pod, identified by the helm.sh/template=controller.yaml label in the specified namespace.

```bash
$ kubectl logs -n $NAMESPACE -l helm.sh/template=controller.yaml -c plugin
[...]
2022-01-25T08:19:57Z [INFO] [driver/utils.go:104] GRPC call: /csi.v1.Controller/CreateVolume
2022-01-25T08:19:57Z [INFO] [driver/utils.go:105] GRPC request: {"capacity_range":{"required_bytes":1073741824},"name":"pvc-a3d7962b-0ab5-4184-b545-a44cc424aaf1","parameters":{"fsType":"ext4"},"volume_capabilities":[{"AccessType":{"Mount":{"fs_type":"ext4"}},"access_mode":{"mode":1}}]}}
2022-01-25T08:19:57Z [ERROR] [driver/utils.go:108] GRPC error: rpc error: code = Internal desc = Couldn't find any host available to create Volume
```

--------------------------------

### Build and Test Commands

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Commands to compile the driver, development tools, and run unit tests.

```bash
make
```

```bash
make synocli
```

```bash
make test
```

--------------------------------

### Deploy CSI Driver via Helm

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Commands to manually set up the namespace, secrets, and deploy the driver using Helm for local development.

```bash
kubectl create ns synology-csi; kubectl label ns synology-csi pod-security.kubernetes.io/enforce=privileged --overwrite
```

```bash
kubectl create secret -n synology-csi generic client-info-secret --from-file=./config/client-info.yml
```

```bash
cd deploy/helm; make up
```

--------------------------------

### Docker Image Management

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Commands to build the container image and verify its existence.

```bash
./scripts/deploy.sh build
```

```bash
docker images
```

--------------------------------

### Deploy CSI Driver via Shell Script

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Commands to deploy the driver using the provided deployment script, supporting both full and basic configurations.

```bash
./scripts/deploy.sh run
```

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

```bash
./scripts/deploy.sh install --all
```

```bash
./scripts/deploy.sh install --basic
```

--------------------------------

### Apply Kubernetes StorageClass

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Command to apply a StorageClass configuration file to the cluster.

```bash
kubectl apply -f <storageclass_yaml>
```

--------------------------------

### Apply VolumeSnapshotClass

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Command to apply a VolumeSnapshotClass configuration file to the cluster.

```bash
kubectl apply -f <volumesnapshotclass_yaml>
```

--------------------------------

### Automated Testing

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Runs automated tests for the Synology CSI chart, including creating and mounting a PersistentVolumeClaim.

```bash
$ make test
```

--------------------------------

### Uninstallation Command

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Script to remove the CSI driver from the cluster.

```bash
./scripts/uninstall.sh
```

--------------------------------

### Create Kubernetes Secret

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Command to create a Kubernetes secret from the client-info.yml configuration file.

```bash
kubectl create secret -n <namespace> generic client-info-secret --from-file=config/client-info.yml
```

--------------------------------

### Describe Test Pod

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Describes the pod associated with the test job, filtering by the helm.sh/template=test.yaml label in the specified namespace.

```bash
$ kubectl describe pods -n $NAMESPACE -l helm.sh/template=test.yaml
[...]
Volumes:
  data:
    Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
    ClaimName:  synology-csi-test
    ReadOnly:   false
[...]
Events:
  Type     Reason            Age                 From               Message
  ----     ------            ----                ----               -------
  Warning  FailedScheduling  3m6s                default-scheduler  0/4 nodes are available: 4 pod has unbound immediate PersistentVolumeClaims.
  Warning  FailedScheduling  61s (x1 over 2m1s)  default-scheduler  0/4 nodes are available: 4 pod has unbound immediate PersistentVolumeClaims.
```

--------------------------------

### Add Helm Repository

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Adds the Synology CSI chart repository to Helm.

```bash
helm repo add synology-csi-chart https://christian-schlichtherle.github.io/synology-csi-chart
```

--------------------------------

### Configure NVMe/TCP StorageClass

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

StorageClass definition for the NVMe/TCP protocol.

```yaml
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
```

--------------------------------

### Setting the Namespace

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Sets the NAMESPACE environment variable to 'synology-csi' for subsequent kubectl commands.

```bash
$ NAMESPACE=synology-csi
```

--------------------------------

### Configure SMB/CIFS Credentials Secret

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

Secret definition required for SMB/CIFS storage class authentication.

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

--------------------------------

### Uninstalling the Chart

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Command to uninstall the chart.

```bash
$ make down
```

--------------------------------

### Configure SMB/CIFS StorageClass

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

StorageClass definition for the SMB/CIFS protocol, referencing the required credentials secret.

```yaml
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
```

--------------------------------

### Describe Test PVC

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Describes the PersistentVolumeClaim associated with the test job, filtering by the helm.sh/template=test.yaml label in the specified namespace.

```bash
$ kubectl describe pvc -n $NAMESPACE -l helm.sh/template=test.yaml
[...]
Events:
  Type     Reason                Age                     From                                                                  Message
  ----     ------                ----                    ----                                                                  -------
  Normal   Provisioning          4m2s (x9 over 8m17s)    csi.san.synology.com_kolossus-3_c3a0b188-fa91-409b-a4d1-0316d5ffbbd6  External provisioner is provisioning volume for claim "synology-csi/synology-csi-test"
  Warning  ProvisioningFailed    4m2s (x9 over 8m17s)    csi.san.synology.com_kolossus-3_c3a0b188-fa91-409b-a4d1-0316d5ffbbd6  failed to provision volume with StorageClass "synology-csi-delete": rpc error: code = Internal desc = Couldn't find any host available to create Volume
  Normal   ExternalProvisioning  2m25s (x26 over 8m17s)  persistentvolume-controller                                           waiting for a volume to be created, either by external provisioner "csi.san.synology.com" or manually created by system administrator
```

--------------------------------

### Configure NFS StorageClass

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

StorageClass definition for the NFS protocol.

```yaml
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
```

--------------------------------

### Configure iSCSI StorageClass

Source: https://github.com/synologyopensource/synology-csi/blob/main/README.md

StorageClass definition for the iSCSI protocol.

```yaml
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: 'btrfs'
  dsm: '192.168.1.1'
  location: '/volume1'
  formatOptions: '--nodiscard'
reclaimPolicy: Retain
allowVolumeExpansion: true
```

--------------------------------

### Uninstall the Chart

Source: https://github.com/synologyopensource/synology-csi/blob/main/deploy/helm/README.md

Uninstalls the Synology CSI chart from a Kubernetes cluster.

```bash
helm delete <release-name>
```
Tokens:
Raw