CSI External-Attacher 镜像文档

镜像概述和主要用途

CSI External-Attacher（外部附加器）是 Kubernetes CSI（Container Storage Interface）规范的核心辅助组件，作为 sidecar 容器与 CSI 控制器插件协同工作。其主要用途是监听 Kubernetes VolumeAttachment API 对象的生命周期事件，通过协调调用 CSI 驱动的 ControllerPublishVolume 和 ControllerUnpublishVolume 接口，实现存储卷到节点的附加（attach）与分离（detach）操作的自动化管理。

核心功能和特性

核心功能

• VolumeAttachment 事件监听：持续监控 Kubernetes 集群中 VolumeAttachment 对象的创建、更新和删除事件。
• CSI 接口调用协调：
  • 当 VolumeAttachment 对象创建时，触发 CSI 驱动的 ControllerPublishVolume 接口，将卷附加到目标节点。
  • 当 VolumeAttachment 对象删除时，触发 CSI 驱动的 ControllerUnpublishVolume 接口，将卷从节点分离。
• 状态更新与反馈：根据 CSI 驱动的响应结果，更新 VolumeAttachment 对象的状态（如 status.attached 和 status.conditions），同步卷附加/分离操作的执行状态。

关键特性

• CSI 规范兼容：遵循 CSI 1.0+ 规范，支持所有实现 ControllerPublishVolume 和 ControllerUnpublishVolume 接口的存储驱动。
• 高可用设计：内置 leader election 机制，多副本部署时确保仅一个实例处理事件，避免重复操作和单点故障。
• 可配置化：支持自定义日志级别、超时时间、选举参数等，适配不同集群规模和存储驱动特性。
• 监控与可观测性：提供指标暴露接口（--metrics-addr）和健康检查接口（--health-addr），便于集成监控系统和问题排查。

使用场景和适用范围

典型使用场景

• CSI 驱动部署：作为 CSI 控制器插件的必要 sidecar 容器，与 CSI 控制器（如 csi-controller）共同部署，实现卷附加/分离流程的自动化协调。
• 动态卷管理：在 Pod 使用持久化卷（PVC）时，协调卷从存储系统到目标节点的附加过程，确保 Pod 启动前卷已就绪。
• 存储集群扩展：在多节点 Kubernetes 集群中，支持跨节点的卷动态迁移和负载均衡，提升存储资源利用率。

适用范围

• Kubernetes 版本：兼容 Kubernetes v1.13+（需支持 CSI 规范）。
• 部署环境：所有 Kubernetes 集群（包括自建集群、云厂商托管集群如 EKS、GKE、AKS 等）。
• 存储类型：适用于所有实现 CSI ControllerPublishVolume 和 ControllerUnpublishVolume 接口的存储驱动（如 Ceph RBD、AWS EBS、Azure Disk、GCE PD 等）。

使用方法和配置说明

部署方式

CSI External-Attacher 通常作为 sidecar 容器与 CSI 控制器插件共同部署在 Kubernetes 集群中，通过 Unix 域套接字与 CSI 控制器通信。以下为典型部署方案示例。

Kubernetes StatefulSet 部署示例（推荐）

在 CSI 控制器的 StatefulSet 配置中，将 external-attacher 作为 sidecar 容器包含：

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: csi-controller
  namespace: kube-system
spec:
  serviceName: "csi-controller"
  replicas: 2  # 多副本确保高可用
  selector:
    matchLabels:
      app: csi-controller
  template:
    metadata:
      labels:
        app: csi-controller
    spec:
      serviceAccountName: csi-controller-sa  # 需绑定 VolumeAttachment 相关 RBAC 权限
      containers:
        - name: external-attacher
          image: registry.k8s.io/sig-storage/csi-attacher:v4.4.0  # 替换为最新版本
          args:
            - --v=5  # 日志级别（0-5）
            - --csi-address=/csi/csi.sock  # 与 CSI 控制器共享的套接字路径
            - --leader-election=true  # 启用 leader election
            - --leader-election-namespace=kube-system  # 选举锁命名空间
            - --timeout=30s  # CSI RPC 超时时间
            - --metrics-addr=:8080  # 指标暴露地址
            - --health-addr=:9808  # 健康检查地址
          volumeMounts:
            - name: socket-dir
              mountPath: /csi  # 挂载共享套接字目录
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi
        - name: csi-driver  # CSI 控制器插件容器
          image: <your-csi-driver-image>  # 替换为实际 CSI 驱动镜像
          args:
            - --csi-address=/csi/csi.sock  # 与 external-attacher 共享套接字
          volumeMounts:
            - name: socket-dir
              mountPath: /csi
      volumes:
        - name: socket-dir
          emptyDir: {}  # 临时目录，用于 CSI 组件间通信

Docker 测试部署示例（非生产环境）

本地测试时，可通过 docker run 启动（需提前部署 CSI 驱动并暴露套接字）：

docker run -d \
  --name csi-attacher \
  -v /host/path/to/csi-socket:/csi/csi.sock \  # 挂载 CSI 驱动的 Unix 域套接字
  registry.k8s.io/sig-storage/csi-attacher:v4.4.0 \
  --csi-address=/csi/csi.sock \
  --v=5 \
  --leader-election=false  # 单节点测试禁用 leader election

核心配置参数

RBAC 权限要求

部署时需为 external-attacher 绑定以下 RBAC 权限（通过 ServiceAccount 实现）：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: csi-attacher-role
rules:
  - apiGroups: ["storage.k8s.io"]
    resources: ["volumeattachments"]
    verbs: ["get", "list", "watch", "create", "update", "patch"]
  - apiGroups: ["coordination.k8s.io"]
    resources: ["leases"]
    verbs: ["get", "list", "create", "update"]  # leader election 所需