MacroSAN CSI Driver 技术文档

一、镜像概述和主要用途

MacroSAN CSI Driver 是符合容器存储接口（CSI）规范的存储驱动程序，用于在 Kubernetes 集群中连接 MacroSAN 存储系统，为容器化应用提供持久化存储服务。该驱动实现了 CSI 规范定义的卷创建、删除、挂载、卸载等核心操作，支持与 MacroSAN 存储系统的深度集成，使 Kubernetes 集群能够动态管理 MacroSAN 存储资源，满足容器应用对持久化存储的需求。

二、核心功能和特性

2.1 核心功能

• 动态卷配置：支持通过 Kubernetes StorageClass 动态创建、删除 MacroSAN 存储卷（LUN）。
• 卷生命周期管理：提供卷挂载、卸载、扩容（在线/离线）、快照、克隆等完整生命周期管理能力。
• 多访问模式支持：支持单节点读写（RWO）、多节点读写（RWX）、单节点只读（ROX）等卷访问模式。
• 存储资源隔离：支持基于 MacroSAN 存储池（Storage Pool）的资源隔离，可指定卷创建到特定存储池。

2.2 关键特性

• 兼容性：符合 CSI 1.3+ 规范，兼容 Kubernetes 1.18+ 版本。
• QoS 策略支持：可通过 StorageClass 参数配置卷的 IOPS、带宽等 QoS 限制，保障应用存储性能。
• 高可用性：支持 MacroSAN 存储系统的冗余架构，卷数据高可用存储。
• 简化管理：通过 Kubernetes 原生存储接口（PVC、StorageClass）统一管理存储资源，无需手动操作存储系统。

三、使用场景和适用范围

3.1 典型使用场景

• Kubernetes 持久化存储：为集群内 StatefulSet 应用（如数据库、消息队列、分布式文件系统）提供持久化存储。
• 高性能存储需求：适用于对存储 IOPS、吞吐量有较高要求的应用（如 MySQL、PostgreSQL、Elasticsearch）。
• 数据高可用场景：通过 MacroSAN 存储系统的冗余机制，保障容器应用数据的高可用性和可靠性。
• 动态资源调整：支持根据应用需求动态扩容卷容量或调整 QoS 策略，适应业务增长。

3.2 适用范围

• Kubernetes 版本：1.18+（需支持 CSI 1.3+ 规范）。
• MacroSAN 存储系统：支持 REST API 接口的 MacroSAN 存储阵列（具体版本需参考厂商兼容性列表）。
• 操作系统：Linux 内核 4.19+ 的节点（需支持 iscsiadm 或 multipathd 工具，用于卷挂载）。

四、使用方法和配置说明

4.1 部署前提

• Kubernetes 集群：已部署 Kubernetes 1.18+ 集群，且集群节点网络可访问 MacroSAN 存储系统管理接口和数据接口。
• MacroSAN 存储系统：
  • 已创建存储池（Storage Pool），并确保存储池有足够容量。
  • 已配置用于 CSI 驱动认证的用户（需具备卷管理权限）。
  • 已开启 iSCSI 或 FC 协议（根据存储网络类型选择，推荐 iSCSI 用于通用场景）。
• 节点依赖：Kubernetes 节点需安装 iscsi-initiator-utils（iSCSI 客户端）和 multipath-tools（多路径工具）。

4.2 部署步骤

4.2.1 部署 CSI Driver

推荐通过 Helm Chart 或 Kubernetes YAML 清单部署 MacroSAN CSI Driver。以下为 YAML 部署示例：

1. 下载部署清单
   从 MacroSAN ***获取驱动部署文件（如 macro-san-csi-driver.yaml），包含 Controller 和 Node 组件。

2. 配置存储系统连接信息
   在部署清单中修改或通过 Secret 配置 MacroSAN 存储系统地址、用户名、密码：

   yaml
   # 创建认证 Secret（示例）
   apiVersion: v1
   kind: Secret
   metadata:
     name: macro-san-secret
     namespace: kube-system
   type: Opaque
   data:
     username: <base64-encoded-username>  # 用户名 base64 编码
     password: <base64-encoded-password>  # 密码 base64 编码
     management-endpoint: <base64-encoded-ip:port>  # 存储系统管理接口地址（如 "192.168.1.100:8443"）
   

3. 部署驱动

   bash
   kubectl apply -f macro-san-csi-driver.yaml
   

4. 验证部署
   检查 Controller 和 Node 组件是否运行正常：

   bash
   kubectl get pods -n kube-system | grep macro-san-csi
   

   预期输出：Controller 组件（1 个副本）和 Node 组件（每个节点 1 个副本）均为 Running 状态。

4.2.2 创建 StorageClass

通过 StorageClass 定义存储资源的属性（如存储池、访问模式、QoS 等），示例如下：

yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: macro-san-sc
provisioner: csi.macrosan.com  # CSI Driver  provisioner 名称（需与驱动配置一致）
parameters:
  storagePool: "pool-1"  # MacroSAN 存储池名称
  protocol: "iscsi"      # 存储协议（iscsi/fc）
  iopsLimit: "1000"      # 卷 IOPS 限制（可选，0 为无限制）
  bandwidthLimit: "100"  # 卷带宽限制（MB/s，可选，0 为无限制）
reclaimPolicy: Delete    # 卷回收策略（Delete/Retain）
allowVolumeExpansion: true  # 允许卷扩容
mountOptions:
  - _netdev  # 确保网络就绪后再挂载

4.2.3 创建 PVC 和使用存储

1. 创建 PVC
   通过 PVC 请求存储资源，引用上述 StorageClass：

   yaml
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: macro-san-pvc
   spec:
     accessModes:
       - ReadWriteOnce  # 单节点读写（支持 ReadWriteMany 需存储系统配置）
     resources:
       requests:
         storage: 10Gi  # 请求 10GiB 存储
     storageClassName: macro-san-sc  # 引用上述 StorageClass
   

2. 创建 Pod 使用 PVC

   yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: macro-san-test-pod
   spec:
     containers:
     - name: test-container
       image: nginx:latest
       volumeMounts:
       - name: macro-san-volume
         mountPath: /data
     volumes:
     - name: macro-san-volume
       persistentVolumeClaim:
         claimName: macro-san-pvc  # 引用上述 PVC
   

4.3 核心配置参数

4.3.1 StorageClass 参数

4.3.2 驱动部署环境变量

在 CSI Controller/Node 组件的 Deployment/DaemonSet 中配置，用于驱动与存储系统交互：

五、部署验证与故障排查

5.1 验证存储可用性

1. 检查 PVC 状态：kubectl get pvc macro-san-pvc，状态应为 Bound。
2. 检查 Pod 状态：kubectl get pod macro-san-test-pod，状态应为 Running。
3. 进入 Pod 验证挂载：kubectl exec -it macro-san-test-pod -- df -h /data，确认存储卷已挂载。

5.2 常见故障排查

• PVC Pending：检查 StorageClass 是否存在、storagePool 参数是否正确，或存储池容量是否充足。
• 卷挂载失败：检查节点 iscsi-initiator-utils 是否安装，存储系统 iSCSI 服务是否正常，节点与存储系统数据网络是否连通。
• 驱动日志：查看 CSI Controller/Node Pod 日志：kubectl logs -n kube-system <macro-san-csi-controller-pod> -c csi-provisioner。

六、版本兼容性

注：具体版本兼容性请参考 MacroSAN ***文档。