--- api_metadata: apiVersion: "v1" import: "k8s.io/api/core/v1" kind: "PersistentVolumeClaim" content_type: "api_reference" description: "PersistentVolumeClaim 是用户针对一个持久卷的请求和申领。" title: "PersistentVolumeClaim" weight: 4 --- `apiVersion: v1` `import "k8s.io/api/core/v1"` ## PersistentVolumeClaim {#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} PersistentVolumeClaimSpec 描述存储设备的常用参数，并支持通过 source 来设置特定于提供商的属性。

- **accessModes** ([]string) accessModes 包含卷应具备的预期访问模式。更多信息： https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#access-modes-1 - **selector** (}}">LabelSelector) selector 是在绑定时对卷进行选择所执行的标签查询。 - **resources** (ResourceRequirements) resources 表示卷应拥有的最小资源。如果启用了 RecoverVolumeExpansionFailure 功能特性，则允许用户指定这些资源要求，此值必须低于之前的值，但必须高于申领的状态字段中记录的容量。更多信息： https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#resources **ResourceRequirements 描述计算资源要求。** - **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。 ### Alpha 级别 - **dataSource** (}}">TypedLocalObjectReference) dataSource 字段可用于二选一： * 现有的 VolumeSnapshot 对象（snapshot.storage.k8s.io/VolumeSnapshot） * 现有的 PVC (PersistentVolumeClaim) 如果制备器或外部控制器可以支持指定的数据源，则它将根据指定数据源的内容创建新的卷。如果 AnyVolumeDataSource 特性门控被启用，此字段的内容将始终与 dataSourceRef 字段内容相同。 - **dataSourceRef** (}}">TypedLocalObjectReference) dataSourceRef 指定一个对象，当需要非空卷时，可以使用它来为卷填充数据。此字段值可以是来自非空 API 组（非核心对象）的一个本地对象，或一个 PersistentVolumeClaim 对象。如果设置了此字段，则仅当所指定对象的类型与所安装的某些卷填充器或动态制备器匹配时，卷绑定才会成功。此字段将替换 dataSource 字段的功能，因此如果两个字段非空，其取值必须相同。为了向后兼容，如果其中一个字段为空且另一个字段非空，则两个字段（dataSource 和 dataSourceRef）将被自动设为相同的值。 dataSource 和 dataSourceRef 之间有两个重要的区别： * dataSource 仅允许两个特定类型的对象，而 dataSourceRef 允许设置任何非核心对象以及 PersistentVolumeClaim 对象。 * dataSource 忽略不允许的值（这类值会被丢弃），dataSourceRef 保留所有值并在指定不允许的值时产生错误。（Beta）使用此字段需要启用 AnyVolumeDataSource 特性门控。 ## PersistentVolumeClaimStatus {#PersistentVolumeClaimStatus} PersistentVolumeClaimStatus 是持久卷申领的当前状态。

- **accessModes** ([]string) accessModes 包含支持 PVC 的卷所具有的实际访问模式。更多信息： https://kubernetes.io/zh-cn/docs/concepts/storage/persistent-volumes#access-modes-1 - **allocatedResources** (map[string]}}">Quantity) allocatedResources 跟踪分配给 PVC 的容量。当出现卷扩充操作请求时，此字段可能大于实际的容量。就存储配额而言，将使用 allocatedResources 和 PVC.spec.resources 二者中的更大值。如果未设置 allocatedResources，则 PVC.spec.resources 单独用于配额计算。如果减小一个卷扩充容量请求，则仅当没有正在进行的扩充操作且实际卷容量等于或小于请求的容量时，才会减小 allocatedResources。这是一个 Alpha 字段，需要启用 RecoverVolumeExpansionFailure 功能特性。 - **capacity** (map[string]}}">Quantity) capacity 表示底层卷的实际资源。 - **conditions** ([]PersistentVolumeClaimCondition) **补丁策略：按照键 `type` 合并** conditions 是持久卷声明的当前的状况。如果正在调整底层持久卷的大小，则状况将被设为 “ResizeStarted”。 **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 是唯一的，它应该是一个机器可理解的简短字符串，指明上次状况转换的原因。如果它报告 “ResizeStarted”，则意味着正在调整底层持久卷的大小。 - **phase** (string) phase 表示 PersistentVolumeClaim 的当前阶段。 - **resizeStatus** (string) resizeStatus 存储大小调整操作的状态。默认不设置 resizeStatus，但在扩充完成时， resizeStatus 将由大小调整控制器或 kubelet 设为空。这是一个 Alpha 字段，需要启用 RecoverVolumeExpansionFailure 功能特性。 ## PersistentVolumeClaimList {#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 ## 操作 {#Operations}

