CSI Metadata Retriever 镜像文档

概述

CSI Metadata Retriever是一个轻量级工具镜像，专门用于从Container Storage Interface (CSI)存储系统中检索、解析和输出元数据。该镜像设计用于与Kubernetes等容器编排平台集成，帮助用户或自动化系统获取存储卷相关的元数据信息，如卷ID、容量、访问模式、存储后端属性等，适用于存储管理、监控和自动化场景。

核心功能与特性

核心功能

• CSI元数据检索：支持通过CSI接口规范从CSI存储驱动中获取存储卷元数据
• 元数据解析与处理：对原始CSI元数据进行结构化解析，支持过滤和格式化
• 多平台集成：原生支持与Kubernetes容器编排平台集成，兼容CSI 1.0+规范

主要特性

• 轻量级设计：基于Alpine Linux构建，镜像体积小，资源占用低
• 灵活配置：支持通过环境变量或配置文件自定义元数据检索参数
• 多输出格式：支持JSON、YAML等多种元数据输出格式，便于后续处理
• 日志可观测性：提供详细日志输出，支持日志级别调整（info/warn/debug/error）

使用场景

• Kubernetes存储管理：在K8s集群中获取PVC/PV关联的CSI存储卷元数据，辅助存储资源调度
• 存储监控与审计：定期检索存储卷元数据，用于存储使用情况监控和合规审计
• 自动化运维：作为存储管理自动化脚本的组件，实现存储卷属性自动采集与上报
• CSI驱动开发调试：辅助CSI驱动开发者验证元数据返回格式和内容正确性

使用方法

基本使用（Docker Run）

通过docker run命令直接运行镜像，需指定CSI驱动端点（通常为CSI驱动的Unix域套接字路径）：

docker run --rm \
  -e CSI_ENDPOINT=unix:///csi/csi.sock \
  -v /path/to/csi/socket:/csi/csi.sock:ro \
  csi-metadata-retriever:latest

参数说明

• -v /path/to/csi/socket:/csi/csi.sock:ro：挂载CSI驱动的Unix域套接字到容器内，确保容器可访问CSI驱动
• -e CSI_ENDPOINT：指定CSI驱动端点地址（必填），格式为unix://<socket-path>或tcp://<ip>:<port>

环境变量配置

Kubernetes集成示例

在Kubernetes集群中，可通过Pod部署CSI Metadata Retriever，挂载CSI驱动的Unix域套接字（通常位于节点的/var/lib/kubelet/plugins_registry/或CSI驱动指定路径）：

apiVersion: v1
kind: Pod
metadata:
  name: csi-metadata-retriever
  namespace: default
spec:
  containers:
  - name: retriever
    image: csi-metadata-retriever:latest
    env:
    - name: CSI_ENDPOINT
      value: "unix:///csi/csi.sock"  # 容器内套接字路径
    - name: OUTPUT_FORMAT
      value: "yaml"  # 指定YAML格式输出
    - name: LOG_LEVEL
      value: "debug"  # 开启调试日志
    volumeMounts:
    - name: csi-socket
      mountPath: /csi/csi.sock
      readOnly: true
  volumes:
  - name: csi-socket
    hostPath:
      path: /var/lib/kubelet/plugins_registry/csi-driver-example.sock  # 节点上的CSI驱动套接字路径
      type: Socket
  restartPolicy: Never

运行结果示例（JSON格式）

{
  "volumes": [
    {
      "volumeId": "vol-123456",
      "capacity": "10Gi",
      "accessModes": ["ReadWriteOnce"],
      "storageClass": "csi-example-sc",
      "backend": {
        "type": "ceph",
        "pool": "rbd-pool",
        "image": "rbd-vol-123456"
      }
    }
  ]
}

注意事项

• CSI驱动兼容性：需确保目标CSI驱动支持元数据查询能力（遵循CSI规范中ControllerGetVolume或NodeGetVolume接口）
• 权限要求：容器需具备访问CSI驱动套接字的权限，Kubernetes环境中建议使用hostPath挂载时设置readOnly: true
• 网络配置：若CSI驱动端点为TCP地址，需确保容器网络可访问该TCP端点（如通过Service或直接IP访问）