CSI External Provisioner 镜像文档

1. 镜像概述和主要用途

1.1 概述

CSI External Provisioner（外部供应器）是 Kubernetes CSI（容器存储接口）规范的核心组件之一，作为独立运行的外部服务，负责协调 Kubernetes 控制平面与 CSI 存储驱动之间的卷供应流程。其核心逻辑是监听 Kubernetes 集群中的 PersistentVolumeClaim（PVC）对象事件，并根据 PVC 定义的存储需求，调用 CSI 驱动的卷供应接口，实现持久化卷的动态创建与删除。

1.2 主要用途

• 连接 Kubernetes 控制平面与 CSI 存储驱动，作为两者之间的通信桥梁
• 自动化处理 PVC 的生命周期事件（创建触发卷供应，删除触发卷清理）
• 确保卷供应流程符合 Kubernetes 存储类（StorageClass）定义的参数和策略
• 实现卷供应的标准化流程，兼容所有符合 CSI 规范的存储驱动

2. 核心功能和特性

2.1 核心功能

• PVC 事件监听：持续监控 Kubernetes API Server 中的 PVC 对象，捕获创建、删除等事件
• 卷供应触发：当检测到新 PVC 时，根据关联的 StorageClass 参数，调用 CSI 驱动的 CreateVolume 接口创建卷
• 卷清理触发：当检测到 PVC 被删除且关联的 PV 回收策略为删除时，调用 CSI 驱动的 DeleteVolume 接口清理卷
• 状态同步：将卷供应结果（成功/失败）同步至 Kubernetes PV/PVC 对象状态

2.2 关键特性

• CSI 规范兼容：严格遵循 CSI 1.0+ 规范，支持所有符合 CSI 标准的存储驱动
• 参数传递：支持将 StorageClass 和 PVC 中的 parameters 字段传递给 CSI 驱动，实现定制化卷配置
• 重试机制：内置失败重试逻辑，处理临时网络故障或驱动不可用场景
• 日志与监控：提供详细的操作日志（支持日志级别调整），并暴露 Prometheus 监控指标

3. 使用场景和适用范围

3.1 典型使用场景

• 动态卷供应：在 Kubernetes 集群中通过 PVC 动态创建持久化卷（如 AWS EBS、GCP PD、Ceph RBD 等）
• 存储自动化：替代手动创建 PV 的传统方式，实现卷生命周期的全自动化管理
• 多存储集成：在同一集群中集成多种存储后端（通过不同 StorageClass 关联不同 CSI 驱动）

3.2 适用范围

• 环境要求：Kubernetes 集群（版本 ≥ 1.13，CSI 规范稳定版）
• 驱动兼容性：需配合 CSI 存储驱动使用（如 Ceph CSI、AWS EBS CSI、Azure Disk CSI 等）
• 部署模式：仅运行于 Kubernetes 集群内部（作为 DaemonSet 或 Deployment），不建议单机 Docker 环境使用

4. 使用方法和配置说明

4.1 部署方式概述

External Provisioner 通常作为 Kubernetes 部署（Deployment）运行，与 CSI 驱动的 sidecar 容器共同部署，通过 Unix Domain Socket 与 CSI 驱动通信。生产环境中不建议直接使用 Docker 命令运行（需依赖 Kubernetes API 和集群内网络），以下提供测试环境的 Docker 运行示例及生产环境的 Kubernetes 部署示例。

4.2 Docker 部署示例（测试环境）

4.2.1 前置条件

• 本地运行 Kubernetes 集群（如 Minikube、Kind），且已部署 CSI 驱动（如 hostpath.csi.k8s.io）
• 已获取集群管理员权限的 kubeconfig 文件

4.2.2 docker run 命令示例

docker run -d \
  --name csi-provisioner \
  --network=host \  # 测试环境简化网络配置，生产环境需使用 Pod 网络
  -v /var/lib/kubelet/plugins/hostpath.csi.k8s.io/csi.sock:/csi/csi.sock \  # 挂载 CSI 驱动 socket
  -v ~/.kube/config:/kubeconfig \  # 挂载本地 kubeconfig（测试用）
  quay.io/k8scsi/csi-provisioner:v3.5.0 \  # 镜像版本（需与 CSI 驱动兼容）
  --provisioner=hostpath.csi.k8s.io \  # CSI 驱动的供应器名称（需与 StorageClass 匹配）
  --csi-address=/csi/csi.sock \  # CSI 驱动 socket 路径
  --kubeconfig=/kubeconfig \  # 测试环境连接 Kubernetes API 的配置文件
  --v=5  # 日志级别（5 为调试级别，生产环境建议 2-3）

4.3 Kubernetes 部署示例（生产环境）

4.3.1 Deployment 配置示例（以 HostPath CSI 驱动为例）

apiVersion: apps/v1
kind: Deployment
metadata:
  name: csi-provisioner-hostpath
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: csi-provisioner-hostpath
  template:
    metadata:
      labels:
        app: csi-provisioner-hostpath
    spec:
      serviceAccountName: csi-provisioner  # 需绑定集群管理员权限的 SA
      containers:
        - name: csi-provisioner
          image: quay.io/k8scsi/csi-provisioner:v3.5.0
          args:
            - "--provisioner=hostpath.csi.k8s.io"  # CSI 驱动供应器名称
            - "--csi-address=$(ADDRESS)"
            - "--timeout=30s"  # 操作超时时间
            - "--retry-interval-start=500ms"  # 初始重试间隔
            - "--v=2"  # 日志级别
          env:
            - name: ADDRESS
              value: /csi/csi.sock  # CSI 驱动 socket 路径
          volumeMounts:
            - name: socket-dir
              mountPath: /csi
      volumes:
        - name: socket-dir
          hostPath:
            path: /var/lib/kubelet/plugins/hostpath.csi.k8s.io
            type: DirectoryOrCreate

5. 配置参数和环境变量

5.1 核心命令行参数

5.2 环境变量（辅助配置）

6. 注意事项

• 版本兼容性：需确保 External Provisioner 版本与 CSI 驱动版本兼容（参考驱动文档），例如 CSI 1.5 驱动需搭配 v3.x 系列 Provisioner
• 权限配置：运行 Provisioner 的 ServiceAccount 需绑定 ClusterRole，包含对 PVC、PV、StorageClass 等资源的操作权限
• Socket 挂载：必须与 CSI 驱动共享同一 Unix Domain Socket 文件（通常通过 emptyDir 或 hostPath 卷挂载）
• 存储类配置：PVC 必须关联存在的 StorageClass，且 StorageClass 的 provisioner 字段需与 --provisioner 参数一致