### `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 #### 参数 - **namespace** (**路径参数**): string，必需 }}">namespace - **allowWatchBookmarks** (**查询参数**): boolean }}">allowWatchBookmarks - **continue** (**查询参数**): string }}">continue - **fieldSelector** (**查询参数**): string }}">fieldSelector - **labelSelector** (**查询参数**): string }}">labelSelector - **limit** (**查询参数**): integer }}">limit - **pretty** (**查询参数**): string }}">pretty - **resourceVersion** (**查询参数**): string }}">resourceVersion - **resourceVersionMatch** (**查询参数**): string }}">resourceVersionMatch - **timeoutSeconds** (**查询参数**): integer }}">timeoutSeconds - **watch** (**查询参数**): boolean }}">watch #### 响应 200 (}}">PersistentVolumeClaimList): OK 401: Unauthorized ### `list` 列出或观测类别为 PersistentVolumeClaim 的对象 #### HTTP 请求 GET /api/v1/persistentvolumeclaims #### 参数 - **allowWatchBookmarks** (**查询参数**): boolean }}">allowWatchBookmarks - **continue** (**查询参数**): string }}">continue - **fieldSelector** (**查询参数**): string }}">fieldSelector - **labelSelector** (**查询参数**): string }}">labelSelector - **limit** (**查询参数**): integer }}">limit - **pretty** (**查询参数**): string }}">pretty - **resourceVersion** (**查询参数**): string }}">resourceVersion - **resourceVersionMatch** (**查询参数**): string }}">resourceVersionMatch - **timeoutSeconds** (**查询参数**): integer }}">timeoutSeconds - **watch** (**查询参数**): boolean }}">watch #### 响应 200 (}}">PersistentVolumeClaimList): OK 401: Unauthorized ### `create` 创建 PersistentVolumeClaim #### HTTP 请求 POST /api/v1/namespaces/{namespace}/persistentvolumeclaims #### 参数 - **namespace** (**路径参数**): string，必需 }}">namespace - **body**: }}">PersistentVolumeClaim，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 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，必需 }}">namespace - **body**: }}">PersistentVolumeClaim，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">PersistentVolumeClaim): OK 201 (}}">PersistentVolumeClaim): Created 401: Unauthorized ### `update` 替换指定的 PersistentVolumeClaim 的状态 #### HTTP 请求 PUT /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status #### 参数 - **name** (**路径参数**): string，必需 PersistentVolumeClaim 的名称 - **namespace** (**路径参数**): string，必需 }}">namespace - **body**: }}">PersistentVolumeClaim，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 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} #### 参数 - **name** (**路径参数**): string，必需 PersistentVolumeClaim 的名称 - **namespace** (**路径参数**): string，必需 }}">namespace - **body**: }}">DeleteOptions - **dryRun** (**查询参数**): string }}">dryRun - **gracePeriodSeconds** (**查询参数**): integer }}">gracePeriodSeconds - **pretty** (**查询参数**): string }}">pretty - **propagationPolicy** (**查询参数**): string }}">propagationPolicy #### 响应 200 (}}">PersistentVolumeClaim): OK 202 (}}">PersistentVolumeClaim): Accepted 401: Unauthorized ### `deletecollection` 删除 PersistentVolumeClaim 的集合 #### HTTP 请求 DELETE /api/v1/namespaces/{namespace}/persistentvolumeclaims #### 参数 - **namespace** (**路径参数**): string，必需 }}">namespace - **body**: }}">DeleteOptions - **continue** (**查询参数**): string }}">continue - **dryRun** (**查询参数**): string }}">dryRun - **fieldSelector** (**查询参数**): string }}">fieldSelector - **gracePeriodSeconds** (**查询参数**): integer }}">gracePeriodSeconds - **labelSelector** (**查询参数**): string }}">labelSelector - **limit** (**查询参数**): integer }}">limit - **pretty** (**查询参数**): string }}">pretty - **propagationPolicy** (**查询参数**): string }}">propagationPolicy - **resourceVersion** (**查询参数**): string }}">resourceVersion - **resourceVersionMatch** (**查询参数**): string }}">resourceVersionMatch - **timeoutSeconds** (**查询参数**): integer }}">timeoutSeconds #### 响应 200 (}}">Status): OK 401: Unauthorized