PersistentVolumeClaim

PersistentVolumeClaim 是用户对持久卷的请求和声明。

apiVersion: v1

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

PersistentVolumeClaim

PersistentVolumeClaim 是用户对持久卷的请求和声明

PersistentVolumeClaimSpec

PersistentVolumeClaimSpec 描述了存储设备的通用属性，并允许指定供应商特定的属性源

Beta 级别

  • dataSource (TypedLocalObjectReference)

    dataSource 字段可用于指定以下任一内容：* 现有的 VolumeSnapshot 对象 (snapshot.storage.k8s.io/VolumeSnapshot) * 现有的 PVC (PersistentVolumeClaim) 如果 provisioner 或外部控制器支持指定的数据源，它将根据指定数据源的内容创建一个新卷。当启用 AnyVolumeDataSource 功能门时， dataSource 内容将被复制到 dataSourceRef，并且当 dataSourceRef.namespace 未指定时，dataSourceRef 内容将被复制到 dataSource。如果指定了命名空间，则 dataSourceRef 不会被复制到 dataSource。

  • dataSourceRef (TypedObjectReference)

    dataSourceRef 指定了要从中填充卷数据的对象（如果需要非空卷）。这可以是来自非空 API 组（非核心对象）的任何对象，也可以是 PersistentVolumeClaim 对象。当指定此字段时，仅当指定对象的类型与某些已安装的卷填充器或动态 provisioner 匹配时，卷绑定才会成功。此字段将取代 dataSource 字段的功能，因此如果两个字段都非空，则它们必须具有相同的值。为了向后兼容，当 dataSourceRef 中未指定命名空间时，如果其中一个字段为空而另一个非空，则两个字段（dataSource 和 dataSourceRef）将自动设置为相同的值。当在 dataSourceRef 中指定了命名空间时， dataSource 不会设置为相同的值，并且必须为空。dataSource 和 dataSourceRef 之间有三个重要区别：* dataSource 只允许两种特定类型的对象，而 dataSourceRef 允许任何非核心对象以及 PersistentVolumeClaim 对象。

    • dataSource 忽略不允许的值（将其丢弃），而 dataSourceRef 保留所有值，并在指定不允许的值时生成错误。
    • dataSource 只允许本地对象，而 dataSourceRef 允许任何命名空间中的对象。（Beta）使用此字段需要启用 AnyVolumeDataSource 功能门。（Alpha）使用 dataSourceRef 的 namespace 字段需要启用 CrossNamespaceVolumeDataSource 功能门。

    TypedObjectReference 包含足够的信息，以便您可以找到类型化的引用对象

    • dataSourceRef.kind (string), required

      Kind 是所引用资源的类型

    • dataSourceRef.name (string), required

      Name 是所引用资源的名称

    • dataSourceRef.apiGroup (string)

      APIGroup 是被引用资源的组。如果未指定 APIGroup，则指定的 Kind 必须位于核心 API 组中。对于任何其他第三方类型，APIGroup 是必需的。

    • dataSourceRef.namespace (string)

      Namespace 是被引用资源的命名空间。请注意，当指定命名空间时，在引用命名空间中需要一个 gateway.networking.k8s.io/ReferenceGrant 对象，以允许该命名空间的所有者接受该引用。有关详细信息，请参阅 ReferenceGrant 文档。（Alpha）此字段需要启用 CrossNamespaceVolumeDataSource 功能门。

  • volumeAttributesClassName (string)

    volumeAttributesClassName 可用于设置此声明使用的 VolumeAttributesClass。如果指定，CSI 驱动程序将使用相应 VolumeAttributesClass 中定义的属性创建或更新卷。这与 storageClassName 的目的不同，它可以在声明创建后进行更改。空字符串或 nil 值表示没有 VolumeAttributesClass 将应用于该声明。如果声明进入 Infeasible 错误状态，可以将此字段重置为先前的值（包括 nil）以取消修改。如果 volumeAttributesClass 引用的资源不存在，此 PersistentVolumeClaim 将设置为 Pending 状态，如 modifyVolumeStatus 字段所示，直到该资源存在为止。更多信息： https://kubernetes.ac.cn/docs/concepts/storage/volume-attributes-classes/

