PersistentVolumeClaim

PersistentVolumeClaim 是用户针对一个持久卷的请求和申领。

apiVersion: v1

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

PersistentVolumeClaim

PersistentVolumeClaim 是用户针对一个持久卷的请求和申领。

PersistentVolumeClaimSpec

PersistentVolumeClaimSpec 描述存储设备的常用参数，并支持通过 source 来设置特定于提供商的属性。

resources 表示卷应拥有的最小资源。 如果启用了 RecoverVolumeExpansionFailure 功能特性，则允许用户指定这些资源要求， 此值必须低于之前的值，但必须高于申领的状态字段中记录的容量。更多信息： https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#resources

VolumeResourceRequirements 描述了卷的存储资源要求。

Beta 级别

  • dataSource (TypedLocalObjectReference)

    dataSource 字段可用于二选一：

    • 现有的 VolumeSnapshot 对象（snapshot.storage.k8s.io/VolumeSnapshot）

    • 现有的 PVC (PersistentVolumeClaim)

    如果制备器或外部控制器可以支持指定的数据源，则它将根据指定数据源的内容创建新的卷。 当 AnyVolumeDataSource 特性门控被启用时，dataSource 内容将被复制到 dataSourceRef， 当 dataSourceRef.namespace 未被指定时，dataSourceRef 内容将被复制到 dataSource。 如果名字空间被指定，则 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 特性门控。

    • dataSourceRef.kind (string)，必需

    kind 是正被引用的资源的类型。

    • dataSourceRef.name (string)，必需

      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 的用途不同，此属性可以在创建申领之后更改。空字符串值表示不会将 VolumeAttributesClass 应用于申领，但一旦设置，就不允许将此字段重置为空字符串。如果未指定且 PersistentVolumeClaim 未绑定， 则持久卷控制器将设置默认的 VolumeAttributesClass（如果存在）。 如果 VolumeAttributesClass 所引用的资源不存在，则此 PersistentVolumeClaim 将被设置为 Pending 状态， 如 modifyVolumeStatus 字段所示，直到存在此类资源。更多信息： https://kubernetes.io/zh-cn/docs/concepts/storage/volume-attributes-classes/

    （Beta）使用此字段需要启用 VolumeAttributesClass 特性门控（默认情况下关闭）。

PersistentVolumeClaimStatus

PersistentVolumeClaimStatus 是持久卷申领的当前状态。

  • accessModes ([]string)

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

    accessModes 包含支持 PVC 的卷所具有的实际访问模式。更多信息： https://kubernetes.io/zh-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)

    补丁策略：按照键 type 合并

    映射：基于 name 键的唯一值将在合并期间被保留

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

    PersistentVolumeClaimCondition 包含有关 PVC 状态的详细信息。

  • conditions.status (string)，必需

  • conditions.type (string)，必需

  • conditions.lastProbeTime (Time)

    lastProbeTime 是我们探测 PVC 状况的时间。

    Time 是 time.Time 的包装类，支持正确地序列化为 YAML 和 JSON。 为 time 包提供的许多工厂方法提供了包装类。

  • conditions.lastTransitionTime (Time)

    lastTransitionTime 是状况从一个状态转换为另一个状态的时间。

    Time 是 time.Time 的包装类，支持正确地序列化为 YAML 和 JSON。 为 time 包提供的许多工厂方法提供了包装类。

  • conditions.message (string)

    message 是人类可读的消息，指示有关上一次转换的详细信息。

  • conditions.reason (string)

    reason 是唯一的，它应该是一个机器可理解的简短字符串，指明上次状况转换的原因。 如果它报告 “Resizing”，则意味着正在调整底层持久卷的大小。

  • currentVolumeAttributesClassName (string)

    currentVolumeAttributesClassName 是 PVC 所使用的 VolumeAttributesClass 的当前名称。 这是一个 Beta 级别字段，需要启用 VolumeAttributesClass 特性（默认情况下处于关闭状态）。

  • modifyVolumeStatus (ModifyVolumeStatus)

    modifyVolumeStatus 表示 ControllerModifyVolume 操作的状态对象。 如果未设置，则表示没有尝试执行任何修改卷操作。这是一个测试字段，需要启用 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 (路径参数): string，必需

    PersistentVolumeClaim 的名称

  • namespace (路径参数): string，必需

    namespace

  • pretty (查询参数): string

    pretty

响应

200 (PersistentVolumeClaim): OK

401: Unauthorized

get 读取指定的 PersistentVolumeClaim 的状态

HTTP 请求

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

参数

  • name (路径参数): string，必需

    PersistentVolumeClaim 的名称

  • namespace (路径参数): string，必需

    namespace

  • pretty (查询参数): string

    pretty

响应

200 (PersistentVolumeClaim): OK

401: Unauthorized

list 列出或观测类别为 PersistentVolumeClaim 的对象

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaimList): OK

401: Unauthorized

list 列出或观测类别为 PersistentVolumeClaim 的对象

HTTP 请求

GET /api/v1/persistentvolumeclaims

参数

响应

200 (PersistentVolumeClaimList): OK

401: Unauthorized

create 创建 PersistentVolumeClaim

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

202 (PersistentVolumeClaim): Accepted

401: Unauthorized

update 替换指定的 PersistentVolumeClaim

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: Unauthorized

update 替换指定的 PersistentVolumeClaim 的状态

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: Unauthorized

patch 部分更新指定的 PersistentVolumeClaim

HTTP 请求

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

参数

  • name (路径参数): string，必需

    PersistentVolumeClaim 的名称

  • namespace (路径参数): string，必需

    namespace

  • body: Patch，必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • force (查询参数): boolean

    force

  • pretty (查询参数): string

    pretty

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: Unauthorized

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

HTTP 请求

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

参数

  • name (路径参数): string，必需

    PersistentVolumeClaim 的名称

  • namespace (路径参数): string，必需

    namespace

  • body: Patch，必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • force (查询参数): boolean

    force

  • pretty (查询参数): string

    pretty

响应

200 (PersistentVolumeClaim): OK

201 (PersistentVolumeClaim): Created

401: Unauthorized

delete 删除 PersistentVolumeClaim

HTTP 请求

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

参数

响应

200 (PersistentVolumeClaim): OK

202 (PersistentVolumeClaim): Accepted

401: Unauthorized

deletecollection 删除 PersistentVolumeClaim 的集合

HTTP 请求

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

参数

响应

200 (Status): OK

401: Unauthorized