Постійні томи

Цей документ описує постійні томи (persistent volumes) в Kubernetes. Рекомендується вже мати уявлення про томи, StorageClasses та VolumeAttributesClasses.

Вступ

Управління зберіганням — це задача, що є відокремленою від управління обчислювальними ресурсами. Підсистема PersistentVolume надає API для користувачів та адміністраторів, яке абстрагує деталі того, як забезпечується зберігання від того, як воно використовується. Для цього ми вводимо два нових ресурси API: PersistentVolume та PersistentVolumeClaim.

PersistentVolume (PV) — це частина системи зберігання в кластері, яка була надана адміністратором або динамічно надана за допомогою Storage Classes. Це ресурс в кластері, так само як вузол — це ресурс кластера. PV — це втулки томів, так само як Volumes, але вони мають життєвий цикл, незалежний від будь-якого окремого Podʼа, який використовує PV. Цей обʼєкт API охоплює деталі реалізації зберігання, такі як NFS, iSCSI або система зберігання, специфічна для постачальника хмарних послуг.

PersistentVolumeClaim (PVC) — це запит на зберігання від користувача. Він схожий на Pod. Podʼи використовують ресурси вузла, а PVC використовують ресурси PV. Podʼи можуть запитувати конкретні рівні ресурсів (CPU та памʼять). Claims можуть запитувати конкретний розмір та режими доступу (наприклад, їх можна монтувати в режимі ReadWriteOnce, ReadOnlyMany, ReadWriteMany або ReadWriteOncePod, див. AccessModes).

Хоча PersistentVolumeClaims дозволяють користувачам споживати абстрактні ресурси зберігання, часто користувачам потрібні PersistentVolumes з різними властивостями, такими як продуктивність для різних завдань. Адміністратори кластера повинні мати можливість надавати різноманітні PersistentVolumes, які відрізняються не тільки розміром і режимами доступу, але й іншими характеристиками, не розголошуючи користувачам деталей того, як реалізовані ці томи. Для цих потреб існує ресурс StorageClass.

Дивіться докладний огляд із робочими прикладами.

Життєвий цикл тому та запиту

PV (PersistentVolume) — це ресурс в кластері. PVC (PersistentVolumeClaim) — це запити на ці ресурси та також діють як перевірки запитів ресурсів. Взаємодія між PV та PVC слідує такому життєвому циклу:

Виділення

Існує два способи надання PV: статичне чи динамічне.

Статичне

Адміністратор кластера створює кілька PV. Вони містять деталі реального зберігання, яке доступне для використання користувачами кластера. Вони існують в API Kubernetes і доступні для споживання.

Динамічне

Коли жоден зі статичних PV, які створив адміністратор, не відповідає PersistentVolumeClaim користувача, кластер може спробувати динамічно надати том спеціально для PVC. Це надання ґрунтується на StorageClasses: PVC повинен запитати клас зберігання, а адміністратор повинен створити та налаштувати цей клас для динамічного надання. Заявки, які запитують клас "", ефективно вимикають динамічне надання для себе.

Для активації динамічного надання сховища на основі класу зберігання адміністратор кластера повинен увімкнути контролер допуску DefaultStorageClass на API-сервері. Це можна зробити, наприклад, забезпечивши, що DefaultStorageClass знаходиться серед значень, розділених комами, у впорядкованому списку для прапорця --enable-admission-plugins компонента API-сервера. Для отримання додаткової інформації щодо прапорців командного рядка API-сервера перевірте документацію kube-apiserver.

Звʼязування

Користувач створює, або, у разі динамічного надання, вже створив, PersistentVolumeClaim із конкретним обсягом запитаного сховища та з певними режимами доступу. Цикл керування в панелі управління бачить нові PVC, знаходить відповідний PV (якщо це можливо), і звʼязує їх один з одним. Якщо PV був динамічно наданий для нового PVC, цикл завжди буде привʼязувати цей PV до PVC. В іншому випадку користувач завжди отримає принаймні те, про що вони просили, але том може бути більшим, ніж те, що було запитано. Як тільки звʼязування виконане, привʼязки PersistentVolumeClaim є ексклюзивними, незалежно від того, як вони були звʼязані. Привʼязка PVC до PV — це відображення один до одного, використовуючи ClaimRef, яке є двонапрямним звʼязуванням між PersistentVolume і PersistentVolumeClaim.

Заявки залишатимуться непривʼязаними нескінченно довго, якщо відповідного тому не існує. Заявки будуть привʼязані, в міру того як стають доступні відповідні томи. Наприклад, кластер, який має багато PV розміром 50Gi, не буде відповідати PVC розміром 100Gi. PVC може бути привʼязаний, коли до кластера додається PV розміром 100Gi.

Використання

Podʼи використовують заявки як томи. Кластер перевіряє заявку, щоб знайти привʼязаний том і монтує цей том для Podʼа. Для томів, які підтримують кілька режимів доступу, користувач вказує бажаний режим при використанні своєї заявки як тому в Podʼі.

Якщо у користувача є заявка, і ця заявка привʼязана, привʼязаний PV належить користувачеві стільки, скільки він йому потрібний. Користувачі планують Podʼи та отримують доступ до своїх заявлених PV, включивши розділ persistentVolumeClaim в блок volumes Podʼа. Див. Заявки як томи для отримання докладнішої інформації щодо цього.

