k8s.gcr.io/sig-storage/csi-attacher 镜像文档

一、镜像概述和主要用途

k8s.gcr.io/sig-storage/csi-attacher 是 Kubernetes SIG Storage 项目维护的 Docker 镜像，包含 CSI（容器存储接口）规范中的 卷附加器（Attacher） 组件。该组件作为 CSI 驱动的辅助容器（Sidecar Container），负责实现 CSI 规范中的卷附加（Attach）与分离（Detach）操作，是 Kubernetes 集群中部署 CSI 存储驱动时的核心辅助组件之一。

二、核心功能和特性

2.1 核心功能

• 实现 CSI 规范定义的 ControllerPublishVolume（Attach）和 ControllerUnpublishVolume（Detach）操作，将存储卷附加到节点或从节点分离。
• 监听 Kubernetes API 中的 VolumeAttachment 对象，根据对象状态触发 CSI 驱动的 Attach/Detach 动作。
• 维护卷附加状态与 Kubernetes 集群状态的一致性，处理重试和失败恢复。

2.2 主要特性

• CSI 规范兼容：支持 CSI 1.0+ 版本规范，兼容所有遵循 CSI 标准的存储驱动。
• Kubernetes 集成：通过 Kubernetes API 监听和更新 VolumeAttachment、Node 等资源，实现与集群控制平面的联动。
• 高可用性：支持 Leader Election 机制，可部署多实例实现高可用（仅 Leader 实例执行实际操作）。
• 可配置化：支持自定义日志级别、重试间隔、超时时间等参数，适配不同存储驱动的特性。
• 轻量级设计：作为 Sidecar 容器运行，资源占用低，仅依赖 CSI 驱动的 Unix Domain Socket 通信。

三、使用场景和适用范围

3.1 典型使用场景

• Kubernetes CSI 驱动部署：在 Kubernetes 集群中部署任何遵循 CSI 规范的存储驱动时，需配合 csi-attacher 实现卷的节点附加/分离逻辑。例如：
  • AWS EBS CSI 驱动
  • GCE PD CSI 驱动
  • Ceph RBD CSI 驱动
  • Azure Disk CSI 驱动
• 存储卷生命周期管理：作为 CSI 驱动的控制平面组件，与 csi-provisioner（卷供应）、csi-snapshotter（卷快照）等组件协同，完成存储卷从创建到挂载的全流程。

3.2 适用范围

• 所有基于 Kubernetes 部署的 CSI 存储驱动。
• 需满足 Kubernetes 版本 ≥ v1.13（CSI 1.0 规范最低要求）。
• 需配合 CSI 驱动的 Controller 服务（通常通过 Unix Domain Socket 与 csi-attacher 通信）。

四、使用方法和配置说明

4.1 部署方式

csi-attacher 通常作为 Deployment 部署在 Kubernetes 集群中（控制平面组件，非节点级），与 CSI 驱动的 Controller 容器共享同一 Pod，通过挂载 CSI 驱动的 Unix Domain Socket 实现通信。

4.2 核心配置参数

csi-attacher 通过命令行参数配置，常用参数如下：

4.3 Kubernetes 部署示例（Deployment 清单）

以下是部署 csi-attacher 作为 Sidecar 的示例 YAML（以 generic CSI 驱动为例）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: csi-attacher
  namespace: kube-system
spec:
  replicas: 2  # 多实例确保高可用（配合 leader election）
  selector:
    matchLabels:
      app: csi-attacher
  template:
    metadata:
      labels:
        app: csi-attacher
    spec:
      serviceAccountName: csi-attacher-sa  # 需绑定 RBAC 权限（见下方）
      containers:
        - name: csi-attacher
          image: k8s.gcr.io/sig-storage/csi-attacher:v4.0.0  # 替换为实际版本
          args:
            - "--v=5"
            - "--csi-address=/csi/csi.sock"  # 对应 CSI 驱动的 socket 路径
            - "--leader-election=true"
            - "--leader-election-namespace=kube-system"
            - "--retry-interval-start=1"
            - "--retry-interval-max=30"
          volumeMounts:
            - name: csi-socket-dir
              mountPath: /csi  # 挂载 CSI 驱动的 socket 目录
        # 此处省略 CSI 驱动的 Controller 容器配置（需与 csi-attacher 共享 csi-socket-dir 卷）
      volumes:
        - name: csi-socket-dir
          emptyDir: {}  # 或 hostPath（若 CSI 驱动 socket 位于节点本地）

4.4 RBAC 权限配置

csi-attacher 需要访问 Kubernetes API 操作 VolumeAttachment 等资源，需配置 RBAC 权限（示例）：

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", "delete"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["volumeattachments/status"]
    verbs: ["update"]
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: csi-attacher-binding
subjects:
  - kind: ServiceAccount
    name: csi-attacher-sa
    namespace: kube-system
roleRef:
  kind: ClusterRole
  name: csi-attacher-role
  apiGroup: rbac.authorization.k8s.io

4.5 Docker 运行示例（仅作演示，实际推荐 Kubernetes 部署）

# 需提前准备 CSI 驱动的 socket 文件（如 /host/var/lib/csi/sock/csi.sock）
docker run -d \
  --name csi-attacher \
  -v /host/var/lib/csi/sock:/csi \  # 挂载 CSI 驱动的 socket 目录
  k8s.gcr.io/sig-storage/csi-attacher:v4.0.0 \
  --v=5 \
  --csi-address=/csi/csi.sock \
  --leader-election=false  # 单实例运行时禁用 leader election

五、注意事项

1. 权限依赖：需确保 csi-attacher 的服务账户拥有访问 VolumeAttachment、Node 资源的权限，否则会导致操作失败。
2. CSI 驱动兼容性：需与 CSI 驱动的版本匹配（例如 CSI 1.5 驱动需使用支持 CSI 1.5 的 csi-attacher 版本）。
3. Socket 通信：--csi-address 必须指向 CSI 驱动 Controller 暴露的 Unix Domain Socket，且路径需通过卷挂载共享到 csi-attacher 容器。
4. 高可用配置：生产环境建议部署 2+ 实例，并启用 --leader-election，避免单点故障。