synology/synology-csi

Synology CSI Driver for Kubernetes

Synology NAS的官方https://github.com/container-storage-interface%E9%A9%B1%E5%8A%A8%E3%80%82

容器镜像与Kubernetes兼容性

驱动名称: csi.san.synology.com

Synology CSI驱动支持:

• 访问模式: 多Pod读写(Read/Write Multiple Pods)
• 克隆功能
• 扩容功能
• 快照功能

安装

前提条件

• Kubernetes 1.19或更高版本
• 运行以下系统的Synology NAS:
  • DSM 7.0或更高版本
  • DSM UC 3.1或更高版本
• 推荐Go 1.21或更高版本
• (可选) 如果要使用快照功能，Kubernetes集群中必须安装https://github.com/kubernetes-csi/external-snapshotter/tree/v4.0.0/client/config/crd%E5%92%8Chttps://github.com/kubernetes-csi/external-snapshotter/tree/v4.0.0/deploy/kubernetes/snapshot-controller

注意事项

1. 安装CSI驱动前，请确保已在DSM上创建并初始化至少一个存储池和一个卷。
2. 确保Kubernetes集群中的所有工作节点都能连接到DSM。
3. 完成以下步骤后，将安装CSI驱动的完整部署，包括快照器。如果不需要快照功能，可以安装CSI驱动的基本部署。

安装步骤

1. 克隆git仓库: git clone https://github.com/SynologyOpenSource/synology-csi.git

2. 进入目录: cd synology-csi

3. 复制客户端信息模板文件: cp config/client-info-template.yml config/client-info.yml

4. 编辑config/client-info.yml配置DSM连接信息。可以指定CSI卷将在其上创建的一个或多个存储系统。根据需要修改以下参数:

   • host: DSM的IPv4地址
   • port: 连接DSM的端口。默认HTTP端口为5000，HTTPS端口为5001。仅在使用不同端口时更改此项。
   • https: 设置为"true"以使用HTTPS进行安全连接。确保端口也已正确配置。
   • username, password: 连接DSM的凭据

5. 安装

   • YAML方式 运行./scripts/deploy.sh run安装驱动。这将是完整部署，意味着将构建和运行所有CSI服务以及快照器。如果需要不包含快照器的基本部署，请按以下说明更改命令。

     • 完整部署: ./scripts/deploy.sh run
     • 基本部署: ./scripts/deploy.sh build && ./scripts/deploy.sh install --basic

     如果不需要本地构建驱动，而是想从Docker拉取https://hub.docker.com/r/synology/synology-csi%EF%BC%8C%E8%AF%B7%E6%8C%89%E4%BB%A5%E4%B8%8B%E8%AF%B4%E6%98%8E%E8%BF%90%E8%A1%8C%E5%91%BD%E4%BB%A4%E3%80%82

     • 完整部署: ./scripts/deploy.sh install --all
     • 基本部署: ./scripts/deploy.sh install --basic

     运行bash脚本将:

     • 创建名为"synology-csi"的命名空间，驱动将安装在此命名空间中
     • 使用您在先前步骤中配置的client-info.yml中的凭据创建名为"client-info-secret"的密钥
     • 构建本地镜像并部署CSI驱动
     • 创建使用"Retain"策略的名为"synology-iscsi-storage"的默认存储类
     • 创建使用"Delete"策略的名为"synology-snapshotclass"的卷快照类（仅完整部署）

   • HELM (本地开发)

     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. 检查CSI驱动的所有pod状态是否为Running: kubectl get pods -n synology-csi

CSI驱动配置

存储类和密钥是CSI驱动正常运行所必需的。本节说明如何执行以下操作:

1. 创建存储系统密钥（这不是必需的，因为deploy.sh会在您配置前面提到的配置文件时完成所有配置）
2. 配置存储类
3. 配置卷快照类

创建密钥

创建用于指定存储系统地址和凭据（用户名和密码）的密钥。通常配置文件也会设置密钥，但如果仍要创建或重新创建密钥，请按照以下说明操作:

1. 编辑配置文件config/client-info.yml或创建新文件，如下例所示:

   clients:
   - host: 192.168.1.1
     port: 5000
     https: false
     username: <用户名>
     password: <密码>
   - host: 192.168.1.2
     port: 5001
     https: true
     username: <用户名>
     password: <密码>
   

   clients字段可以包含多个Synology NAS，使用前缀"-"分隔。

2. 使用以下命令创建密钥（通常由deploy.sh完成）:

   kubectl create secret -n <命名空间> generic client-info-secret --from-file=config/client-info.yml
   

   • 确保将<命名空间>替换为synology-csi，这是默认命名空间。如有需要，更改为自定义命名空间。
   • 如果将密钥名称"client-info-secret"更改为其他名称，请确保deploy/kubernetes/<k8s版本>/下的所有文件都使用您设置的密钥名称。

