longhornio/csi-attacher

CSI Attacher 技术文档

1. 镜像概述和主要用途

1.1 概述

CSI Attacher（Container Storage Interface Attacher）是容器存储接口（CSI）规范定义的核心组件之一，负责协调持久化存储卷（Volume）与容器节点（Node）之间的附加（Attach）和分离（Detach）操作。它作为CSI存储插件与容器编排平台（如Kubernetes）之间的桥梁，实现存储卷在节点上的可用性管理，是CSI存储插件正常工作的必要组件。

1.2 主要用途

• 接收容器编排平台（如Kubernetes）的存储卷附加/分离请求，转发至CSI存储插件进行处理。
• 监控CSI存储插件的状态，确保卷附加/分离操作的一致性和可靠性。
• 处理卷附加/分离过程中的重试、超时等异常场景，保障存储卷生命周期管理的稳定性。

2. 核心功能和特性

• CSI规范实现：严格遵循CSI 1.0+规范，支持AttachVolume、DetachVolume等核心CSI RPC接口。
• 卷附加/分离管理：协调存储卷与节点的绑定关系，确保卷在节点上的可访问性（如挂载块设备、配置网络存储路径等）。
• 多节点协调：支持跨节点的卷操作调度，避免同一卷被重复附加到多个节点。
• 重试与容错机制：内置操作重试逻辑（可配置初始间隔、最大间隔等参数），应对临时网络故障或插件不可用场景。
• 可观测性：提供详细日志输出（支持日志级别配置），并暴露Prometheus监控指标（如操作成功率、延迟等）。
• 灵活性：支持通过UNIX域套接字或TCP与CSI插件通信，适配不同部署模式。

3. 使用场景和适用范围

3.1 使用场景

• Kubernetes存储插件部署：作为CSI存储插件（如Ceph CSI、AWS EBS CSI、Azure Disk CSI等）的配套组件，在Kubernetes集群中实现存储卷的动态附加/分离。
• 持久化存储管理：为需要持久化数据的应用（如数据库、分布式文件系统、消息队列等）提供存储卷的节点级可用性保障。

3.2 适用范围

• 容器编排平台：主要用于Kubernetes，也可适配其他支持CSI的编排平台（如OpenShift、Cloud Foundry）。
• CSI存储插件类型：适用于所有实现CSI Attach/Detach接口的存储插件，包括块存储（如EBS、Cinder）、文件存储（如NFS、GlusterFS）、对象存储（通过文件系统网关）等。

4. 使用方法和配置说明

4.1 部署方式

CSI Attacher通常以容器化方式部署，支持独立Docker运行或在Kubernetes中通过Deployment/DaemonSet部署（推荐后者，需与CSI插件协同）。

4.1.1 Docker独立部署（测试场景）

通过docker run直接启动容器，需指定CSI插件的通信地址（通常为CSI插件暴露的UNIX域套接字或TCP地址）。

示例命令：

bash
docker run -d \
  --name csi-attacher \
  --privileged \  # 部分场景下需访问主机设备或套接字
  -v /var/lib/csi/sockets/pluginproxy/csi-plugin.sock:/csi/csi.sock \  # 挂载CSI插件的UNIX套接字
  quay.io/k8scsi/csi-attacher:v4.0.0 \  # 镜像版本（需替换为实际版本）
  --csi-address=/csi/csi.sock \  # CSI插件的通信地址（容器内路径）
  --v=5 \  # 日志级别（1-10，5为默认）
  --timeout=30s \  # 单次CSI操作超时时间
  --retry-interval-start=1s \  # 初始重试间隔
  --retry-interval-max=30s  # 最大重试间隔

4.1.2 Kubernetes部署（生产场景）

在Kubernetes中，CSI Attacher通常以Deployment形式部署（单副本或多副本，通过Leader选举确保唯一性），并通过CSIDriver资源与CSI插件关联。

Kubernetes Deployment示例（精简版）：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: csi-attacher
  namespace: kube-system
spec:
  replicas: 1  # 单副本（Leader选举模式下可多副本）
  selector:
    matchLabels:
      app: csi-attacher
  template:
    metadata:
      labels:
        app: csi-attacher
    spec:
      containers:
      - name: csi-attacher
        image: quay.io/k8scsi/csi-attacher:v4.0.0
        args:
          - --csi-address=/csi/csi.sock  # CSI插件的套接字路径（需通过Volume挂载）
          - --v=5
          - --timeout=30s
          - --retry-interval-start=1s
          - --retry-interval-max=30s
        volumeMounts:
        - name: csi-plugin-socket
          mountPath: /csi  # 挂载CSI插件的UNIX套接字目录
      volumes:
      - name: csi-plugin-socket
        hostPath:
          path: /var/lib/csi/sockets/pluginproxy/csi-plugin.sock  # 主机上CSI插件的套接字路径
          type: Socket

4.2 核心配置参数

CSI Attacher通过命令行参数或环境变量配置，常用参数如下：

4.3 环境变量

部分参数可通过环境变量配置（优先级低于命令行参数）：

• CSI_ATTACHER_TIMEOUT：等价于--timeout。
• CSI_ATTACHER_RETRY_INTERVAL_START：等价于--retry-interval-start。
• CSI_PROBE_TIMEOUT：CSI插件健康检查超时时间（默认5s）。

5. 注意事项

• 依赖CSI插件：CSI Attacher需与CSI插件（如csi-driver-registrar、CSI存储插件本身）协同工作，确保CSI插件已正常部署且通信地址可访问。
• 权限要求：需挂载CSI插件的UNIX套接字（通常位于主机路径），容器需具备主机路径挂载权限（如--privileged或CAP_SYS_ADMIN capability）。
• 版本兼容性：CSI Attacher版本需与CSI插件支持的CSI规范版本匹配（如CSI 1.6+需使用csi-attacher v4.0+）。
• 监控与日志：通过--metrics-addr暴露的Prometheus指标可集成监控系统（如Grafana），日志可通过标准输出采集（如ELK stack）。