Synology CSI 驱动：Kubernetes 持久化存储方案

1. 持久化方案简介

在使用 Kubernetes (K8s) 时，存储方案的选择至关重要。对于群晖 (Synology) NAS 用户，推荐使用官方提供的 CSI 驱动，它支持动态创建存储资源并挂载给 Pod。

1.1 iSCSI 方案 (本项目推荐)

• 特点：非常适合个人、家庭用户及中小企业，追求性能、稳定且配置轻量。
• 适用场景：数据库类应用、虚拟化存储、对 I/O 性能要求较高的有状态服务。
• 原理：基于块级（Block-level）存储，当 Pod 申请存储空间时，CSI 驱动通过 API 调用群晖 DSM，在 NAS 上自动创建 iSCSI LUN 和 Target，并将其映射给 K8s 节点。
• 优势：性能最接近原生硬盘，延迟低，支持空间回收（Thin Provisioning），且无需复杂的集群维护。
• 项目地址：Synology CSI Driver

1.2 SMB/NFS 方案

• 特点：配置简单，属于文件级（File-level）共享，性能相对 iSCSI 稍逊。
• 适用场景：简单文件存储、多 Pod 共享数据、静态资源托管、低频访问的备份数据。

• 差异：

  • NFS：Linux 环境兼容性好，支持多读多写（RWX）。
  • SMB：更适合 Windows 混合环境。

1.3 其他方案 (如 Ceph)

• Ceph：功能极度强大，支持块、文件和对象存储。但其架构复杂，对内存、计算资源及网络带宽要求较高，运维成本大，更适合大规模企业级数据中心。
• 对比：对于拥有群晖 NAS 的个人或家庭用户，Ceph 过重，iSCSI 方案在满足生产级稳定性的同时提供了更好的易用性。
• 注意：本文目前仅专注于群晖 iSCSI 方案的实现与配置，其他存储方案（如 Ceph 的部署与调优）将在日后另行介绍。

2. 配置步骤

2.1 先决条件

• Kubernetes: v1.19 或更高版本。

• Synology NAS:

  • DSM 7.0 或更高版本。
  • DSM UC 3.1 或更高版本。

• 环境准备:

  • （可选）若需自行编译：Go v1.21+。
  • （可选）若需快照功能：需安装 Snapshot Controller，参考 Volume Snapshot CRDs 及 Common Snapshot Controller。

2.2 注意事项

1. 存储初始化：在安装驱动前，必须在 DSM 上至少创建一个存储池（Storage Pool）和存储空间（Volume）。
2. 网络连通性：确保所有 Kubernetes 节点均能访问 DSM 管理地址。

2.3 安装过程

支持通过脚本或 Helm 两种方式部署。

1. 克隆仓库

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

2. 配置连接信息

复制模板文件并编辑 config/client-info.yml，配置 DSM 的连接参数：

• host: DSM 的 IP 地址。
• port: 默认为 5000 (HTTP) 或 5001 (HTTPS)。
• https: 是否启用加密连接。
• username/password: 具备管理权限的账号。

3. 方案一：服务器脚本部署 (推荐)

直接使用预编译镜像安装：

# 安装完整功能 (包含快照)
./scripts/deploy.sh install --all

# 仅安装基本功能
./scripts/deploy.sh install --basic

脚本主要操作：

• 创建 synology-csi 命名空间。
• 创建包含凭据的 client-info-secret。
• 创建默认存储类 synology-iscsi-storage (回收策略：Retain)。
• (仅全量安装) 创建快照类 synology-snapshotclass (回收策略：Delete)。

4. 方案二：本地 Helm 部署

# 创建命名空间并配置安全策略
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

需要更多自定义配置可以修改 values.yml 进行定制。

5. 方案三：Helm 仓库部署

官方仓库默认会安装所有类型的存储后端存储类，并且包含 Retain 和 Delete 两种模式。

添加仓库：

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

安装：

helm upgrade -i <release-name> synology-csi-chart/synology-csi -n synology-csi --create-namespace

卸载：

helm delete <release-name> -n synology-csi

如果需要定制安装，可以将 Chart 下载的本地进行修改，要注意 Helm Chart 仓库和本地配置存在差别，不要使用仓库里的 values.yaml。推荐在 local.yaml 中对默认参数进行覆盖。

helm pull --untar synology-csi-chart/synology-csi
cd synology-csi && vim local.yaml

6. 验证状态

kubectl get pods -n synology-csi

通过 Helm 运行测试， 运行测试会创建 iSCSI/SMB/NFS 三种类型的 PersistentVolumeClaim 并将其挂载到 Pod 运行 fio 测试吞吐量。如果测试通过，这些 PersistentVolumeClaim 和 Pods 会自动被移除。

# 随机读写测试
helm test -n synology-csi

# 查看资源状态
kubectl describe pods -n synology-csi -l helm.sh/template=test.yaml

3. 存储类 (StorageClass) 配置详解

驱动正常运行后，需定义 StorageClass 来按需分配存储。

3.1 iSCSI 协议示例

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

3.2 SMB/CIFS 协议示例

使用 SMB 前必须先创建包含账号信息的 Secret：

apiVersion: v1
kind: Secret
metadata:
  name: cifs-csi-credentials
  namespace: default
stringData:
  username: <账号>
  password: <密码>
---
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

3.3 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

4. 参数配置指南

• 对于SSD固态，建议启用强制单元访问 (FUA) 和 SCSI 同步缓存命令，可以降低因意外关机而导致的存储损坏风险。也可以在创建后在 SAN Manager 中更改。

5. 卸载驱动

若需移除驱动，可执行：

./scripts/uninstall.sh