CSIDriver

CSIDriver 抓取集群上部署的容器存储接口（CSI）卷驱动有关的信息。

apiVersion: storage.k8s.io/v1

import "k8s.io/api/storage/v1"

CSIDriver

CSIDriver 抓取集群上部署的容器存储接口（CSI）卷驱动有关的信息。 Kubernetes 挂接/解除挂接控制器使用此对象来决定是否需要挂接。 kubelet 使用此对象决定挂载时是否需要传递 Pod 信息。 CSIDriver 对象未划分命名空间。

  • apiVersion: storage.k8s.io/v1

  • kind: CSIDriver

CSIDriverSpec

CSIDriverSpec 是 CSIDriver 的规约。

  • attachRequired (boolean)

    attachRequired 表示这个 CSI 卷驱动需要挂接操作 （因为它实现了 CSI ControllerPublishVolume() 方法）， Kubernetes 挂接/解除挂接控制器应调用挂接卷接口， 以检查卷挂接（volumeattachment）状态并在继续挂载之前等待卷被挂接。 CSI 外部挂接器与 CSI 卷驱动配合使用，并在挂接操作完成时更新 volumeattachment 状态。 如果值指定为 false，则会跳过挂载操作。否则，将调用挂载操作。

    此字段不可变更。

  • fsGroupPolicy (string)

    fsGroupPolicy 定义底层卷是否支持在挂载之前更改卷的所有权和权限。 有关更多详细信息，请参考特定的 FSGroupPolicy 值。

    此字段在 Kubernetes 1.29 版本之前不可变更，现在可变更。

    默认为 ReadWriteOnceWithFSType，这会检查每个卷，以决定 Kubernetes 是否应修改卷的所有权和权限。 采用默认策略时，如果定义了 fstype 且卷的访问模式包含 ReadWriteOnce，将仅应用定义的 fsGroup。

  • nodeAllocatableUpdatePeriodSeconds (int64)

    nodeAllocatableUpdatePeriodSeconds 指定了 CSINode 针对此驱动对可分配容量作定期更新的时间间隔。 设置后，定期更新和由容量相关故障触发的更新均会启用。 如果没有设置，则不会发生更新（无论是定期更新还是检测到与容量相关的故障）， 并且 allocatable.count 保持为固定值。此字段允许的最小值为 10 秒。

    此特性需要启用 MutableCSINodeAllocatableCount 特性门控。

    此字段是可变更的。

  • podInfoOnMount (boolean)

    如果 podInfoOnMount 设为 true，则表示在挂载操作期间这个 CSI 卷驱动需要更多的 Pod 信息（例如 podName 和 podUID 等）。 如果设为 false，则挂载时将不传递 Pod 信息。默认为 false。

    CSI 驱动将 podInfoOnMount 指定为驱动部署的一部分。 如果为 true，Kubelet 将在 CSI NodePublishVolume() 调用中作为 VolumeContext 传递 Pod 信息。 CSI 驱动负责解析和校验作为 VolumeContext 传递进来的信息。

    如果 podInfoOnMount 设为 true，将传递以下 VolumeConext。 此列表可能变大，但将使用前缀。

    • "csi.storage.k8s.io/pod.name": pod.name
    • "csi.storage.k8s.io/pod.namespace": pod.namespace
    • "csi.storage.k8s.io/pod.uid": string(pod.UID)
    • "csi.storage.k8s.io/ephemeral": 如果此卷是 CSIVolumeSource 定义的一个临时内联卷，则为 “true”，否则为 “false”

    csi.storage.k8s.io/ephemeral 是 Kubernetes 1.16 中一个新的功能特性。 只有同时支持 Persistent 和 Ephemeral VolumeLifecycleMode 的驱动，此字段才是必需的。 其他驱动可以保持禁用 Pod 信息或忽略此字段。 由于 Kubernetes 1.15 不支持此字段，所以在这类集群上部署驱动时，只能支持一种模式。 该部署就决定了是哪种模式，例如通过驱动的命令行参数。

    此字段在 Kubernetes 1.29 版本之前不可变更，现在可变更。

  • preventPodSchedulingIfMissing (boolean)

    PreventPodSchedulingIfMissing 表示如果节点上缺少 CSI 驱动程序，CSI 驱动程序将阻止 Pod 调度。

    启用此选项将阻止调度器（或任何嵌入默认调度器的其他组件，例如 cluster-autoscaler）将 Pod 调度到未安装 CSI 驱动程序的节点。

    对于嵌入调度器并使用调度器插件运行 Pod 放置模拟的组件（例如 cluster-autoscaler）， 它们必须通过 CSINode 对象获取 CSI 驱动程序注册信息。在调度模拟期间， 除了创建 Node 对象之外，它们还必须创建模拟的 CSINode 对象。 否则，如果全局为 CSIDriver 对象启用 PreventPodSchedulingIfMissing， 则任何新创建的节点都可能由于缺少节点的 CSI 驱动程序信息而被调度器拒绝。

    这是一个 Alpha 级别特性，需要启用 VolumeLimitScaling 特性门控。默认值为 “false”。

  • requiresRepublish (boolean)

    requiresRepublish 表示 CSI 驱动想要 NodePublishVolume 被周期性地调用， 以反映已挂载卷中的任何可能的变化。 此字段默认为 false。

    注：成功完成对 NodePublishVolume 的初始调用后，对 NodePublishVolume 的后续调用只应更新卷的内容。 新的挂载点将不会被运行的容器察觉。

  • seLinuxMount (boolean)

    seLinuxMount 指定 CSI 驱动是否支持 "-o context" 挂载选项。

    当值为 “true” 时，CSI 驱动必须确保该 CSI 驱动提供的所有卷可以分别用不同的 -o context 选项进行挂载。 这对于将卷作为块设备上的文件系统或作为独立共享卷提供的存储后端来说是典型的方法。 当 Kubernetes 挂载在 Pod 中使用的已显式设置 SELinux 上下文的 ReadWriteOncePod 卷时， 将使用 -o context=xyz 挂载选项调用 NodeStage / NodePublish。 未来可能会扩展到其他的卷访问模式（AccessModes）。在任何情况下，Kubernetes 都会确保该卷仅使用同一 SELinux 上下文进行挂载。

    当值为 “false” 时，Kubernetes 不会将任何特殊的 SELinux 挂载选项传递给驱动。 这通常用于代表更大共享文件系统的子目录的卷。

    默认为 “false”。

  • serviceAccountTokenInSecrets (boolean)

    serviceAccountTokenInSecrets 是 CSI 驱动程序的一个可选参数， 用于指示服务帐户令牌应通过 NodePublishVolumeRequest 中的 secrets 字段传递， 而不是通过 volumeContext 字段传递。CSI 规约提供了一个专用的 secrets 字段来存储令牌等敏感信息，这是处理凭据的合适机制。 这解决了之前敏感令牌作为卷上下文的一部分被记录的安全问题。

    如果设置为 true，kubelet 将仅通过键为 csi.storage.k8s.io/serviceAccount.tokens 的 secrets 字段传递令牌。CSI 驱动程序必须更新为从 secrets 字段而不是 VolumeContext 读取令牌。

    如果设置为 false 或未设置，kubelet 将通过键为 csi.storage.k8s.io/serviceAccount.tokens 的 volumeContext 传递令牌（现有行为）。这保持了与现有 CSI 驱动程序的向后兼容性。

    只有在配置了 tokenRequests 时才能设置此字段。 API 服务器将拒绝未设置 tokenRequests 的 CSIDriver 规约。

    如果未设置此字段，则默认行为是在 volumeContext 字段中传递令牌。

  • storageCapacity (boolean)

    如果设为 true，则 storageCapacity 表示 CSI 卷驱动希望 Pod 调度时考虑存储容量， 驱动部署将通过创建包含容量信息的 CSIStorageCapacity 对象来报告该存储容量。

    部署驱动时可以立即启用这个检查。 这种情况下，只有此驱动部署已发布某些合适的 CSIStorageCapacity 对象， 才会继续制备新的卷，然后进行绑定。

    换言之，可以在未设置此字段或此字段为 false 的情况下部署驱动， 并且可以在发布存储容量信息后再修改此字段。

    此字段在 Kubernetes 1.22 及更早版本中不可变更，但现在可以变更。

  • tokenRequests ([]TokenRequest)

    原子性：将在合并期间被替换

    tokenRequests 表示 CSI 驱动需要供挂载卷所用的 Pod 的服务帐户令牌，进行必要的鉴权。 kubelet 将在 CSI NodePublishVolume 调用中传递 VolumeContext 中的令牌。 CSI 驱动应解析和校验以下 VolumeContext：

    "csi.storage.k8s.io/serviceAccount.tokens": {
  "<audience>": {
    "token": <令牌>,
    "expirationTimestamp": <格式为 RFC3339 的过期时间戳>,
  },
  ...
}

    注：每个 tokenRequest 中的受众应该不同，且最多有一个令牌是空字符串。 要在令牌过期后接收一个新的令牌，requiresRepublish 可用于周期性地触发 NodePublishVolume。

    tokenRequest 包含一个服务帐户令牌的参数。

    • tokenRequests.audience (string)，必需

      audience 是 TokenRequestSpec 中令牌的目标受众。 它默认为 kube apiserver 的受众。

    • tokenRequests.expirationSeconds (int64)

      expirationSeconds 是 tokenRequestSpec 中令牌的有效期。 它具有与 tokenRequestSpec 中 expirationSeconds 相同的默认值。

  • volumeLifecycleModes ([]string)

    集合：唯一值将在合并期间被保留

    volumeLifecycleModes 定义这个 CSI 卷驱动支持哪种类别的卷。 如果列表为空，则默认值为 Persistent，这是 CSI 规范定义的用法， 并通过常用的 PV/PVC 机制在 Kubernetes 中实现。

    另一种模式是 Ephemeral。 在这种模式下，在 Pod 规约中用 CSIVolumeSource 以内联方式定义卷，其生命周期与该 Pod 的生命周期相关联。 驱动必须感知到这一点，因为只有针对这种卷才会接收到 NodePublishVolume 调用。

    有关实现此模式的更多信息，请参阅 https://kubernetes-csi.github.io/docs/ephemeral-local-volumes.html。 驱动可以支持其中一种或多种模式，将来可能会添加更多模式。

    此字段处于 Beta 阶段。此字段不可变更。

