PersistentVolumeClaim

PersistentVolumeClaim — это запрос пользователя на постоянный том и заявка на его получение

Документация по концепции PersistentVolumeClaim

Постоянные тома

apiVersion: v1

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

PersistentVolumeClaim

PersistentVolumeClaim — это запрос пользователя на постоянный том и заявка на его получение

Поле	Описание
`apiVersion` string	APIVersion определяет версионированную схему этого представления объекта. Серверы должны преобразовывать распознанные схемы в последнее внутреннее представление и могут отклонять нераспознанные значения. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`kind` string	Kind — строковое значение, представляющее ресурс REST, который соответствует этому объекту. Серверы могут определять его по конечной точке, на которую клиент отправляет запросы. Изменение не допускается. В CamelCase. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ObjectMeta	Стандартные метаданные объекта. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
`spec` PersistentVolumeClaimSpec	spec определяет желаемые характеристики тома, запрошенного автором пода. Подробнее: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
`status` PersistentVolumeClaimStatus	status содержит текущую информацию о заявке на постоянный том и её состояние. Только для чтения. Подробнее: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims

PersistentVolumeClaimSpec

PersistentVolumeClaimSpec описывает общие атрибуты устройств хранения и позволяет указать источник для атрибутов, зависящих от поставщика

Поле	Описание
`accessModes` string array	accessModes содержит желаемые режимы доступа для тома. Подробнее: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1
`dataSource` TypedLocalObjectReference	Поле dataSource можно использовать для указания одного из следующих объектов: * Существующий объект VolumeSnapshot (snapshot.storage.k8s.io/VolumeSnapshot) * Существующий PVC (PersistentVolumeClaim). Если поставщик или внешний контроллер поддерживает указанный источник данных, он создаст новый том на основе содержимого этого источника данных. Если включён feature gate AnyVolumeDataSource, содержимое dataSource будет скопировано в dataSourceRef, а содержимое dataSourceRef будет скопировано в dataSource, если namespace не указан в dataSourceRef. Если пространство имён указано, dataSourceRef не будет скопировано в dataSource.
`dataSourceRef` TypedObjectReference	dataSourceRef указывает объект, из которого следует заполнить том данными, если требуется непустой том. Это может быть любой объект из непустой группы API (не из основной группы) или объект PersistentVolumeClaim. Если это поле указано, привязка тома будет успешной, только если тип указанного объекта соответствует одному из установленных заполнителей томов или динамических поставщиков. Это поле заменяет функциональность поля dataSource, поэтому при заполнении обоих полей их значения должны совпадать. Для обратной совместимости, если namespace не указан в dataSourceRef, оба поля (dataSource и dataSourceRef) будут автоматически иметь одинаковое значение, если одно из них пустое, а другое заполнено. Если namespace указан в dataSourceRef, dataSource не получает такое же значение и должен оставаться пустым. Между dataSource и dataSourceRef есть три важных различия: * dataSource допускает только два определённых типа объектов, а dataSourceRef — любые объекты, кроме объектов основной группы, а также объекты PersistentVolumeClaim. * dataSource игнорирует запрещённые значения (отбрасывает их), а dataSourceRef сохраняет все значения и выдаёт ошибку, если указано запрещённое значение. * dataSource допускает только локальные объекты, а dataSourceRef — объекты из любых пространств имён. (Бета) Для использования этого поля необходимо включить feature gate AnyVolumeDataSource. (Альфа) Для использования поля namespace в dataSourceRef необходимо включить feature gate CrossNamespaceVolumeDataSource.
`resources` VolumeResourceRequirements	resources указывает минимальные ресурсы, которыми должен располагать том. Пользователям разрешено указывать требования к ресурсам ниже предыдущего значения, но они должны оставаться выше ёмкости, записанной в поле status заявки. Подробнее: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources
`selector` LabelSelector	selector — это запрос по меткам для выбора томов, рассматриваемых для привязки.
`storageClassName` string	storageClassName — имя StorageClass, требуемого этой заявкой. Подробнее: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1
`volumeAttributesClassName` string	volumeAttributesClassName можно использовать для задания VolumeAttributesClass, применяемого этой заявкой. Если поле указано, драйвер CSI создаст или обновит том с атрибутами, определёнными в соответствующем VolumeAttributesClass. Это поле выполняет другую функцию, чем storageClassName, и его можно изменить после создания заявки. Пустая строка или значение nil означает, что к заявке не будет применён VolumeAttributesClass. Если заявка переходит в состояние ошибки Infeasible, это поле можно сбросить до предыдущего значения (включая nil), чтобы отменить изменение. Если ресурс, на который ссылается volumeAttributesClass, не существует, эта PersistentVolumeClaim перейдёт в состояние Pending, отражённое в поле modifyVolumeStatus, до появления такого ресурса. Подробнее: https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/
`volumeMode` string	volumeMode определяет тип тома, требуемый заявкой. Если это поле не указано в спецификации заявки, подразумевается значение Filesystem. Возможные значения перечисления: - `"Block"` означает, что том не будет отформатирован файловой системой и останется необработанным блочным устройством. - `"Filesystem"` означает, что том будет отформатирован файловой системой или уже отформатирован.
`volumeName` string	volumeName — ссылка привязки на PersistentVolume, предоставляющий том для этой заявки.