PersistentVolumeClaimStatus

PersistentVolumeClaimStatus 是持久卷声明的当前状态。

  • accessModes ([]string)

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

    accessModes 包含卷支持 PVC 的实际访问模式。更多信息： https://kubernetes.ac.cn/docs/concepts/storage/persistent-volumes#access-modes-1

  • allocatedResourceStatuses (map[string]string)

    allocatedResourceStatuses 存储了给定 PVC 的正在调整大小的资源的状态。键名遵循标准的 Kubernetes 标签语法。有效值可以是：* 没有前缀的键：- storage - 卷的容量。* 自定义资源必须使用实现定义的带前缀的名称，例如“example.com/my-custom-resource”。除了以上值之外，未加前缀或带有 kubernetes.io 前缀的键被视为保留，因此不得使用。

    ClaimResourceStatus 可以处于以下任何状态：- ControllerResizeInProgress：当 resize 控制器在控制平面开始调整卷大小时设置的状态。- ControllerResizeFailed：当 resize 在控制平面中因终结错误而失败时设置的状态。- NodeResizePending：当 resize 控制器完成卷大小调整，但需要在节点上进行进一步调整时设置的状态。- NodeResizeInProgress：当 kubelet 开始调整卷大小时设置的状态。- NodeResizeFailed：当 resizing 在 kubelet 中因终结错误而失败时设置的状态。瞬时错误不会设置 NodeResizeFailed。例如：如果扩展 PVC 以获取更多容量 - 此字段可以是以下状态之一：- pvc.status.allocatedResourceStatus['storage'] = "ControllerResizeInProgress" - pvc.status.allocatedResourceStatus['storage'] = "ControllerResizeFailed" - pvc.status.allocatedResourceStatus['storage'] = "NodeResizePending" - pvc.status.allocatedResourceStatus['storage'] = "NodeResizeInProgress" - pvc.status.allocatedResourceStatus['storage'] = "NodeResizeFailed" 当未设置此字段时，表示没有正在进行的 PVC 调整大小操作。

    接收到先前未知 resourceName 或 ClaimResourceStatus 的 PVC 更新的控制器应忽略该更新，以实现其设计目的。例如 - 仅负责调整卷容量大小的控制器应忽略更改 PVC 相关其他有效资源的 PVC 更新。

    这是一个 Alpha 字段，需要启用 RecoverVolumeExpansionFailure 功能。

  • allocatedResources (map[string]Quantity)

    allocatedResources 跟踪分配给 PVC 的资源，包括其容量。键名遵循标准的 Kubernetes 标签语法。有效值可以是：* 没有前缀的键：- storage - 卷的容量。* 自定义资源必须使用实现定义的带前缀的名称，例如“example.com/my-custom-resource”。除了以上值之外，未加前缀或带有 kubernetes.io 前缀的键被视为保留，因此不得使用。

    当请求卷扩展操作时，此处报告的容量可能大于实际容量。对于存储配额，将使用 allocatedResources 和 PVC.spec.resources 中的较大值。如果未设置 allocatedResources，则仅使用 PVC.spec.resources 进行配额计算。如果卷扩展容量请求降低，则仅当没有正在进行的扩展操作且实际卷容量等于或低于请求容量时，allocatedResources 才会降低。

    接收到先前未知 resourceName 的 PVC 更新的控制器应忽略该更新，以实现其设计目的。例如 - 仅负责调整卷容量大小的控制器应忽略更改 PVC 相关其他有效资源的 PVC 更新。

    这是一个 Alpha 字段，需要启用 RecoverVolumeExpansionFailure 功能。

  • capacity (map[string]Quantity)

    capacity 表示底层卷的实际资源。

  • conditions ([]PersistentVolumeClaimCondition)

    补丁策略：按键 type 合并

    映射：合并时将保留键类型上的唯一值

    conditions 是持久卷声明的当前 Condition。如果底层持久卷正在调整大小，则 Condition 将设置为 'Resizing'。

    PersistentVolumeClaimCondition 包含 pvc 状态的详细信息

  • currentVolumeAttributesClassName (string)

    currentVolumeAttributesClassName 是 PVC 当前使用的 VolumeAttributesClass 的名称。当未设置时，此 PersistentVolumeClaim 没有应用 VolumeAttributeClass

  • modifyVolumeStatus (ModifyVolumeStatus)

    ModifyVolumeStatus 表示 ControllerModifyVolume 操作的状态对象。当未设置时，没有正在尝试的 ModifyVolume 操作。

    ModifyVolumeStatus 表示 ControllerModifyVolume 操作的状态对象

    • modifyVolumeStatus.status (string), required

      status 是 ControllerModifyVolume 操作的状态。它可以处于以下任何状态

      • Pending Pending 表示 PersistentVolumeClaim 由于未满足的要求（例如，指定的 VolumeAttributesClass 不存在）而无法修改。
      • InProgress InProgress 表示卷正在被修改。
      • Infeasible Infeasible 表示请求已被 CSI 驱动程序拒绝为无效。要解决此错误，需要指定一个有效的 VolumeAttributesClass。注意：未来可能会添加新的状态。使用者应检查未知状态并适当处理失败。

    • modifyVolumeStatus.targetVolumeAttributesClassName (string)

      targetVolumeAttributesClassName 是 PVC 当前正在协调的 VolumeAttributesClass 的名称

  • phase (string)

    phase 表示 PersistentVolumeClaim 的当前阶段。