CSIDriverList

CSIDriverList 是 CSIDriver 对象的集合。

  • apiVersion: storage.k8s.io/v1

  • kind: CSIDriverList

操作

get 读取指定的 CSIDriver

HTTP 请求

GET /apis/storage.k8s.io/v1/csidrivers/{name}

参数

  • name (路径参数): string，必需

    CSIDriver 的名称。

  • pretty (查询参数): string

    pretty

响应

200 (CSIDriver): OK

401: Unauthorized

list 列出或观测类别为 CSIDriver 的对象

HTTP 请求

GET /apis/storage.k8s.io/v1/csidrivers

参数

响应

200 (CSIDriverList): OK

401: Unauthorized

create 创建 CSIDriver

HTTP 请求

POST /apis/storage.k8s.io/v1/csidrivers

参数

响应

200 (CSIDriver): OK

201 (CSIDriver): Created

202 (CSIDriver): Accepted

401: Unauthorized

update 替换指定的 CSIDriver

HTTP 请求

PUT /apis/storage.k8s.io/v1/csidrivers/{name}

参数

  • name (路径参数): string，必需

    CSIDriver 的名称。

  • body: CSIDriver，必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • pretty (查询参数): string

    pretty

响应

200 (CSIDriver): OK

201 (CSIDriver): Created

401: Unauthorized

patch 部分更新指定的 CSIDriver

HTTP 请求

PATCH /apis/storage.k8s.io/v1/csidrivers/{name}

参数

  • name (路径参数): string，必需

    CSIDriver 的名称。

  • body: Patch，必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • force (查询参数): boolean

    force

  • pretty (查询参数): string

    pretty

响应

200 (CSIDriver): OK

201 (CSIDriver): Created

401: Unauthorized

delete 删除 CSIDriver

HTTP 请求

DELETE /apis/storage.k8s.io/v1/csidrivers/{name}

参数

响应

200 (CSIDriver): OK

202 (CSIDriver): Accepted

401: Unauthorized

deletecollection 删除 CSIDriver 的集合

HTTP 请求

DELETE /apis/storage.k8s.io/v1/csidrivers

参数

响应

200 (Status): OK

401: Unauthorized

最后修改 May 09, 2026 at 11:26 AM PST: [zh-cn]sync csi-driver-v1 (a24bb6cb71)