PersistentVolumeClaimStatus

PersistentVolumeClaimStatus — это текущее состояние заявки на постоянный том.

Поле	Описание
`accessModes` string array	accessModes содержит фактические режимы доступа тома, предоставленного для PVC. Подробнее: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1
`allocatedResourceStatuses` object	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` object	allocatedResources отслеживает ресурсы, выделенные для PVC, включая её ёмкость. Имена ключей соответствуют стандартному синтаксису меток Kubernetes. Допустимы следующие значения: * Ключи без префикса: - storage — ёмкость тома. * Пользовательские ресурсы должны использовать префиксы, определённые реализацией, например "example.com/my-custom-resource". Помимо указанных выше значений, ключи без префикса или с префиксом kubernetes.io считаются зарезервированными и использоваться не могут. Указанная здесь ёмкость может превышать фактическую ёмкость, если запрошено расширение тома. При расчёте квоты на хранилище используется большее значение из allocatedResources и PVC.spec.resources. Если allocatedResources не задано, для расчёта квоты используется только PVC.spec.resources. Если запрос на расширение ёмкости тома уменьшен, allocatedResources уменьшается только при отсутствии выполняющихся операций расширения и если фактическая ёмкость тома не превышает запрошенную. Контроллер, получивший обновление PVC с ранее неизвестным resourceName, должен игнорировать это обновление в рамках своей задачи. Например, контроллер, отвечающий только за изменение ёмкости тома, должен игнорировать обновления PVC, изменяющие другие допустимые ресурсы, связанные с PVC.
`capacity` object	capacity представляет фактические ресурсы базового тома.
`conditions` PersistentVolumeClaimCondition array стратегия слияния исправлений: слияние по ключу `type`	conditions — текущее условие заявки на постоянный том. Если выполняется изменение размера базового постоянного тома, условию будет присвоено значение 'Resizing'.
`currentVolumeAttributesClassName` string	currentVolumeAttributesClassName — текущее имя VolumeAttributesClass, используемого PVC. Если значение не задано, к этой PersistentVolumeClaim не применяется VolumeAttributesClass
`modifyVolumeStatus` ModifyVolumeStatus	ModifyVolumeStatus представляет объект состояния операции ControllerModifyVolume. Если значение не задано, попытка выполнения операции ModifyVolume отсутствует.
`phase` string	phase представляет текущую фазу PersistentVolumeClaim. Возможные значения перечисления: - `"Bound"` используется для привязанных PersistentVolumeClaims - `"Lost"` используется для PersistentVolumeClaims, потерявших базовый PersistentVolume. Заявка была привязана к PersistentVolume, но этот том больше не существует, и все данные на нём потеряны. - `"Pending"` используется для PersistentVolumeClaims, которые ещё не привязаны

PersistentVolumeClaimList

PersistentVolumeClaimList — это список элементов PersistentVolumeClaim.

Поле	Описание
`apiVersion` string	APIVersion определяет версионированную схему этого представления объекта. Серверы должны преобразовывать распознанные схемы в последнее внутреннее представление и могут отклонять нераспознанные значения. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`items` * PersistentVolumeClaim array	items — список заявок на постоянные тома. Подробнее: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
`kind` string	Kind — строковое значение, представляющее ресурс REST, который соответствует этому объекту. Серверы могут определять его по конечной точке, на которую клиент отправляет запросы. Изменение не допускается. В CamelCase. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ListMeta	Стандартные метаданные списка. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

ModifyVolumeStatus

ModifyVolumeStatus представляет объект состояния операции ControllerModifyVolume

Поле Описание

status *
string status — состояние операции ControllerModifyVolume. Оно может принимать следующие значения: - Pending: Pending означает, что PersistentVolumeClaim нельзя изменить из-за невыполненных требований, например отсутствия указанного VolumeAttributesClass. - InProgress: InProgress означает, что том изменяется. - Infeasible: Infeasible означает, что драйвер CSI отклонил запрос как недопустимый. Чтобы устранить ошибку, необходимо указать допустимый VolumeAttributesClass. Примечание: в будущем могут появиться новые состояния. Потребителям следует проверять неизвестные состояния и корректно обрабатывать их.

Возможные значения перечисления:
- `"InProgress"` InProgress означает, что том изменяется
- `"Infeasible"` Infeasible означает, что драйвер CSI отклонил запрос как недопустимый. Чтобы устранить ошибку, необходимо указать допустимый VolumeAttributesClass
- `"Pending"` Pending означает, что PersistentVolumeClaim нельзя изменить из-за невыполненных требований, например отсутствия указанного VolumeAttributesClass

targetVolumeAttributesClassName
string targetVolumeAttributesClassName — имя VolumeAttributesClass, с которым в настоящее время согласуется состояние PVC

Поле	Описание
`status` * string	status — состояние операции ControllerModifyVolume. Оно может принимать следующие значения: - Pending: Pending означает, что PersistentVolumeClaim нельзя изменить из-за невыполненных требований, например отсутствия указанного VolumeAttributesClass. - InProgress: InProgress означает, что том изменяется. - Infeasible: Infeasible означает, что драйвер CSI отклонил запрос как недопустимый. Чтобы устранить ошибку, необходимо указать допустимый VolumeAttributesClass. Примечание: в будущем могут появиться новые состояния. Потребителям следует проверять неизвестные состояния и корректно обрабатывать их. Возможные значения перечисления: - `"InProgress"` InProgress означает, что том изменяется - `"Infeasible"` Infeasible означает, что драйвер CSI отклонил запрос как недопустимый. Чтобы устранить ошибку, необходимо указать допустимый VolumeAttributesClass - `"Pending"` Pending означает, что PersistentVolumeClaim нельзя изменить из-за невыполненных требований, например отсутствия указанного VolumeAttributesClass
`targetVolumeAttributesClassName` string	targetVolumeAttributesClassName — имя VolumeAttributesClass, с которым в настоящее время согласуется состояние PVC

PersistentVolumeClaimCondition

PersistentVolumeClaimCondition содержит сведения о состоянии PVC

Поле	Описание
`lastProbeTime` Time	lastProbeTime — время последней проверки условия.
`lastTransitionTime` Time	lastTransitionTime — время перехода условия из одного состояния в другое.
`message` string	message — понятное пользователю сообщение с подробностями о последнем переходе.
`reason` string	reason — уникальная короткая машиночитаемая строка, указывающая причину последнего перехода условия. Значение "Resizing" означает, что выполняется изменение размера базового постоянного тома.
`status` * string	Status — состояние условия. Допустимые значения: True, False, Unknown. Подробнее: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required
`type` * string	Type — тип условия. Подробнее: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about

TypedObjectReference

TypedObjectReference содержит достаточно сведений, чтобы найти объект указанного типа

Поле	Описание
`apiGroup` string	APIGroup — группа для ресурса, на который выполняется ссылка. Если APIGroup не указан, заданный Kind должен относиться к основной группе API. Для любых других сторонних типов APIGroup является обязательным.
`kind` * string	Kind — тип ресурса, на который выполняется ссылка
`name` * string	Name — имя ресурса, на который выполняется ссылка
`namespace` string	Namespace — пространство имён ресурса, на который выполняется ссылка. Обратите внимание: если пространство имён указано, в пространстве имён целевого объекта необходим объект gateway.networking.k8s.io/ReferenceGrant, разрешающий владельцу этого пространства имён принять ссылку. Подробнее см. документацию по ReferenceGrant. (Альфа) Для использования этого поля необходимо включить feature gate CrossNamespaceVolumeDataSource.

VolumeResourceRequirements

VolumeResourceRequirements описывает требования к ресурсам хранения для тома.

Поле Описание

limits
object Limits описывает максимальный объём разрешённых вычислительных ресурсов. Подробнее: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

requests
object Requests описывает минимальный объём необходимых вычислительных ресурсов. Если Requests не указан для контейнера, по умолчанию используется Limits, если это значение задано явно, иначе — значение, определяемое реализацией. Requests не может превышать Limits. Подробнее: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

Поле	Описание
`limits` object	Limits описывает максимальный объём разрешённых вычислительных ресурсов. Подробнее: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
`requests` object	Requests описывает минимальный объём необходимых вычислительных ресурсов. Если Requests не указан для контейнера, по умолчанию используется Limits, если это значение задано явно, иначе — значение, определяемое реализацией. Requests не может превышать Limits. Подробнее: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

© 2026 The Kubernetes Authors | Documentation Distributed under CC BY 4.0
Copyright © 2026 The Linux Foundation ®. All rights reserved.
https://kubernetes.io/docs/reference/kubernetes-api/core/persistent-volume-claim-v1/