--- api_metadata: apiVersion: "storage.k8s.io/v1" import: "k8s.io/api/storage/v1" kind: "CSIDriver" content_type: "api_reference" description: "CSIDriver 抓取集群上部署的容器存储接口（CSI）卷驱动有关的信息。" title: "CSIDriver" weight: 3 --- `apiVersion: storage.k8s.io/v1` `import "k8s.io/api/storage/v1"` ## CSIDriver {#CSIDriver} CSIDriver 抓取集群上部署的容器存储接口（CSI）卷驱动有关的信息。 Kubernetes 挂接/解除挂接控制器使用此对象来决定是否需要挂接。 kubelet 使用此对象决定挂载时是否需要传递 Pod 信息。 CSIDriver 对象未划分命名空间。

- **apiVersion**: storage.k8s.io/v1 - **kind**: CSIDriver - **metadata** (}}">ObjectMeta) 标准的对象元数据。 `metadata.name` 表示此对象引用的 CSI 驱动的名称；它必须与该驱动的 CSI `GetPluginName()` 调用返回的名称相同。驱动名称不得超过 63 个字符，以字母、数字（[a-z0-9A-Z]）开头和结尾，中间可包含短划线（-）、英文句点（.）、字母和数字。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - **spec** (}}">CSIDriverSpec)，必需 `spec` 表示 CSI 驱动的规约。 ## CSIDriverSpec {#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": { "": { "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} CSIDriverList 是 CSIDriver 对象的集合。

- **apiVersion**: storage.k8s.io/v1 - **kind**: CSIDriverList - **metadata** (}}">ListMeta) 标准的列表元数据。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - **items** ([]}}">CSIDriver)，必需 `items` 是 CSIDriver 的列表。 ## 操作 {#Operations}

### `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 #### 参数 - **allowWatchBookmarks** (**查询参数**): boolean }}">allowWatchBookmarks - **continue** (**查询参数**): string }}">continue - **fieldSelector** (**查询参数**): string }}">fieldSelector - **labelSelector** (**查询参数**): string }}">labelSelector - **limit** (**查询参数**): integer }}">limit - **pretty** (**查询参数**): string }}">pretty - **resourceVersion** (**查询参数**): string }}">resourceVersion - **resourceVersionMatch** (**查询参数**): string }}">resourceVersionMatch - **sendInitialEvents** (**查询参数**): boolean }}">sendInitialEvents - **shardSelector** (**查询参数**): string }}">shardSelector - **timeoutSeconds** (**查询参数**): integer }}">timeoutSeconds - **watch** (**查询参数**): boolean }}">watch #### 响应 200 (}}">CSIDriverList): OK 401: Unauthorized ### `create` 创建 CSIDriver #### HTTP 请求 POST /apis/storage.k8s.io/v1/csidrivers #### 参数 - **body**: }}">CSIDriver，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 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} #### 参数 - **name** (**路径参数**): string，必需 CSIDriver 的名称。 - **body**: }}">DeleteOptions - **dryRun** (**查询参数**): string }}">dryRun - **gracePeriodSeconds** (**查询参数**): integer }}">gracePeriodSeconds - **ignoreStoreReadErrorWithClusterBreakingPotential** (**查询参数**): boolean }}">ignoreStoreReadErrorWithClusterBreakingPotential - **pretty** (**查询参数**): string }}">pretty - **propagationPolicy** (**查询参数**): string }}">propagationPolicy #### 响应 200 (}}">CSIDriver): OK 202 (}}">CSIDriver): Accepted 401: Unauthorized ### `deletecollection` 删除 CSIDriver 的集合 #### HTTP 请求 DELETE /apis/storage.k8s.io/v1/csidrivers #### 参数 - **body**: }}">DeleteOptions - **continue** (**查询参数**): string }}">continue - **dryRun** (**查询参数**): string }}">dryRun - **fieldSelector** (**查询参数**): string }}">fieldSelector - **gracePeriodSeconds** (**查询参数**): integer }}">gracePeriodSeconds - **ignoreStoreReadErrorWithClusterBreakingPotential** (**查询参数**): boolean }}">ignoreStoreReadErrorWithClusterBreakingPotential - **labelSelector** (**查询参数**): string }}">labelSelector - **limit** (**查询参数**): integer }}">limit - **pretty** (**查询参数**): string }}">pretty - **propagationPolicy** (**查询参数**): string }}">propagationPolicy - **resourceVersion** (**查询参数**): string }}">resourceVersion - **resourceVersionMatch** (**查询参数**): string }}">resourceVersionMatch - **sendInitialEvents** (**查询参数**): boolean }}">sendInitialEvents - **shardSelector** (**查询参数**): string }}">shardSelector - **timeoutSeconds** (**查询参数**): integer }}">timeoutSeconds #### 响应 200 (}}">Status): OK 401: Unauthorized