csi-resizer 容器镜像文档

一、镜像概述

1.1 镜像说明

csi-resizer 容器镜像是 Quay 仓库中 csi-resizer 官方容器的镜像副本。该镜像包含 CSI（Container Storage Interface）规范中的 csi-resizer 组件，作为 CSI Sidecar 容器，用于与 CSI 存储驱动协同工作，实现持久卷（Persistent Volume, PV）的动态大小调整功能。

1.2 主要用途

• 作为 Kubernetes 集群中 CSI 存储插件的辅助组件，支持通过 PVC（Persistent Volume Claim）动态调整 PV 大小。
• 协调 CSI 驱动完成卷大小调整的生命周期管理，包括请求验证、调整操作执行及状态更新。

二、核心功能和特性

2.1 核心功能

• 动态卷大小调整：支持通过 Kubernetes API 触发 PVC 大小调整请求，并将请求转发至 CSI 驱动执行实际存储容量调整。
• CSI 驱动协同：与遵循 CSI 规范的存储驱动（需实现 ControllerExpandVolume 或 NodeExpandVolume 接口）配合，完成卷扩展操作。
• 生命周期管理：监控 PVC 大小调整状态，处理调整成功/失败的后续逻辑（如更新 PV 容量信息、标记 PVC 状态）。

2.2 关键特性

• 规范兼容性：完全遵循 CSI v1.0+ 规范，支持与符合 CSI 标准的各类存储驱动集成（如 Ceph RBD、AWS EBS、GCE PD 等）。
• 可配置性：通过命令行参数灵活配置日志级别、超时时间、CSI 驱动通信地址等核心参数。
• 轻量级设计：容器体积小，资源占用低，适合在 Kubernetes 集群中作为 Sidecar 容器与 CSI 驱动部署。

三、使用场景和适用范围

3.1 典型使用场景

• 动态存储扩展：Kubernetes 集群中，当应用需要更多存储容量时，通过修改 PVC 的 spec.resources.requests.storage 字段触发自动扩容。
• CSI 存储插件部署：作为 CSI 驱动部署架构的必要组件（通常与 csi-provisioner、csi-attacher 等 Sidecar 容器配合），提供完整的卷管理能力。
• 自动化容量管理：替代手动调整存储卷大小的操作，实现存储资源的按需动态分配，提升集群存储利用率。

3.2 适用范围

• 环境要求：运行于 Kubernetes 1.16+ 集群（需启用 ExpandCSIVolumes 特性门控，1.24+ 默认为稳定版）。
• 驱动兼容性：需配合支持卷扩展功能的 CSI 驱动（驱动需实现 ControllerExpandVolume 接口，若支持在线扩展还需实现 NodeExpandVolume 接口）。
• 存储类型：适用于块存储（如 EBS、RBD）或文件存储（如 NFS、CephFS）等支持容量扩展的存储后端。

四、使用方法和配置说明

4.1 部署方式

csi-resizer 作为 CSI Sidecar 容器，通常与 CSI 驱动的 Controller 组件（如 Deployment）共同部署在 Kubernetes 集群中。以下提供基础部署示例（含 Docker 运行命令及 Kubernetes YAML 配置参考）。

4.1.1 Docker 运行示例

（注：实际生产环境中，csi-resizer 通常通过 Kubernetes 部署，以下为本地调试用 Docker 命令）

docker run -d \
  --name csi-resizer \
  --privileged \
  -v /var/lib/kubelet/plugins/<csi-driver-name>:/var/lib/kubelet/plugins/<csi-driver-name> \
  quay.io/k8scsi/csi-resizer:v1.8.0 \
  --csi-address=/var/lib/kubelet/plugins/<csi-driver-name>/csi.sock \
  --v=5 \
  --timeout=30s

参数说明：

• -v：挂载 CSI 驱动的 UNIX 域套接字（socket）路径，确保 csi-resizer 能与 CSI 驱动通信。
• --csi-address：CSI 驱动的 socket 文件路径（必填，需与驱动实际路径一致）。
• --v：日志级别（数值越大日志越详细，默认 0）。
• --timeout：与 CSI 驱动通信的超时时间（默认 15s）。

4.1.2 Kubernetes 部署示例（Controller 模式）

在 Kubernetes 中，csi-resizer 通常作为 Sidecar 容器嵌入 CSI 驱动的 Controller Deployment 中，示例 YAML 片段如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: csi-driver-controller
  namespace: kube-system
spec:
  replicas: 1
  template:
    spec:
      containers:
        # ... 其他容器（如 CSI 驱动自身、csi-provisioner 等）
        - name: csi-resizer
          image: quay.io/k8scsi/csi-resizer:v1.8.0
          args:
            - "--csi-address=$(ADDRESS)"
            - "--v=5"
            - "--timeout=30s"
            - "--leader-election"  # 启用 leader 选举（多副本部署时必填）
          env:
            - name: ADDRESS
              value: /var/lib/kubelet/plugins/<csi-driver-name>/csi.sock
          volumeMounts:
            - name: socket-dir
              mountPath: /var/lib/kubelet/plugins/<csi-driver-name>
      volumes:
        - name: socket-dir
          hostPath:
            path: /var/lib/kubelet/plugins/<csi-driver-name>
            type: DirectoryOrCreate

4.2 核心配置参数

csi-resizer 主要通过命令行参数配置，以下为常用参数说明：

4.3 使用注意事项

1. CSI 驱动兼容性：确保所用 CSI 驱动已实现卷扩展接口（ControllerExpandVolume 和/或 NodeExpandVolume），否则 csi-resizer 无法正常工作。
2. Kubernetes 版本：1.16-1.23 版本需手动启用 ExpandCSIVolumes 特性门控；1.24+ 版本默认支持。
3. 权限配置：运行 csi-resizer 的 Pod 需具备访问 Kubernetes API（如获取/更新 PVC、PV）及 CSI 驱动 socket 文件的权限。
4. 日志调试：通过 --v=5 开启详细日志，可排查卷扩展失败原因（如驱动返回错误、权限不足等）。