Захист обʼєкта зберігання, що використовується

Мета функції захисту обʼєктів зберігання — це забезпечити, що PersistentVolumeClaims (PVC), які активно використовуються Podʼом, та PersistentVolume (PV), які привʼязані до PVC, не видаляються з системи, оскільки це може призвести до втрати даних.

Якщо користувач видаляє PVC, що активно використовується Podʼом, PVC не видаляється негайно. Видалення PVC відкладається до тих пір, поки PVC більше активно не використовується жодними Podʼами. Також, якщо адміністратор видаляє PV, який привʼязаний до PVC, PV не видаляється негайно. Видалення PV відкладається до тих пір, поки PV більше не є привʼязаним до PVC.

Ви можете перевірити, що PVC захищено, коли статус PVC — «Terminating», а список Finalizers включає kubernetes.io/pvc-protection:

kubectl describe pvc hostpath
Name:          hostpath
Namespace:     default
StorageClass:  example-hostpath
Status:        Terminating
Volume:
Labels:        <none>
Annotations:   volume.beta.kubernetes.io/storage-class=example-hostpath
               volume.beta.kubernetes.io/storage-provisioner=example.com/hostpath
Finalizers:    [kubernetes.io/pvc-protection]
...

Ви можете перевірити, що PV захищено, коли статус PV — «Terminating», а список Finalizers також включає kubernetes.io/pv-protection:

kubectl describe pv task-pv-volume
Name:            task-pv-volume
Labels:          type=local
Annotations:     <none>
Finalizers:      [kubernetes.io/pv-protection]
StorageClass:    standard
Status:          Terminating
Claim:
Reclaim Policy:  Delete
Access Modes:    RWO
Capacity:        1Gi
Message:
Source:
    Type:          HostPath (bare host directory volume)
    Path:          /tmp/data
    HostPathType:
Events:            <none>

Повторне використання

Коли користувач закінчує використання свого тому, він може видалити обʼєкти PVC з API, що дозволяє відновлення ресурсу. Політика відновлення для PersistentVolume повідомляє кластеру, що робити з томом після звільнення заявки на нього. Наразі томи можуть бути Retained, Recycled, або Deleted

Retain

Політика повторного використання Retain дозволяє ручне повторне використання ресурсу. Коли видаляється PersistentVolumeClaim, PersistentVolume все ще існує, і том вважається "звільненим". Але він ще не доступний для іншої заявки через те, що дані попередньої заявки залишаються на томі. Адміністратор може вручну відновити том виконавши наступні кроки.

1. Видаліть PersistentVolume. Повʼязаний актив в зовнішній інфраструктурі все ще існує після видалення PV.
2. Вручну очистіть дані на повʼязаному активі відповідно.
3. Вручну видаліть повʼязаний актив.

Якщо ви хочете використовувати той самий актив, створіть новий PersistentVolume з тим же описом активу.

Delete

Для втулків томів, які підтримують політику відновлення Delete, видалення видаляє як обʼєкт PersistentVolume з Kubernetes, так і повʼязаний актив зовнішньої інфраструктури. Томи, які були динамічно виділені, успадковують політику пвоторного використання їх StorageClass, яка типово встановлена в Delete. Адміністратор повинен налаштувати StorageClass відповідно до очікувань користувачів; в іншому випадку PV повинен бути відредагований або виправлений після створення. Див. Змінення політики повторного використання PersistentVolume.

Recycle

