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) 如果提供程序或外部控制器可以支持指定的DataSource，它将基于指定DataSource的内容创建新的卷。当启用 AnyVolumeDataSource 特性门控时，dataSource 内容将被复制到 dataSourceRef，并且 dataSourceRef 内容将被复制到 dataSource，当 dataSourceRef.namespace 未指定时。如果指定了命名空间，则 dataSourceRef 将不会被复制到 dataSource。

  • dataSourceRef (TypedObjectReference)

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

    • 虽然 dataSource 忽略不允许的值（删除它们），但 dataSourceRef 会保留所有值，并在指定不允许的值时生成错误。
    • 虽然 dataSource 仅允许本地对象，但 dataSourceRef 允许任何命名空间中的对象。（Beta）使用此字段需要启用 AnyVolumeDataSource 特性门控。（Alpha）使用 dataSourceRef 的命名空间字段需要启用 CrossNamespaceVolumeDataSource 特性门控。

    TypedObjectReference 包含足够的信息来定位引用的类型对象

    • dataSourceRef.kind (string), required

      Kind 是被引用的资源的类型

    • dataSourceRef.name (string), required

      Name 是被引用的资源的名称

    • dataSourceRef.apiGroup (string)

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

    • dataSourceRef.namespace (string)

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

  • volumeAttributesClassName (string)

    volumeAttributesClassName 可用于设置此声明使用的 VolumeAttributesClass。如果指定，CSI 驱动程序将使用相应 VolumeAttributesClass 中定义的属性创建或更新卷。这与 storageClassName 不同，可以在声明创建后更改。如果声明进入 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：当调整大小控制器开始在控制平面中调整卷大小时设置的状态。- 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 进行调整大小操作。

    接收 PVC 更新的控制器，其中包含先前未知的 resourceName 或 ClaimResourceStatus，应忽略更新以达到其设计目的。例如 - 仅负责调整卷容量的控制器，应忽略更改与 PVC 关联的其他有效资源的 PVC 更新。

  • 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 更新。

  • capacity (map[string]Quantity)

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

  • conditions ([]PersistentVolumeClaimCondition)

    Patch 策略：在键 type 上合并

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

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

    PersistentVolumeClaimCondition 包含 pvc 状态的详细信息

  • currentVolumeAttributesClassName (string)

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

  • modifyVolumeStatus (ModifyVolumeStatus)

    ModifyVolumeStatus 表示 ControllerModifyVolume 操作的状态对象。如果未设置此对象，则表示没有正在尝试的 ModifyVolume 操作。

    ModifyVolumeStatus 表示 ControllerModifyVolume 操作的状态对象

    • modifyVolumeStatus.status (string), required

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

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

      可能的枚举值

      • "InProgress" InProgress 表示卷正在修改中
      • "Infeasible" Infeasible 表示 CSI 驱动程序已将请求拒绝为无效。要解决此错误，需要指定有效的 VolumeAttributesClass
      • "Pending" Pending 表示由于未满足要求（例如，指定的 VolumeAttributesClass 不存在）而无法修改 PersistentVolumeClaim

    • modifyVolumeStatus.targetVolumeAttributesClassName (string)

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

  • phase (string)

    phase 表示 PersistentVolumeClaim 的当前阶段。

    可能的枚举值

    • "Bound" 用于已绑定的 PersistentVolumeClaims
    • "Lost" 用于丢失其底层 PersistentVolume 的 PersistentVolumeClaims。声明已绑定到 PersistentVolume，并且此卷不再存在，并且所有数据都已丢失。
    • "Pending" 用于尚未绑定的 PersistentVolumeClaims

PersistentVolumeClaimList

PersistentVolumeClaimList 是 PersistentVolumeClaim 项目的列表。

操作

get 读取指定的 PersistentVolumeClaim

HTTP 请求

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

Parameters

  • name (在路径中): string, 必需

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string, 必需

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

401: 未授权

get 读取指定 PersistentVolumeClaim 的状态

HTTP 请求

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

Parameters

  • name (在路径中): string, 必需

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string, 必需

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

401: 未授权

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

HTTP 请求

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

Parameters

响应

200 (PersistentVolumeClaimList): OK

401: 未授权

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

HTTP 请求

GET /api/v1/persistentvolumeclaims

Parameters

响应

200 (PersistentVolumeClaimList): OK

401: 未授权

create 创建 PersistentVolumeClaim

HTTP 请求

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

Parameters

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

202 (PersistentVolumeClaim): Accepted

401: 未授权

update 替换指定的 PersistentVolumeClaim

HTTP 请求

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

Parameters

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

update 替换指定 PersistentVolumeClaim 的状态

HTTP 请求

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

Parameters

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

patch 部分更新指定的 PersistentVolumeClaim

HTTP 请求

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

Parameters

  • name (在路径中): string, 必需

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string, 必需

    命名空间

  • body: Patch, 必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

patch 部分更新指定 PersistentVolumeClaim 的状态

HTTP 请求

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

Parameters

  • name (在路径中): string, 必需

    PersistentVolumeClaim 的名称

  • namespace (在路径中): string, 必需

    命名空间

  • body: Patch, 必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: 未授权

delete 删除 PersistentVolumeClaim

HTTP 请求

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

Parameters

响应

200 (PersistentVolumeClaim): OK

202 (PersistentVolumeClaim): Accepted

401: 未授权

deletecollection 删除 PersistentVolumeClaim 集合

HTTP 请求

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

Parameters

响应

200 (Status): 确定

401: 未授权

本页面是自动生成的。

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

最后修改时间为 2025 年 12 月 21 日下午 5:37 PST：更新 v1.35 资源文档 (85b57273c5)