1. Documentation
    2. history bug_report picture_as_pdf
×

PersistentVolumeClaim [v1]

Specification

Property Type Description

apiVersion

string

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

kind

string

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

PersistentVolumeClaimSpec describes the common attributes of storage devices and allows a Source for provider-specific attributes

status

object

PersistentVolumeClaimStatus is the current status of a persistent volume claim.

.spec

Description

PersistentVolumeClaimSpec describes the common attributes of storage devices and allows a Source for provider-specific attributes

Type

object

Property Type Description

accessModes

array (string)

accessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1

dataSource

object

TypedLocalObjectReference contains enough information to let you locate the typed referenced object inside the same namespace.

dataSourceRef

object

TypedLocalObjectReference contains enough information to let you locate the typed referenced object inside the same namespace.

resources

object

ResourceRequirements describes the compute resource requirements.

selector

LabelSelector

selector is a label query over volumes to consider for binding.

storageClassName

string

storageClassName is the name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1

volumeMode

string

volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec.

volumeName

string

volumeName is the binding reference to the PersistentVolume backing this claim.

.spec.dataSource

Description

TypedLocalObjectReference contains enough information to let you locate the typed referenced object inside the same namespace.

Type

object

Required

  • kind

  • name

Property Type Description

apiGroup

string

APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required.

kind

string

Kind is the type of resource being referenced

name

string

Name is the name of resource being referenced

.spec.dataSourceRef

Description

TypedLocalObjectReference contains enough information to let you locate the typed referenced object inside the same namespace.

Type

object

Required

  • kind

  • name

Property Type Description

apiGroup

string

APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required.

kind

string

Kind is the type of resource being referenced

name

string

Name is the name of resource being referenced

.spec.resources

Description

ResourceRequirements describes the compute resource requirements.

Type

object

Property Type Description

limits

object (Quantity)

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

requests

object (Quantity)

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

.status

Description

PersistentVolumeClaimStatus is the current status of a persistent volume claim.

Type

object

Property Type Description

accessModes

array (string)

accessModes contains the actual access modes the volume backing the PVC has. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1

allocatedResources

object (Quantity)

allocatedResources is the storage resource within AllocatedResources tracks the capacity allocated to a PVC. It may be larger than the actual capacity when a volume expansion operation is requested. For storage quota, the larger value from allocatedResources and PVC.spec.resources is used. If allocatedResources is not set, PVC.spec.resources alone is used for quota calculation. If a volume expansion capacity request is lowered, allocatedResources is only lowered if there are no expansion operations in progress and if the actual volume capacity is equal or lower than the requested capacity. This is an alpha field and requires enabling RecoverVolumeExpansionFailure feature.

capacity

object (Quantity)

capacity represents the actual resources of the underlying volume.

conditions

array

conditions is the current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'.

conditions[]

object

PersistentVolumeClaimCondition contails details about state of pvc

phase

string

phase represents the current phase of PersistentVolumeClaim.

Possible enum values: - "Bound" used for PersistentVolumeClaims that are bound - "Lost" used for PersistentVolumeClaims that lost their underlying PersistentVolume. The claim was bound to a PersistentVolume and this volume does not exist any longer and all data on it was lost. - "Pending" used for PersistentVolumeClaims that are not yet bound

resizeStatus

string

resizeStatus stores status of resize operation. ResizeStatus is not set by default but when expansion is complete resizeStatus is set to empty string by resize controller or kubelet. This is an alpha field and requires enabling RecoverVolumeExpansionFailure feature.

.status.conditions

Description

conditions is the current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'.

Type

array

.status.conditions[]

Description

PersistentVolumeClaimCondition contails details about state of pvc

Type

object

Required

  • type

  • status

Property Type Description

lastProbeTime

Time

lastProbeTime is the time we probed the condition.

lastTransitionTime

Time

lastTransitionTime is the time the condition transitioned from one status to another.

message

string

message is the human-readable message indicating details about last transition.

reason

string

reason is a unique, this should be a short, machine understandable string that gives the reason for condition’s last transition. If it reports "ResizeStarted" that means the underlying persistent volume is being resized.

status

string

type

string

API endpoints

The following API endpoints are available:

  • /api/v1/persistentvolumeclaims

    • GET: list or watch objects of kind PersistentVolumeClaim

  • /api/v1/watch/persistentvolumeclaims

    • GET: watch individual changes to a list of PersistentVolumeClaim. deprecated: use the 'watch' parameter with a list operation instead.

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

    • DELETE: delete collection of PersistentVolumeClaim

    • GET: list or watch objects of kind PersistentVolumeClaim

    • POST: create a PersistentVolumeClaim

  • /api/v1/watch/namespaces/{namespace}/persistentvolumeclaims

    • GET: watch individual changes to a list of PersistentVolumeClaim. deprecated: use the 'watch' parameter with a list operation instead.

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

    • DELETE: delete a PersistentVolumeClaim

    • GET: read the specified PersistentVolumeClaim

    • PATCH: partially update the specified PersistentVolumeClaim

    • PUT: replace the specified PersistentVolumeClaim

  • /api/v1/watch/namespaces/{namespace}/persistentvolumeclaims/{name}

    • GET: watch changes to an object of kind PersistentVolumeClaim. deprecated: use the 'watch' parameter with a list operation instead, filtered to a single item with the 'fieldSelector' parameter.

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

    • GET: read status of the specified PersistentVolumeClaim

    • PATCH: partially update status of the specified PersistentVolumeClaim

    • PUT: replace status of the specified PersistentVolumeClaim

/api/v1/persistentvolumeclaims

Table 1. Global query parameters
Parameter Type Description

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server's discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the `continue` field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

pretty

string

If 'true', then the output is pretty printed.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.
HTTP method

GET

Description

list or watch objects of kind PersistentVolumeClaim

Table 2. HTTP responses
HTTP code Reponse body

200 - OK

PersistentVolumeClaimList schema

401 - Unauthorized

Empty

/api/v1/watch/persistentvolumeclaims

Table 3. Global query parameters
Parameter Type Description

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server's discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the `continue` field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only us