PersistentVolumeClaimList

PersistentVolumeClaimList 是 PersistentVolumeClaim 项的列表。

操作

get 读取指定的 PersistentVolumeClaim

HTTP 请求

GET /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}

参数

  • name (在路径中): string，必填

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

401: 未授权

get 读取指定 PersistentVolumeClaim 的状态

HTTP 请求

GET /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status

参数

  • name (在路径中): string，必填

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

401: 未授权

list 列出或监视 PersistentVolumeClaim 类型的对象

HTTP 请求

GET /api/v1/namespaces/{namespace}/persistentvolumeclaims

参数

响应

200 (PersistentVolumeClaimList): OK

401: 未授权

list 列出或监视 PersistentVolumeClaim 类型的对象

HTTP 请求

GET /api/v1/persistentvolumeclaims

参数

响应

200 (PersistentVolumeClaimList): OK

401: 未授权

create 创建一个 PersistentVolumeClaim

HTTP 请求

POST /api/v1/namespaces/{namespace}/persistentvolumeclaims

参数

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

202 (PersistentVolumeClaim): Accepted

401: 未授权

update 替换指定的 PersistentVolumeClaim

HTTP 请求

PUT /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}

参数

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

update 替换指定 PersistentVolumeClaim 的状态

HTTP 请求

PUT /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status

参数

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

patch 部分更新指定的 PersistentVolumeClaim

HTTP 请求

PATCH /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}

参数

  • name (在路径中): string，必填

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Patch，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (在查询中): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

patch 部分更新指定 PersistentVolumeClaim 的状态

HTTP 请求

PATCH /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status

参数

  • name (在路径中): string，必填

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Patch，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (在查询中): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

delete 删除一个 PersistentVolumeClaim

HTTP 请求

DELETE /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}

参数

响应

200 (PersistentVolumeClaim): OK

202 (PersistentVolumeClaim): Accepted

401: 未授权

deletecollection 删除 PersistentVolumeClaim 的集合

HTTP 请求

DELETE /api/v1/namespaces/{namespace}/persistentvolumeclaims

参数

响应

200 (Status): OK

401: 未授权

本页面是自动生成的。

如果你打算报告此页面存在的问题，请在问题描述中提及此页面是自动生成的。修复可能需要在 Kubernetes 项目的其他地方进行。

上次修改时间：2025 年 9 月 4 日 下午 3:37 PST：更新 v1.34 的 API 资源参考 (3e10e8c195)