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 命令）

bash
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 片段如下：

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 主要通过命令行参数配置，以下为常用参数说明：

参数名	类型	描述	是否必填	默认值
`--csi-address`	string	CSI 驱动的 UNIX 域套接字路径（如 `/var/run/csi/csi.sock`）	是	-
`--v`	int	日志级别（0-5，5 为最详细）	否	0
`--timeout`	string	与 CSI 驱动通信的超时时间（如 `30s`）	否	15s
`--leader-election`	bool	启用 leader 选举（多副本部署时防止重复操作）	否	false
`--leader-election-namespace`	string	leader 选举的命名空间（启用选举时必填）	否	`kube-system`
`--metrics-addr`	string	metrics 指标暴露地址（如 `:8080`）	否	`:8080`

4.3 使用注意事项

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