PersistentVolumeClaim
apiVersion: v1
import "k8s.io/api/core/v1"
PersistentVolumeClaim
PersistentVolumeClaim 是用户针对一个持久卷的请求和申领。
apiVersion: v1
kind: PersistentVolumeClaim
metadata (ObjectMeta)
标准的对象元数据。更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
spec (PersistentVolumeClaimSpec)
spec 定义 Pod 作者所请求的卷的预期特征。更多信息: https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
status (PersistentVolumeClaimStatus)
status 表示一个持久卷申领的当前信息/状态。只读。更多信息: https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
PersistentVolumeClaimSpec
PersistentVolumeClaimSpec 描述存储设备的常用参数,并支持通过 source 来设置特定于提供商的属性。
accessModes ([]string)
原子性:将在合并期间被替换
accessModes 包含卷应具备的预期访问模式。更多信息: https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#access-modes-1
selector (LabelSelector)
selector 是在绑定时对卷进行选择所执行的标签查询。
- resources (VolumeResourceRequirements)
resources 表示卷应拥有的最小资源。 如果启用了 RecoverVolumeExpansionFailure 功能特性,则允许用户指定这些资源要求, 此值必须低于之前的值,但必须高于申领的状态字段中记录的容量。更多信息: https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#resources
VolumeResourceRequirements 描述了卷的存储资源要求。
resources.limits (map[string]Quantity)
limits 描述允许的最大计算资源量。更多信息: https://kubernetes.io/zh-cn/docs/concepts/configuration/manage-resources-containers/
resources.requests (map[string]Quantity)
requests 描述所需的最小计算资源量。 如果针对容器省略 requests,则在显式指定的情况下默认为 limits,否则为具体实现所定义的值。请求不能超过限制。更多信息: https://kubernetes.io/zh-cn/docs/concepts/configuration/manage-resources-containers/
volumeName (string)
volumeName 是对此申领所对应的 PersistentVolume 的绑定引用。
storageClassName (string)
storageClassName 是此申领所要求的 StorageClass 名称。更多信息: https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#class-1
volumeMode (string)
volumeMode 定义申领需要哪种类别的卷。当申领规约中未包含此字段时,意味着取值为 Filesystem。
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”。
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 各项的列表。
apiVersion: v1
kind: PersistentVolumeClaimList
metadata (ListMeta)
标准的列表元数据。更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
items ([]PersistentVolumeClaim),必需
items 是持久卷申领的列表。更多信息: https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
操作
get
读取指定的 PersistentVolumeClaim
HTTP 请求
GET /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}
参数
name (路径参数): string,必需
PersistentVolumeClaim 的名称
namespace (路径参数): string,必需
pretty (查询参数): string
响应
200 (PersistentVolumeClaim): OK
401: Unauthorized
get
读取指定的 PersistentVolumeClaim 的状态
HTTP 请求
GET /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status
参数
name (路径参数): string,必需
PersistentVolumeClaim 的名称
namespace (路径参数): string,必需
pretty (查询参数): string
响应
200 (PersistentVolumeClaim): OK
401: Unauthorized
list
列出或观测类别为 PersistentVolumeClaim 的对象
HTTP 请求
GET /api/v1/namespaces/{namespace}/persistentvolumeclaims
参数
namespace (路径参数): string,必需
allowWatchBookmarks (查询参数): boolean
continue (查询参数): string
fieldSelector (查询参数): string
labelSelector (查询参数): string
limit (查询参数): integer
pretty (查询参数): string
resourceVersion (查询参数): string
resourceVersionMatch (查询参数): string
sendInitialEvents (查询参数): boolean
timeoutSeconds (查询参数): integer
watch (查询参数): boolean
响应
200 (PersistentVolumeClaimList): OK
401: Unauthorized
list
列出或观测类别为 PersistentVolumeClaim 的对象
HTTP 请求
GET /api/v1/persistentvolumeclaims
参数
allowWatchBookmarks (查询参数): boolean
continue (查询参数): string
fieldSelector (查询参数): string
labelSelector (查询参数): string
limit (查询参数): integer
pretty (查询参数): string
resourceVersion (查询参数): string
resourceVersionMatch (查询参数): string
sendInitialEvents (查询参数): boolean
timeoutSeconds (查询参数): integer
watch (查询参数): boolean
响应
200 (PersistentVolumeClaimList): OK
401: Unauthorized
create
创建 PersistentVolumeClaim
HTTP 请求
POST /api/v1/namespaces/{namespace}/persistentvolumeclaims
参数
namespace (路径参数): string,必需
body: PersistentVolumeClaim,必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
pretty (查询参数): string
响应
200 (PersistentVolumeClaim): OK
201 (PersistentVolumeClaim): Created
202 (PersistentVolumeClaim): Accepted
401: Unauthorized
update
替换指定的 PersistentVolumeClaim
HTTP 请求
PUT /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}
参数
name (路径参数): string,必需
PersistentVolumeClaim 的名称
namespace (路径参数): string,必需
body: PersistentVolumeClaim,必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
pretty (查询参数): string
响应
200 (PersistentVolumeClaim): OK
201 (PersistentVolumeClaim): Created
401: Unauthorized
update
替换指定的 PersistentVolumeClaim 的状态
HTTP 请求
PUT /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status
参数
name (路径参数): string,必需
PersistentVolumeClaim 的名称
namespace (路径参数): string,必需
body: PersistentVolumeClaim,必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
pretty (查询参数): string
响应
200 (PersistentVolumeClaim): OK
201 (PersistentVolumeClaim): Created
401: Unauthorized
patch
部分更新指定的 PersistentVolumeClaim
HTTP 请求
PATCH /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}
参数
name (路径参数): string,必需
PersistentVolumeClaim 的名称
namespace (路径参数): string,必需
body: Patch,必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
force (查询参数): boolean
pretty (查询参数): string
响应
200 (PersistentVolumeClaim): OK
201 (PersistentVolumeClaim): Created
401: Unauthorized
patch
部分更新指定的 PersistentVolumeClaim 的状态
HTTP 请求
PATCH /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status
参数
name (路径参数): string,必需
PersistentVolumeClaim 的名称
namespace (路径参数): string,必需
body: Patch,必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
force (查询参数): boolean
pretty (查询参数): string
响应
200 (PersistentVolumeClaim): OK
201 (PersistentVolumeClaim): Created
401: Unauthorized
delete
删除 PersistentVolumeClaim
HTTP 请求
DELETE /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}
参数
name (路径参数): string,必需
PersistentVolumeClaim 的名称
namespace (路径参数): string,必需
body: DeleteOptions
dryRun (查询参数): string
gracePeriodSeconds (查询参数): integer
pretty (查询参数): string
propagationPolicy (查询参数): string
响应
200 (PersistentVolumeClaim): OK
202 (PersistentVolumeClaim): Accepted
401: Unauthorized
deletecollection
删除 PersistentVolumeClaim 的集合
HTTP 请求
DELETE /api/v1/namespaces/{namespace}/persistentvolumeclaims
参数
namespace (路径参数): string,必需
body: DeleteOptions
continue (查询参数): string
dryRun (查询参数): string
fieldSelector (查询参数): string
gracePeriodSeconds (查询参数): integer
labelSelector (查询参数): string
limit (查询参数): integer
pretty (查询参数): string
propagationPolicy (查询参数): string
resourceVersion (查询参数): string
resourceVersionMatch (查询参数): string
sendInitialEvents (查询参数): boolean
timeoutSeconds (查询参数): integer
响应
200 (Status): OK
401: Unauthorized