4. Identity Service 详解：GetPluginInfo、GetPluginCapabilities、Probe 三个 RPC 的实现规范与适配要点

Identity Service 是 CSI 规范中所有存储插件必须实现的三个服务之一，也是 kubelet 与 CSI 驱动建立通信后调用的第一组 RPC。该服务不涉及任何存储数据面操作，其核心职责是身份声明、能力通告与健康自检。在移植适配过程中，Identity Service 的实现质量直接决定插件能否通过 Kubernetes 的节点注册与健康检查流程。

4.1 三个 RPC 的规范总览

下表从调用时机、核心字段、返回码三个维度对比三个 RPC 的规范差异：

4.2 GetPluginInfo：身份声明与版本契约

GetPluginInfo 是 kubelet 调用 CSI 驱动的第一个 RPC，用于获取插件的唯一标识与版本信息。该 RPC 的实现必须满足以下规范约束：

• name 字段：必须为反向域名格式，且全局唯一。例如 csi.huawei.com 或 csi.ceph.com。kubelet 使用该名称在节点上注册 CSINode 对象。
• vendor_version 字段：语义化版本号，如 3.5.0。该版本号会被记录在 CSINode 对象的 annotation 中，用于运维排查。
• manifest 字段：可选键值对，用于携带驱动元数据（如驱动描述、支持协议版本等）。
• 错误处理：如果插件无法提供身份信息，应返回 gRPC Status::UNIMPLEMENTED，但实际生产环境中该 RPC 必须实现，否则 kubelet 无法完成注册。

// GetPluginInfo 响应示例（protobuf 序列化后）
{
  "name": "csi.huawei.storage",
  "vendor_version": "2.1.0",
  "manifest": {
    "url": "https://github.com/huawei/csi-driver",
    "supported_csi_spec": "1.5.0, 1.6.0"
  }
}

4.3 GetPluginCapabilities：能力通告与特性协商

GetPluginCapabilities 用于向 Kubernetes 通告插件支持的服务类型与扩展特性。CSI 规范定义了三种核心能力类型：

此外，CSI 1.5+ 规范还引入了 UNKNOWN 能力类型用于扩展。适配时建议按以下步骤实现：

1. 根据插件实际实现的服务（Controller / Node）声明对应能力。
2. 如果后端存储支持拓扑约束，添加 VOLUME_ACCESSIBILITY_CONSTRAINTS 并实现拓扑键。
3. 对于不支持的能力（如快照、扩容），不要在 capabilities 中声明，否则 Kubernetes 会尝试调用对应 RPC 并导致错误。

// GetPluginCapabilities 响应示例
{
  "capabilities": [
    {"service": {"type": "CONTROLLER_SERVICE"}},
    {"service": {"type": "NODE_SERVICE"}},
    {"volume_accessibility_constraints": {"required": true}}
  ]
}

4.4 Probe：健康自检与就绪状态

Probe RPC 是 kubelet 对 CSI 驱动进行健康检查的唯一接口。与 Kubernetes 的 livenessProbe 和 readinessProbe 不同，CSI 驱动的健康状态完全由 Probe 的返回值决定：

• ready = true：驱动正常运行，可以处理后续 RPC 请求。
• ready = false：驱动未就绪，kubelet 会停止向该驱动发送卷操作请求，并持续重试 Probe。
• 返回 NOT_READY 错误：与 ready=false 等效，但更适用于驱动初始化未完成或依赖服务不可用等场景。

// Probe 响应示例（就绪状态）
{
  "ready": true
}

// Probe 响应示例（未就绪状态）
{
  "ready": false
}
// 或返回 gRPC 错误码 NOT_READY

4.5 三个 RPC 的调用流程与适配要点

下图展示了 kubelet 在节点注册阶段调用 Identity Service 三个 RPC 的完整流程：

4.6 移植适配中的常见问题与避坑指南