longhornio/livenessprobe

CSI Livenessprobe 镜像文档

一、镜像概述和主要用途

CSI Livenessprobe 是遵循容器存储接口（CSI）规范的健康检查工具，主要用于监控 CSI 驱动的运行状态。作为 CSI 架构中的辅助组件，它通过定期探测 CSI 驱动的 gRPC 服务端点，验证驱动是否正常响应请求，确保存储服务的可用性。通常作为 Sidecar 容器部署在 CSI 驱动的 Pod 中，配合 Kubernetes 的 liveness/readiness 探针机制，实现故障自动恢复。

二、核心功能和特性

核心功能

• CSI 驱动健康探测：通过 gRPC 协议与 CSI 驱动通信，检查驱动的基础服务（如 Controller/Node 服务）是否正常。
• 状态上报：将探测结果以退出码形式返回（0 表示健康，非 0 表示异常），供容器编排平台（如 Kubernetes）判断服务状态。

关键特性

• 可配置探测参数：支持自定义探测间隔、超时时间、重试次数等。
• 多端点支持：兼容 CSI 驱动的 UNIX 域套接字（unix://）和 TCP 端点（tcp://）。
• 轻量级设计：镜像体积小，资源占用低，适合作为 Sidecar 长期运行。
• 符合 CSI 规范：严格遵循 CSI 1.0+ 标准，兼容主流 CSI 驱动实现。

三、使用场景和适用范围

典型场景

1. Kubernetes CSI 驱动部署：作为 Sidecar 容器与 CSI 驱动（如 csi-provisioner、csi-node-driver-registrar 等）共同运行，提供健康状态监控。
2. 存储服务高可用保障：当 CSI 驱动异常时，通过 Kubernetes 的 liveness 探针触发 Pod 重启，实现自动恢复。
3. 自定义健康检查策略：通过调整探测参数（如间隔、超时），适配不同性能需求的 CSI 驱动。

适用范围

• 所有遵循 CSI 1.0+ 规范的存储驱动（如 Ceph CSI、AWS EBS CSI、NFS CSI 等）。
• 容器编排平台：Kubernetes、OpenShift 等支持 CSI 的容器平台。

四、使用方法和配置说明

4.1 基础使用（Docker Run）

通过 docker run 直接运行容器，需挂载 CSI 驱动的 gRPC 端点（通常为 UNIX 域套接字文件），并指定探测参数：

bash
docker run -d \
  --name csi-livenessprobe \
  -v /path/to/csi/driver/socket:/csi/csi.sock \  # 挂载 CSI 驱动的套接字文件
  quay.io/k8scsi/livenessprobe:v2.10.0 \          # 示例镜像（以实际镜像为准）
  --endpoint=unix:///csi/csi.sock \               # CSI 驱动的 gRPC 端点
  --interval=10s \                                # 探测间隔（默认 10s）
  --timeout=3s \                                  # 单次探测超时时间（默认 3s）
  --probe-path=/csi.v1.Identity/Probe             # 探测的 gRPC 方法路径（默认 /csi.v1.Identity/Probe）

4.2 Kubernetes 部署示例（Sidecar 容器）

在 Kubernetes 中，通常将 CSI Livenessprobe 作为 Sidecar 容器嵌入 CSI 驱动的 Pod 配置（如 DaemonSet 或 Deployment）：

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: csi-node-driver
  namespace: kube-system
spec:
  template:
    spec:
      containers:
        # CSI 驱动主容器
        - name: csi-driver
          image: <csi-driver-image>
          volumeMounts:
            - name: csi-socket-dir
              mountPath: /csi
        # CSI Livenessprobe Sidecar 容器
        - name: liveness-probe
          image: quay.io/k8scsi/livenessprobe:v2.10.0
          args:
            - --endpoint=unix:///csi/csi.sock
            - --interval=15s
            - --timeout=5s
          volumeMounts:
            - name: csi-socket-dir
              mountPath: /csi
      volumes:
        - name: csi-socket-dir
          hostPath:
            path: /var/lib/csi/sockets/pluginproxy/
            type: DirectoryOrCreate

4.3 Docker Compose 配置（本地测试用）

适用于本地调试 CSI 驱动时，通过 Docker Compose 启动驱动与 Livenessprobe 容器：

yaml
version: "3"
services:
  csi-driver:
    image: <local-csi-driver-image>
    volumes:
      - csi-socket:/csi
    command: ["--endpoint=unix:///csi/csi.sock"]

  livenessprobe:
    image: quay.io/k8scsi/livenessprobe:v2.10.0
    depends_on:
      - csi-driver
    volumes:
      - csi-socket:/csi
    command:
      - --endpoint=unix:///csi/csi.sock
      - --interval=5s
      - --timeout=2s

volumes:
  csi-socket:

五、配置参数说明

5.1 命令行参数

5.2 环境变量（可选，用于替代命令行参数）

六、注意事项

1. 端点一致性：--endpoint 需与 CSI 驱动实际监听的端点完全一致（如套接字路径或 TCP 地址），否则探测会失败。
2. 资源限制：建议为容器设置资源限制（如 resources.limits.cpu=100m、memory=128Mi），避免资源占用过高。
3. 版本兼容性：需使用与 CSI 驱动版本匹配的 Livenessprobe 镜像（如 CSI 1.8+ 建议使用 v2.10+ 版本）。
4. Kubernetes 探针联动：在 Kubernetes 中，需同时配置容器的 livenessProbe（基于 Livenessprobe 容器的退出码），示例：

   yaml
   livenessProbe:
     exec:
       command: ["cat", "/tmp/health"]  # 或直接依赖容器退出码（若 Livenessprobe 进程退出则触发重启）
     initialDelaySeconds: 10
     periodSeconds: 5