PersistentVolumeClaim

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

apiVersion: v1

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

PersistentVolumeClaim

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

PersistentVolumeClaimSpec

PersistentVolumeClaimSpec 描述了存储设备的通用属性，并允许为特定于提供者的属性指定 Source

Beta 级别

  • dataSource (TypedLocalObjectReference)

    dataSource 字段可用于指定以下任一内容：* 现有的 VolumeSnapshot 对象 (snapshot.storage.k8s.io/VolumeSnapshot) * 现有的 PVC (PersistentVolumeClaim) 如果 Provisioner 或外部控制器支持指定的 data source，它将基于指定 data source 的内容创建新卷。启用 AnyVolumeDataSource 特性门控后，如果未指定 dataSourceRef.namespace，dataSource 的内容将复制到 dataSourceRef，dataSourceRef 的内容将复制到 dataSource。如果指定了 namespace，则 dataSourceRef 不会复制到 dataSource。

  • dataSourceRef (TypedObjectReference)

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

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

    TypedObjectReference 包含足够的信息，以便你可以定位类型化的引用对象

    • dataSourceRef.kind (string)，必需

      Kind 是被引用资源的类型

    • dataSourceRef.name (string)，必需

      Name 是被引用资源的名称

    • dataSourceRef.apiGroup (string)

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

    • dataSourceRef.namespace (string)

      Namespace 是被引用资源的 namespace。请注意，指定 namespace 后，被引用资源的 namespace 中需要一个 gateway.networking.k8s.io/ReferenceGrant 对象，以允许该 namespace 的所有者接受该引用。详见 ReferenceGrant 文档。(Alpha) 此字段需要启用 CrossNamespaceVolumeDataSource 特性门控。

  • volumeAttributesClassName (string)

    volumeAttributesClassName 可用于设置此声明使用的 VolumeAttributesClass。如果指定，CSI 驱动程序将使用相应的 VolumeAttributesClass 中定义的属性创建或更新卷。这与 storageClassName 的用途不同，它可以在创建声明后更改。空字符串值表示不会将 VolumeAttributesClass 应用于此声明，但一旦设置此字段，则不允许将其重置为空字符串。如果未指定且 PersistentVolumeClaim 未绑定，则如果存在默认 VolumeAttributesClass，将由 PersistentVolume Controller 设置。如果 volumeAttributesClass 引用的资源不存在，此 PersistentVolumeClaim 将被设置为 Pending 状态（由 modifyVolumeStatus 字段反映），直到该资源存在。更多信息：https://kubernetes.ac.cn/docs/concepts/storage/volume-attributes-classes/ (Beta) 使用此字段需要启用 VolumeAttributesClass 特性门控（默认关闭）。

PersistentVolumeClaimStatus

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

  • accessModes ([]string)

    Atomic: 在合并期间将被替换

    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：当扩容控制器在控制平面中开始对卷进行扩容时设置的状态。- ControllerResizeFailed：当扩容控制器在扩容时遇到终结性错误而失败时设置的状态。- NodeResizePending：当扩容控制器已完成卷扩容但在节点上还需要进一步扩容时设置的状态。- NodeResizeInProgress：当 Kubelet 开始对卷进行扩容时设置的状态。- NodeResizeFailed：当 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)

    Patch 策略：按键 type 合并

    Map: 合并期间将保留键 type 的唯一值

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

    PersistentVolumeClaimCondition 包含 PVC 状态的详细信息

  • currentVolumeAttributesClassName (string)

    currentVolumeAttributesClassName 是 PVC 当前使用的 VolumeAttributesClass 的名称。未设置时，没有 VolumeAttributeClass 应用于此 PersistentVolumeClaim。这是一个 Beta 字段，需要启用 VolumeAttributesClass 功能门控（默认关闭）。

  • modifyVolumeStatus (ModifyVolumeStatus)

    ModifyVolumeStatus 表示 ControllerModifyVolume 操作的状态对象。未设置此字段时，没有正在进行的 ModifyVolume 操作。这是一个 Beta 字段，需要启用 VolumeAttributesClass 功能门控（默认关闭）。

    ModifyVolumeStatus 表示 ControllerModifyVolume 操作的状态对象

    • modifyVolumeStatus.status (string)，必需

      status 是 ControllerModifyVolume 操作的状态。可以处于以下任一状态：

      • Pending Pending 表示由于未满足的要求（例如指定的 VolumeAttributesClass 不存在），PersistentVolumeClaim 无法修改。
      • 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 (in path): string，必需

    PersistentVolumeClaim 的名称

  • namespace (in path): string，必需

    namespace

  • pretty (in query): string

    pretty

响应

200 (PersistentVolumeClaim): 成功

401: 未授权

get 读取指定的 PersistentVolumeClaim 的状态

HTTP 请求

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

参数

  • name (in path): string，必需

    PersistentVolumeClaim 的名称

  • namespace (in path): string，必需

    namespace

  • pretty (in query): string

    pretty

响应

200 (PersistentVolumeClaim): 成功

401: 未授权

list 列出或监视 kind 为 PersistentVolumeClaim 的对象

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaimList): 成功

401: 未授权

list 列出或监视 kind 为 PersistentVolumeClaim 的对象

HTTP 请求

GET /api/v1/persistentvolumeclaims

参数

响应

200 (PersistentVolumeClaimList): 成功

401: 未授权

create 创建一个 PersistentVolumeClaim

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): 成功

201 (PersistentVolumeClaim): 已创建

202 (PersistentVolumeClaim): 已接受

401: 未授权

update 替换指定的 PersistentVolumeClaim

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): 成功

201 (PersistentVolumeClaim): 已创建

401: 未授权

update 替换指定的 PersistentVolumeClaim 的状态

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): 成功

201 (PersistentVolumeClaim): 已创建

401: 未授权

patch 部分更新指定的 PersistentVolumeClaim

HTTP 请求

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

参数

  • name (in path): string，必需

    PersistentVolumeClaim 的名称

  • namespace (in path): string，必需

    namespace

  • body: Patch，必需

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

响应

200 (PersistentVolumeClaim): 成功

201 (PersistentVolumeClaim): 已创建

401: 未授权

patch 部分更新指定的 PersistentVolumeClaim 的状态

HTTP 请求

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

参数

  • name (in path): string，必需

    PersistentVolumeClaim 的名称

  • namespace (in path): string，必需

    namespace

  • body: Patch，必需

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

响应

200 (PersistentVolumeClaim): 成功

201 (PersistentVolumeClaim): 已创建

401: 未授权

delete 删除一个 PersistentVolumeClaim

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): 成功

202 (PersistentVolumeClaim): 已接受

401: 未授权

deletecollection 删除 PersistentVolumeClaim 集合

HTTP 请求

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

参数

响应

200 (Status): 成功

401: 未授权

本页是自动生成的。

如果你打算报告此页面的问题，请在问题描述中注明该页面是自动生成的。修复可能需要在 Kubernetes 项目中的其他位置进行。

最后修改时间：2025 年 4 月 9 日 下午 6:36 PST：更新 v1.32 的 API 参考文档 (a3b579d035)