From 2d8986545b5c3304946b48ff368878f52c63efed Mon Sep 17 00:00:00 2001 From: Michael Date: Sat, 11 Jun 2022 10:28:22 +0800 Subject: [PATCH] [zh] resync ref-k8s-api-config: csi-driver-v1.md --- .../csi-driver-v1.md | 718 ++++++++++++++++++ 1 file changed, 718 insertions(+) create mode 100644 content/zh-cn/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md diff --git a/content/zh-cn/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md b/content/zh-cn/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md new file mode 100644 index 0000000000..29011ebe89 --- /dev/null +++ b/content/zh-cn/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md @@ -0,0 +1,718 @@ +--- +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: 8 +--- + + +`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)，必需 + + CSI 驱动的规约。 + +## CSIDriverSpec {#CSIDriverSpec} + + +CSIDriverSpec 是 CSIDriver 的规约。 + +
+ + +- **attachRequired** (boolean) + + attachRequired 表示这个 CSI 卷驱动需要挂接操作 + （因为它实现了 CSI ControllerPublishVolume() 方法）， + Kubernetes 挂接/解除挂接控制器应调用挂接卷接口， + 以检查卷挂接（volumeattachment）状态并在继续挂载之前等待卷被挂接。 + CSI 外部挂接器与 CSI 卷驱动配合使用，并在挂接操作完成时更新 volumeattachment 状态。 + 如果 CSIDriverRegistry 特性门控被启用且此值指定为 false，将跳过挂接操作。 + 否则将调用挂接操作。 + + 此字段不可变更。 + + +- **fsGroupPolicy** (string) + + 定义底层卷是否支持在挂载之前更改卷的所有权和权限。 + 有关更多详细信息，请参考特定的 FSGroupPolicy 值。 + + 此字段不可变更。 + + 默认为 ReadWriteOnceWithFSType，这会检查每个卷，以决定 Kubernetes 是否应修改卷的所有权和权限。 + 采用默认策略时，如果定义了 fstype 且卷的访问模式包含 ReadWriteOnce，将仅应用定义的 fsGroup。 + + +- **podInfoOnMount** (boolean) + + 如果设为 true，则 podInfoOnMount 表示在挂载操作期间这个 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 不支持此字段，所以在这类集群上部署驱动时，只能支持一种模式。 + 该部署就决定了是哪种模式，例如通过驱动的命令行参数。 + + 此字段不可变更。 + + +- **requiresRepublish** (boolean) + + requiresRepublish 表示 CSI 驱动想要 `NodePublishVolume` 被周期性地调用， + 以反映已挂载卷中的任何可能的变化。 + 此字段默认为 false。 + + 注：成功完成对 NodePublishVolume 的初始调用后，对 NodePublishVolume 的后续调用只应更新卷的内容。 + 新的挂载点将不会被运行的容器察觉。 + + +- **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": , + }, + ... + } + ``` + + 注：每个 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 + +- **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 + +- **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 + +- **labelSelector** (**查询参数**): string + + }}">labelSelector + +- **limit** (**查询参数**): integer + + }}">limit + +- **pretty** (**查询参数**): string + + }}">pretty + +- **propagationPolicy** (**查询参数**): string + + }}">propagationPolicy + +- **resourceVersion** (**查询参数**): string + + }}">resourceVersion + +- **resourceVersionMatch** (**查询参数**): string + + }}">resourceVersionMatch + +- **timeoutSeconds** (**查询参数**): integer + + }}">timeoutSeconds + + +#### 响应 + +200 (}}">Status): OK + +401: Unauthorized