Якщо підтримується відповідний втулок томів, політика повторного використання Recycle виконує базове очищення (rm -rf /thevolume/*) тому та знову робить його доступним для нової заявки.

Однак адміністратор може налаштувати власний шаблон Podʼа для повторного використання тому за допомогою аргументів командного рядка контролера Kubernetes, як описано в довідці. Власний шаблон Podʼа повторного використання тому повинен містити специфікацію volumes, як показано у прикладі нижче:

apiVersion: v1
kind: Pod
metadata:
  name: pv-recycler
  namespace: default
spec:
  restartPolicy: Never
  volumes:
  - name: vol
    hostPath:
      path: /any/path/it/will/be/replaced
  containers:
  - name: pv-recycler
    image: "registry.k8s.io/busybox"
    command: ["/bin/sh", "-c", "test -e /scrub && rm -rf /scrub/..?* /scrub/.[!.]* /scrub/*  && test -z \"$(ls -A /scrub)\" || exit 1"]
    volumeMounts:
    - name: vol
      mountPath: /scrub

Проте конкретний шлях, вказаний у власному шаблоні Podʼа для повторного використання тому, в частині volumes, замінюється конкретним шляхом тому, який використовується.

Завершувач захисту від видалення PersistentVolume

До PersistentVolume можна додавати завершувачі, щоб забезпечити, що PersistentVolume з політикою відновлення Delete буде видалено лише після видалення сховища, яке він забезпечував.

Завершувач external-provisioner.volume.kubernetes.io/finalizer (введений у v1.31) додається як до динамічно, так і до статично виділених томів CSI.

Завершувач kubernetes.io/pv-controller (введений у v1.31) додається до динамічно виділених томів внутрішнього втулка і пропускається для статично виділених томів внутрішнього втулка.

Ось приклад динамічно виділеного тому внутрішнього втулка:

kubectl describe pv pvc-74a498d6-3929-47e8-8c02-078c1ece4d78
Name:            pvc-74a498d6-3929-47e8-8c02-078c1ece4d78
Labels:          <none>
Annotations:     kubernetes.io/createdby: vsphere-volume-dynamic-provisioner
                 pv.kubernetes.io/bound-by-controller: yes
                 pv.kubernetes.io/provisioned-by: kubernetes.io/vsphere-volume
Finalizers:      [kubernetes.io/pv-protection kubernetes.io/pv-controller]
StorageClass:    vcp-sc
Status:          Bound
Claim:           default/vcp-pvc-1
Reclaim Policy:  Delete
Access Modes:    RWO
VolumeMode:      Filesystem
Capacity:        1Gi
Node Affinity:   <none>
Message:
Source:
    Type:               vSphereVolume (a Persistent Disk resource in vSphere)
    VolumePath:         [vsanDatastore] d49c4a62-166f-ce12-c464-020077ba5d46/kubernetes-dynamic-pvc-74a498d6-3929-47e8-8c02-078c1ece4d78.vmdk
    FSType:             ext4
    StoragePolicyName:  vSAN Default Storage Policy
Events:                 <none>

Завершувач external-provisioner.volume.kubernetes.io/finalizer додається для томів CSI. Наприклад:

Name:            pvc-2f0bab97-85a8-4552-8044-eb8be45cf48d
Labels:          <none>
Annotations:     pv.kubernetes.io/provisioned-by: csi.vsphere.vmware.com
Finalizers:      [kubernetes.io/pv-protection external-provisioner.volume.kubernetes.io/finalizer]
StorageClass:    fast
Status:          Bound
Claim:           demo-app/nginx-logs
Reclaim Policy:  Delete
Access Modes:    RWO
VolumeMode:      Filesystem
Capacity:        200Mi
Node Affinity:   <none>
Message:
Source:
    Type:              CSI (a Container Storage Interface (CSI) volume source)
    Driver:            csi.vsphere.vmware.com
    FSType:            ext4
    VolumeHandle:      44830fa8-79b4-406b-8b58-621ba25353fd
    ReadOnly:          false
    VolumeAttributes:      storage.kubernetes.io/csiProvisionerIdentity=1648442357185-8081-csi.vsphere.vmware.com
                           type=vSphere CNS Block Volume
Events:                <none>

Коли прапорець функції CSIMigration{provider} увімкнено для конкретного внутрішнього втулка, завершувач kubernetes.io/pv-controller замінюється завершувачем external-provisioner.volume.kubernetes.io/finalizer.

Завершувачі забезпечують, що обʼєкт PV видаляється лише після того, як том буде видалений з бекенду зберігання, якщо політика відновлення PV є Delete. Це також гарантує, що том буде видалений з бекенду зберігання незалежно від порядку видалення PV і PVC.

Резервування PersistentVolume

Панель управління може привʼязувати PersistentVolumeClaims до PersistentVolume в кластері. Однак, якщо вам потрібно, щоб PVC привʼязувався до певного PV, вам слід заздалегідь їх привʼязувати.

Вказавши PersistentVolume в PersistentVolumeClaim, ви оголошуєте привʼязку між цим конкретним PV та PVC. Якщо PersistentVolume існує і не зарезервував PersistentVolumeClaim через своє поле claimRef, тоді PersistentVolume і PersistentVolumeClaim будуть привʼязані.

Привʼязка відбувається попри деякі критерії відповідності, включаючи спорідненість вузла. Панель управління все ще перевіряє, що клас сховища, режими доступу та розмір запитаного сховища є дійсними.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: foo-pvc
  namespace: foo
spec:
  storageClassName: "" # Порожній рядок повинен бути явно встановлений, інакше буде встановлено типовий StorageClass
  volumeName: foo-pv
  ...

Цей метод не гарантує жодних привʼязок для PersistentVolume. Якщо інші PersistentVolumeClaims можуть використовувати PV, який ви вказуєте, вам слід заздалегідь резервувати цей обсяг сховища. Вкажіть відповідний PersistentVolumeClaim у поле claimRef PV, щоб інші PVC не могли привʼязатися до нього.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: foo-pv
spec:
  storageClassName: ""
  claimRef:
    name: foo-pvc
    namespace: foo
  ...

Це корисно, якщо ви хочете використовувати PersistentVolumes з політикою повторного використання Retain, включаючи випадки, коли ви повторно використовуєте наявний PV.

Розширення Persistent Volume Claims

Підтримка розширення PersistentVolumeClaims (PVCs) є типово увімкненою. Ви можете розширити наступні типи томів:

• azureFile (застарілий)
• csi
• flexVolume (застарілий)
• rbd (застарілий)
• portworxVolume (застарілий)

Ви можете розширити PVC лише в тому випадку, якщо поле allowVolumeExpansion його класу сховища має значення true.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: example-vol-default
provisioner: vendor-name.example/magicstorage
parameters:
  resturl: "http://192.168.10.100:8080"
  restuser: ""
  secretNamespace: ""
  secretName: ""
allowVolumeExpansion: true

Для запиту більшого тому для PVC відредагуйте обʼєкт PVC та вказуйте більший розмір. Це спричинює розширення тому, який стоїть за основним PersistentVolume. Новий PersistentVolume ніколи не створюється для задоволення вимоги. Замість цього, змінюється розмір поточного тому.

Розширення томів CSI

Підтримка розширення томів CSI типово увімкнена, але вона також вимагає, щоб конкретний драйвер CSI підтримував розширення тому. Зверніться до документації відповідного драйвера CSI для отримання додаткової інформації.

Зміна розміру тому, що містить файлову систему

Ви можете змінювати розмір томів, що містять файлову систему, тільки якщо файлова система є XFS, Ext3 або Ext4.

Коли том містить файлову систему, розмір файлової системи змінюється тільки тоді, коли новий Pod використовує PersistentVolumeClaim у режимі ReadWrite. Розширення файлової системи виконується при запуску нового Pod або коли Pod працює, і базова файлова система підтримує онлайн-розширення.

FlexVolumes (застарілий починаючи з Kubernetes v1.23) дозволяє змінювати розмір, якщо драйвер налаштований із можливістю RequiresFSResize встановленою в true. FlexVolume може бути змінений при перезапуску Pod.

Зміна розміру використовуваного PersistentVolumeClaim

В цьому випадку вам не потрібно видаляти та перестворювати Pod або Deployment, який використовує наявний PVC. Будь-який PVC, який знаходиться у використанні, автоматично стає доступним для свого Pod, як тільки його файлова система буде розширена. Ця функція не впливає на PVC, які не використовуються Pod або Deployment. Ви повинні створити Pod, який використовує PVC, перш ніж розширення може завершитися.

Аналогічно іншим типам томів — томи FlexVolume також можуть бути розширені в разі використання Podʼом.

Відновлення після невдалих спроб розширення томів

Якщо користувач вказав новий розмір, який надто великий для задоволення базовою системою зберігання, розширення PVC буде намагатися робити спроби його задовольнити, доки користувач або адміністратор кластера не вживе будь-яких заходів. Це може бути небажаним, і, отже, Kubernetes надає наступні методи відновлення після таких невдач.

• Вручну з доступом адміністратора кластера
• Шляхом запиту на зменшення розміру

Типи Persistent Volume

Типи PersistentVolume реалізовані у вигляді втулків. Kubernetes наразі підтримує наступні втулки:

• csi — Інтерфейс зберігання контейнерів (Container Storage Interface, CSI)
• fc — Сховище Fibre Channel (FC)
• hostPath — Том HostPath (для тестування на одному вузлі лише; НЕ ПРАЦЮВАТИМЕ в кластері з декількома вузлами; розгляньте використання тому local замість цього)
• iscsi — Сховище iSCSI (SCSI через IP)
• local — Локальні пристрої зберігання, підключені до вузлів.
• nfs — Сховище в мережевій файловій системі (NFS)

Наступні типи PersistentVolume застарілі, але все ще доступні. Якщо ви використовуєте ці типи томів, окрім flexVolume, cephfs та rbd, будь ласка, встановіть відповідні драйвери CSI.

• awsElasticBlockStore — AWS Elastic Block Store (EBS) (міграція типово увімкнена починаючи з v1.23)
• azureDisk — Azure Disk (міграція типово увімкнена починаючи з v1.23)
• azureFile — Azure File (міграція типово увімкнена починаючи з v1.24)
• cinder — Cinder (блочне сховище OpenStack) (міграція типово увімкнена починаючи з v1.21)
• flexVolume — FlexVolume (застаріло починаючи з версії v1.23, план міграції відсутній, планів припинення підтримки немає)
• gcePersistentDisk — GCE Persistent Disk (застаріло починаючи з v1.23, план міграції відсутній, планів припинення підтримки немає)
• portworxVolume — Том Portworx (міграція типово увімкнена починаючи з v1.31)
• vsphereVolume - vSphere VMDK volume (міграція типово увімкнена починаючи з v1.25)

Старші версії Kubernetes також підтримували наступні типи вбудованих PersistentVolume:

• cephfs (недоступно починаючи з версії v1.31)
• flocker — Flocker storage. (недоступно починаючи з версії v1.25)
• photonPersistentDisk — Photon controller persistent disk. (недоступно починаючи з версії v1.15)
• quobyte — Том Quobyte. (недоступно починаючи з версії v1.25)
• rbd — Rados Block Device (RBD) volume (недоступно починаючи з версії v1.31)
• scaleIO — Том ScaleIO. (недоступно починаючи з версії v1.21)
• storageos — Том StorageOS. (недоступно починаючи з версії v1.25)

Persistent Volumes

Кожен PersistentVolume (PV) містить специфікацію та статус, які являють собою характеристики та стан тому. Імʼя обʼєкта PersistentVolume повинно бути дійсним DNS імʼям субдомену.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv0003
spec:
  capacity:
    storage: 5Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Recycle
  storageClassName: slow
  mountOptions:
    - hard
    - nfsvers=4.1
  nfs:
    path: /tmp
    server: 172.17.0.2

Обсяг

Зазвичай у PV є конкретний обсяг зберігання. Він встановлюється за допомогою атрибута capacity PV, який є значенням кількості обсягу.

Наразі розмір — це єдиний ресурс, який можна встановити або вимагати. Майбутні атрибути можуть включати IOPS, пропускну здатність тощо.

Режим тому

Kubernetes підтримує два режими volumeModes для PersistentVolumes: Filesystem та Block.

volumeMode є необовʼязковим параметром API. Filesystem є типовим режимом, який використовується, коли параметр volumeMode пропущено.

Том з volumeMode: Filesystem монтується в Podʼах в каталог. Якщо том підтримується блоковим пристроєм, і пристрій порожній, Kubernetes створює файлову систему на пристрої перед його першим монтуванням.

Ви можете встановити значення volumeMode в Block, щоб використовувати том як блоковий пристрій. Такий том представляється в Podʼі як блоковий пристрій, без будь-якої файлової системи на ньому. Цей режим корисний, щоб надати Podʼу найшвидший можливий спосіб доступу до тому, без будь-якого рівня файлової системи між Podʼом і томом. З іншого боку, застосунок, який працює в Podʼі, повинен знати, як взаємодіяти з блоковим пристроєм. Дивіться Підтримка блокового тому для прикладу використання тому з volumeMode: Block в Podʼі.

Режими доступу

PersistentVolume може бути підключений до вузла будь-яким способом, який підтримує постачальник ресурсів. Як показано в таблиці нижче, постачальники матимуть різні можливості, і кожному PV присвоюється набір режимів доступу, які описують можливості саме цього PV.

Режими доступу такі:

ReadWriteOnce

том може бути підключений як для читання-запису одним вузлом. Режим доступу ReadWriteOnce все ще може дозволяти доступ до тому для кількох Podʼів, коли Podʼи працюють на тому самому вузлі. Для доступу одного Podʼа, див. ReadWriteOncePod.

ReadOnlyMany

том може бути підключений як для читання лише багатьма вузлами.

ReadWriteMany

том може бути підключений як для читання-запису багатьма вузлами.

ReadWriteOncePod

СТАН ФУНКЦІОНАЛУ: Kubernetes v1.29 [stable]

том може бути підключений як для читання-запису одним Podʼом. Використовуйте режим доступу ReadWriteOncePod, якщо ви хочете забезпечити, що тільки один Pod по всьому кластеру може читати цей PVC або писати в нього.

У командному рядку режими доступу скорочено так:

• RWO — ReadWriteOnce
• ROX — ReadOnlyMany
• RWX — ReadWriteMany
• RWOP — ReadWriteOncePod

Важливо! Том може бути підключений лише одним режимом доступу одночасно, навіть якщо він підтримує багато.

Class

PV може мати клас, який вказується, встановленням атрибуту storageClassName на імʼя StorageClass. PV певного класу може бути призначений лише до PVC, що запитує цей клас. PV без storageClassName не має класу і може бути призначений тільки до PVC, які не запитують жодного конкретного класу.

У минулому для цього використовувався атрибут volume.beta.kubernetes.io/storage-class замість storageClassName. Ця анотація все ще працює; однак вона повністю застаріє в майбутньому релізі Kubernetes.

Політика повторного використання

Поточні політики повторного використання:

• Retain — ручне відновлення
• Recycle — базова очистка (rm -rf /thevolume/*)
• Delete — видалити том

Для Kubernetes 1.31 підтримують повторнн використання лише типи томів nfs та hostPath.

Параметри монтування

Адміністратор Kubernetes може вказати додаткові параметри монтування для випадку, коли постійний том монтується на вузлі.

Наступні типи томів підтримують параметри монтування:

• azureFile
• cephfs (застаріло в v1.28)
• cinder (застаріло в v1.18)
• iscsi
• nfs
• rbd (застаріло в v1.28)
• vsphereVolume

Параметри монтування не перевіряються на валідність. Якщо параметр монтування недійсний, монтування не вдасться.

У минулому для цього використовувалася анотація volume.beta.kubernetes.io/mount-options замість атрибуту mountOptions. Ця анотація все ще працює; однак вона повністю застаріє в майбутньому релізі Kubernetes.

Node Affinity

Постійний том може вказувати властивості спорідненості вузла для визначення обмежень, які обмежують доступ до цього тому з визначених вузлів. Podʼи, які використовують PV, будуть заплановані тільки на ті вузли, які вибрані за допомогою спорідненості вузла. Щоб вказати спорідненість вузла, встановіть nodeAffinity в .spec PV. Деталі поля можна знайти у референсі API PersistentVolume.

Фаза

PersistentVolume може перебувати в одній з наступних фаз:

Available

вільний ресурс, який ще не призначений запиту

Bound

том призначено запиту

Released

запит було видалено, але повʼязане сховища ще не вилучено кластером

Failed

том не вдалося вилучити (автоматично)

Ви можете бачити імʼя PVC, призначеного для PV, використовуючи kubectl describe persistentvolume <імʼя>.

Час переходу фази

Поле .status для PersistentVolume може включати альфа-поле lastPhaseTransitionTime. Це поле фіксує відмітку часу, коли том востаннє перейшов у свою фазу. Для новостворених томів фаза встановлюється як Pending, а lastPhaseTransitionTime встановлюється на поточний час.

PersistentVolumeClaims

Кожен PVC містить специфікацію та статус, які визначають вимоги та стан заявок. Імʼя обʼєкта PersistentVolumeClaim повинно бути дійсним DNS-піддоменом.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: myclaim
spec:
  accessModes:
    - ReadWriteOnce
  volumeMode: Filesystem
  resources:
    requests:
      storage: 8Gi
  storageClassName: slow
  selector:
    matchLabels:
      release: "stable"
    matchExpressions:
      - {key: environment, operator: In, values: [dev]}

Режим доступу

Заявки використовують ті ж самі конвенції, що й томи, коли вони вимагають зберігання з конкретними режимами доступу.

Режим тому

Заявки використовують ту ж саму конвенцію, що і томи, щоб вказати споживання тому як файлової системи чи блокового пристрою.

Ресурси

Заявки, подібно до Podʼів, можуть вимагати конкретну кількість ресурсів. У цьому випадку запит стосується зберігання. До заявок застосовується та ж модель ресурсів, що і до томів.

Селектор

Заявки можуть вказати селектор міток, щоб додатково фільтрувати набір томів. До заявки може бути привʼязано лише ті томи, мітки яких відповідають селектору. Селектор може складатися з двох полів:

• matchLabels — том повинен містити мітку з таким значенням
• matchExpressions — список вимог, які визначаються за допомогою ключа, списку значень та оператора, який повʼязує ключ і значення. Допустимі оператори включають In, NotIn, Exists та DoesNotExist.

Всі вимоги як з matchLabels, так і з matchExpressions обʼєднуються за допомогою ЛОГІЧНОГО «І» — всі вони повинні бути задоволені, щоб мати збіг.

Class

Заявка може вимагати певний клас, вказавши імʼя StorageClass за допомогою атрибута storageClassName. Тільки Томи з запитаним класом, тобто ті, у яких storageClassName збігається з PVC, можуть бути привʼязані до PVC.

PVC не обоʼязково повинен вимагати клас. PVC зі своїм storageClassName, встановленим рівним "", завжди інтерпретується як PVC, який вимагає PV без класу, тобто він може бути привʼязаний лише до PV без класу (без анотації або з анотацією, встановленою рівною ""). PVC без storageClassName не зовсім те ж саме і відзначається по-іншому кластером, залежно від того, чи включений втулок доступу DefaultStorageClass.

• Якщо втулок доступу увімкнено, адміністратор може вказати типовий StorageClass. Усі PVC, у яких немає storageClassName, можуть бути привʼязані лише до PV з цим типовим StorageClass. Вказання типового StorageClass виконується, встановивши анотацію storageclass.kubernetes.io/is-default-class рівною true в обʼєкті StorageClass. Якщо адміністратор не вказав типовий StorageClass, кластер відповідає на створення PVC так, ніби втулок доступу був вимкнений. Якщо вказано більше одного типового StorageClass, для привʼязки PVC використовується остання версія типового StorageClass, коли PVC динамічно виділяється.
• Якщо втулок доступу вимкнено, немає поняття типового StorageClass. Усі PVC, у яких storageClassName встановлено рівно "", можуть бути привʼязані лише до PV, у яких storageClassName також встановлено рівно "". Однак PVC з відсутнім storageClassName можна буде оновити пізніше, коли стане доступним типовий StorageClass. Якщо PVC оновлюється, він більше не буде привʼязуватися до PV з storageClassName, також встановленим рівно "".

Дивіться ретроактивне призначення типового StorageClass для отримання докладнішої інформації.

Залежно від методу встановлення, типовий StorageClass може бути розгорнутий в кластер Kubernetes менеджером надбудов під час встановлення.

Коли PVC вказує selector, крім вимоги типового StorageClass, вимоги використовують ЛОГІЧНЕ «І»: лише PV вказаного класу і з вказаними мітками може бути привʼязаний до PVC.

У минулому анотація volume.beta.kubernetes.io/storage-class використовувалася замість атрибута storageClassName. Ця анотація все ще працює; однак вона не буде підтримуватися в майбутньому релізі Kubernetes.

Ретроактивне призначення типового StorageClass

Ви можете створювати PersistentVolumeClaim без вказівки storageClassName для нового PVC, і ви можете це робити навіть тоді, коли в кластері немає типового StorageClass. У цьому випадку новий PVC створюється так, як ви його визначили, і storageClassName цього PVC залишається невизначеним, доки не стане доступним типовий StorageClass.

Коли стає доступним типовий StorageClass, панель управління ідентифікує всі наявні PVC без storageClassName. Для PVC, у яких або встановлено порожнє значення для storageClassName, або цей ключ взагалі відсутній, панель управління оновлює ці PVC, встановлюючи storageClassName, щоб відповідати новому типовому StorageClass. Якщо у вас є наявний PVC, у якого storageClassName дорівнює "", і ви налаштовуєте типовий StorageClass, то цей PVC не буде оновлено.

Щоб продовжувати привʼязувати до PV з storageClassName, встановленим рівно "" (коли присутній типовий StorageClass), вам потрібно встановити storageClassName асоційованого PVC рівно "".

Це поведінка допомагає адміністраторам змінювати типовий StorageClass, видаляючи спочатку старий, а потім створюючи або встановлюючи інший. Це короткочасне вікно, коли немає типового StorageClass, призводить до того, що PVC без storageClassName, створені в цей час, не мають жодного типового значення, але завдяки ретроактивному призначенню типового StorageClass цей спосіб зміни типових значень є безпечним.

Заявки як томи

Podʼи отримують доступ до сховища, використовуючи заявки як томи. Заявки повинні існувати в тому ж просторі імен, що і Pod, який її використовує. Кластер знаходить заявку в просторі імен Pod і використовує її для отримання PersistentVolume, який підтримує заявку. Потім том монтується на хост та у Pod.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  containers:
    - name: myfrontend
      image: nginx
      volumeMounts:
      - mountPath: "/var/www/html"
        name: mypd
  volumes:
    - name: mypd
      persistentVolumeClaim:
        claimName: myclaim

Примітка щодо просторів імен

Привʼязки PersistentVolumes є ексклюзивними, і оскільки PersistentVolumeClaims є обʼєктами з простором імен, монтування заявк з режимами "Many" (ROX, RWX) можливе лише в межах одного простору імен.

PersistentVolumes типу hostPath

PersistentVolume типу hostPath використовує файл або каталог на вузлі для емуляції мережевого сховища. Див. приклад тому типу hostPath.

Підтримка блокового тому

Наступні втулки томів підтримують блокові томи, включаючи динамічне надання, де це можливо:

• CSI
• FC (Fibre Channel)
• iSCSI
• Локальний том
• OpenStack Cinder
• RBD (застаріло)
• RBD (Ceph Block Device; застаріло)
• VsphereVolume

PersistentVolume, що використовує блоковий том

apiVersion: v1
kind: PersistentVolume
metadata:
  name: block-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  volumeMode: Block
  persistentVolumeReclaimPolicy: Retain
  fc:
    targetWWNs: ["50060e801049cfd1"]
    lun: 0
    readOnly: false

PersistentVolumeClaim, який запитує блоковий том

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: block-pvc
spec:
  accessModes:
    - ReadWriteOnce
  volumeMode: Block
  resources:
    requests:
      storage: 10Gi

Специфікація Pod з додаванням шляху блокового пристрою в контейнер

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-block-volume
spec:
  containers:
    - name: fc-container
      image: fedora:26
      command: ["/bin/sh", "-c"]
      args: [ "tail -f /dev/null" ]
      volumeDevices:
        - name: data
          devicePath: /dev/xvda
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: block-pvc

Привʼязка блокових томів

Якщо користувач вимагає блокового тому, вказавши це за допомогою поля volumeMode у специфікації PersistentVolumeClaim, правила привʼязки трохи відрізняються від попередніх версій, які не враховували цей режим як частину специфікації. У таблиці наведено можливі комбінації, які користувач і адміністратор можуть вказати для запиту блокового пристрою. Таблиця показує, чи буде привʼязаний том чи ні, враховуючи ці комбінації: Матриця привʼязки томів для статично виділених томів:

Підтримка знімків томів та відновлення тому зі знімка

Знімки томів підтримують лише зовнішні втулки томів CSI. Докладні відомості див. у Знімках томів. Втулки томів, які входять до складу Kubernetes, є застарілими. Про застарілі втулки томів можна прочитати в ЧаПи втулків томів.

Створення PersistentVolumeClaim із знімка тому

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: restore-pvc
spec:
  storageClassName: csi-hostpath-sc
  dataSource:
    name: new-snapshot-test
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Клонування томів

Клонування томів доступне лише для втулків томів CSI.

Створення PersistentVolumeClaim із існуючого PVC

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cloned-pvc
spec:
  storageClassName: my-csi-plugin
  dataSource:
    name: existing-src-pvc-name
    kind: PersistentVolumeClaim
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Наповнювачі томів та джерела даних

Kubernetes підтримує користувацькі заповнювачі томів. Для використання користувацьких заповнювачів томів слід увімкнути функціональну можливість AnyVolumeDataSource для kube-apiserver та kube-controller-manager.

Наповнювачі томів використовують поле специфікації PVC, що називається dataSourceRef. На відміну від поля dataSource, яке може містити тільки посилання на інший PersistentVolumeClaim або на VolumeSnapshot, поле dataSourceRef може містити посилання на будь-який обʼєкт у тому ж просторі імен, за винятком основних обʼєктів, окрім PVC. Для кластерів, які мають увімкнутий feature gate, використання dataSourceRef бажано перед dataSource.

Джерела даних зі змішаними просторами імен

Kubernetes підтримує джерела даних томів зі змішаними просторами імен. Для використання джерел даних томів із змішаними просторами імен слід увімкнути функціональну можливість AnyVolumeDataSource та CrossNamespaceVolumeDataSource для kube-apiserver та kube-controller-manager. Також вам слід увімкнути CrossNamespaceVolumeDataSource для csi-provisioner.

Увімкнення CrossNamespaceVolumeDataSource дозволяє вам вказати простір імен у полі dataSourceRef.

Посилання на джерела даних

Поле dataSourceRef поводиться майже так само, як і поле dataSource. Якщо в одне задано, а інше — ні, сервер API надасть обом полям одне й те ж значення. Жодне з цих полів не можна змінити після створення, і спроба вказати різні значення для обох полів призведе до помилки перевірки правильності. Таким чином, обидва поля завжди матимуть однаковий вміст.

Є дві різниці між полем dataSourceRef і полем dataSource, які користувачам слід знати:

• Поле dataSource ігнорує неправильні значення (мовби поле було порожнім), тоді як поле dataSourceRef ніколи не ігнорує значення і призведе до помилки, якщо використано неправильне значення. Неправильними значеннями є будь-які обʼєкти основних обʼєктів (обʼєкти без apiGroup), окрім PVC.
• Поле dataSourceRef може містити обʼєкти різних типів, тоді як поле dataSource дозволяє лише PVC та VolumeSnapshot.

Коли увімкнено CrossNamespaceVolumeDataSource, є додаткові відмінності:

• Поле dataSource дозволяє лише локальні обʼєкти, тоді як поле dataSourceRef дозволяє обʼєкти у будь-яких просторах імен.
• Коли вказано простір імен, dataSource і dataSourceRef не синхронізуються.

Користувачам завжди слід використовувати dataSourceRef в кластерах, де увімкнено feature gate, і використовувати dataSource в кластерах, де він вимкнений. В будь-якому випадку необхідно дивитися на обидва поля. Дубльовані значення із трошки різними семантиками існують лише з метою забезпечення сумісності з попередніми версіями. Зокрема, старі й нові контролери можуть взаємодіяти, оскільки поля однакові.

Використання засобів наповнення томів

Засоби наповнення томів — це контролери, які можуть створювати томи з не порожнім вмістом, де вміст тому визначається за допомогою Custom Resource. Користувачі створюють наповнений том, посилаючись на Custom Resource із використанням поля dataSourceRef:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: populated-pvc
spec:
  dataSourceRef:
    name: example-name
    kind: ExampleDataSource
    apiGroup: example.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Оскільки засоби наповнення томів — це зовнішні компоненти, спроби створити PVC, який використовує їх, можуть завершитися неуспішно, якщо встановлені не всі необхідні компоненти. Зовнішні контролери повинні генерувати події на PVC для надання зворотного звʼязку щодо стану створення, включаючи попередження, якщо PVC не може бути створено через відсутність деякого компонента.

Ви можете встановити альфа-контролер перевірки джерела даних тому у вашому кластері. Цей контролер генерує події попередження на PVC у випадку, якщо не зареєстровано жодного засобу наповнення для обробки цього виду джерела даних. Коли для PVC встановлюється відповідний засіб наповнення, це відповідальність цього контролера наповнення повідомляти про події, що стосуються створення тому та проблем під час цього процесу.

Використання джерела даних томів зі змішаними просторами імен

Створіть ReferenceGrant, щоб дозволити власнику простору імен приймати посилання. Ви визначаєте наповнений том, вказавши джерело даних тому між просторами імен за допомогою поля dataSourceRef. Вам вже повинен бути дійсний ReferenceGrant у вихідному просторі імен:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-ns1-pvc
  namespace: default
spec:
  from:
  - group: ""
    kind: PersistentVolumeClaim
    namespace: ns1
  to:
  - group: snapshot.storage.k8s.io
    kind: VolumeSnapshot
    name: new-snapshot-demo

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: foo-pvc
  namespace: ns1
spec:
  storageClassName: example
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  dataSourceRef:
    apiGroup: snapshot.storage.k8s.io
    kind: VolumeSnapshot
    name: new-snapshot-demo
    namespace: default
  volumeMode: Filesystem

Написання переносимої конфігурації

Якщо ви пишете шаблони конфігурації або приклади, які повинні працювати на широкому спектрі кластерів і вам потрібне постійний сховище, рекомендується використовувати такий підхід:

• Включайте обʼєкти PersistentVolumeClaim у ваш набір конфігурації (нарізі з Deployment, ConfigMap і т. д.).
• Не включайте обєкти PersistentVolume в конфігурацію, оскільки користувач, який створює конфігурацію, може не мати прав на створення PersistentVolumes.
• Дайте користувачеві можливість надавати імʼя класу сховища при створенні шаблону.
  • Якщо користувач вказує імʼя класу сховища, вставте це значення в поле persistentVolumeClaim.storageClassName. Це призведе до збігу PVC з відповідним класом сховища, якщо в адміністратора увімкнені класи сховища.
  • Якщо користувач не вказує імʼя класу сховища, залиште поле persistentVolumeClaim.storageClassName нульовим. Це призведе до автоматичного надання користувачеві PV в кластері. Багато середовищ кластеру мають типовий клас сховища, або адміністратори можуть створити свій типовий клас сховища.
• В інструментах спостерігайте за PVC, які не привʼязуються протягом певного часу та виводьте це користувачеві, оскільки це може вказувати на те, що у кластері відсутня підтримка динамічного сховища (у цьому випадку користувач повинен створити відповідний PV) або у кластері відсутня система сховища (у цьому випадку користувач не може розгортати конфігурацію, що вимагає PVC).

Що далі

• Дізнайтеся більше про створення PersistentVolume.
• Дізнайтеся більше про створення PersistentVolumeClaim.
• Прочитайте документ з дизайну постійного сховища.

API references

Дізнайтеся більше про описані на цій сторінці API:

• PersistentVolume
• PersistentVolumeClaim