创建存储类

创建并应用具有所需属性的存储类。

1. 使用deploy/kubernetes/<k8s版本>/storage-class.yml作为示例创建YAML文件，其内容如下:

   iSCSI协议

   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
   

   SMB/CIFS协议

   创建SMB/CIFS存储类之前，必须创建密钥并指定要授予权限的DSM用户。

   apiVersion: v1
   kind: Secret
   metadata:
     name: cifs-csi-credentials
     namespace: default
   type: Opaque
   stringData:
     username: <用户名>  # 访问共享文件夹的DSM用户账户
     password: <密码>  # 访问共享文件夹的DSM用户密码
   

   创建密钥后，创建存储类并填写node-stage-secret的密钥。如果使用SMB，这是必需步骤，否则在挂载卷时会出错。

   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协议

   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
   

2. 通过在表中分配参数来配置存储类属性。如果没有偏好，可以留空:

   名称	类型	描述	默认值	支持的协议
   dsm	string	DSM的IPv4地址，必须包含在client-info.yml中，以便CSI驱动登录DSM	-	iSCSI, SMB, NFS
   location	string	DSM上创建PersistentVolume的LUN位置(/volume1, /volume2, ...)	-	iSCSI, SMB, NFS
   fsType	string	在pod上挂载时PersistentVolumes的格式化文件系统。此参数仅适用于iSCSI。对于SMB，fsType始终为'cifs'。	'ext4'	iSCSI
   protocol	string	存储后端协议。输入'iscsi'创建LUN，或输入'smb'或'nfs'在DSM上创建共享文件夹。	'iscsi'	iSCSI, SMB, NFS
   formatOptions	string	传递给mkfs.*命令的其他选项/参数。请参阅与您选择的文件系统对应的Linux手册。	-	iSCSI
   enableSpaceReclamation	string	为精简配置的Btrfs LUN启用空间回收以提高存储效率。可能会影响性能和空间显示。	'false'	iSCSI
   enableFuaSyncCache	string	为LUN启用FUA和Sync Cache SCSI命令。	'false'	iSCSI
   csi.storage.k8s.io/node-stage-secret-name	string	node-stage-secret的名称。如果通过SMB访问DSM共享文件夹，则需要。	-	SMB
   csi.storage.k8s.io/node-stage-secret-namespace	string	node-stage-secret的命名空间。如果通过SMB访问DSM共享文件夹，则需要。	-	SMB
   mountPermissions	string	挂载文件夹权限。如果设置为非零，驱动将在挂载后执行chmod	'0750'	NFS

   注意

   • 如果将参数location留空，CSI驱动将选择DSM上有可用存储空间的卷来创建卷。
   • CSI驱动创建的所有iSCSI卷都是DSM上的精简配置LUN，这允许您对其进行快照。

3. 将YAML文件应用到Kubernetes集群:

   kubectl apply -f <storageclass_yaml>
   

创建卷快照类

创建并应用具有所需属性的卷快照类。

1. 使用deploy/kubernetes/<k8s版本>/snapshotter/volume-snapshot-class.yml作为示例创建YAML文件，其内容如下:

   apiVersion: snapshot.storage.k8s.io/v1beta1    # Kubernetes v1.20及以上版本使用v1
   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'
   

2. 通过分配以下参数配置卷快照类属性，所有参数都是可选的:

   名称	类型	描述	默认值	支持的协议
   description	string	DSM上快照的描述	""	iSCSI
   is_locked	string	是否要在DSM上锁定快照	'false'	iSCSI, SMB, NFS

3. 将YAML文件应用到Kubernetes集群:

   kubectl apply -f <volumesnapshotclass_yaml>
   

构建与手动安装

默认情况下，CSI驱动将从Docker Hub拉取最新的https://hub.docker.com/r/synology/synology-csi%E3%80%82

如果要使用本地构建的镜像进行安装，请编辑deploy/kubernetes/<k8s版本>/下的所有文件，并确保每个csi-plugin容器都包含imagePullPolicy: IfNotPresent。

构建

• 要构建CSI驱动，执行make。
• 要构建synocli开发工具，执行make synocli。输出二进制文件将位于bin/synocli。
• 要运行单元测试，执行make test。
• 要构建docker镜像，运行./scripts/deploy.sh build。之后，运行docker images检查新创建的镜像。

安装

• 要安装CSI驱动的所有pod，运行./scripts/deploy.sh install --all
• 要安装不包含快照器的CSI驱动pod，运行./scripts/deploy.sh install --basic
• 运行./scripts/deploy.sh --help查看有关命令用法的更多信息。

卸载

如果不再使用CSI驱动，在卸载前确保Kubernetes集群中没有其他资源使用Synology CSI驱动管理的存储:

• ./scripts/uninstall.sh