Kubernetes v1.37: Storage Version Migration типово увімкнена

Я радий, що міграція версії зберігання (SVM) досягла загальної доступності (GA) у Kubernetes v1.37!

Після кількох випусків роботи та тестування вбудований API StorageVersionMigration (storagemigration.k8s.io/v1) та контролер панелі управління тепер повністю стабільні та типово увімкнені у всіх кластерах Kubernetes v1.37.

Проблема застарілих версій зберігання

У Kubernetes збережені API-ресурси записуються з використанням певної версії зберігання (представлення схеми). Те, як Kubernetes взаємодіє з обʼєктним сховищем, принципово вимагає зміни ресурсу, щоб гарантувати використання останньої версії зберігання для всіх ресурсів. Це створює проблеми, коли ви хочете змінити версію зберігання ресурсу.

Один із прикладів сценарію, коли ви можете захотіти змінити версію зберігання ресурсу, — це коли ви просуваєте CRD, щоб відмовитися від старішої версії API (наприклад, v1alpha1) на користь новішої (залишивши лише v1beta1 та v1). Відмова від старішої версії API є проблемою, поки в сховищі все ще залишаються ресурси, збережені зі старою альфа-версією.

Щоб уникнути проблем, ви призначаєте v1 як нову версію зберігання; але само по собі цього недостатньо. Поки нові записи зберігаються як v1, будь-який наявний ресурс може залишатися збереженим як v1alpha1 або v1beta1 у сховищі. Ви не можете безпечно видалити v1alpha1 з .status.storedVersions CRD або припинити підтримку обслуговування, доки кожен окремий ресурс у сховищі не буде переписаний так, щоб не серіалізуватися та не зберігатися з альфа-версією.

Іншим доречним прикладом є шифрування у стані спокою та, повʼязана з ним, ротація ключів. Коли ви налаштовуєте шифрування у стані спокою або виконуєте ротацію ключів шифрування, наявні ресурси у сховищі залишаються незашифрованими (або зашифрованими старими ключами), доки вони не будуть активно переписані через API-сервер Kubernetes.

Історично адміністратори кластерів та автори CRD мали покладатися на ручні скрипти kubectl get / kubectl replace або розгортати зовнішній компонент kube-storage-version-migrator, щоб примусово виконувати перезапис. Ці підходи часто були марудними, схильними до помилок та важкими для моніторингу.

Як працює міграція версії зберігання

Запустити міграцію версії зберігання так само просто, як створити декларативний обʼєкт StorageVersionMigration. Вбудований контролер StorageVersionMigrator у панелі управління Kubernetes відстежує ці обʼєкти та автоматично переносить наявні ресурси до типової версії зберігання для цього API.

Приклад: міграція API власного ресурсу

Припустимо, ви оновили CustomResourceDefinition (crontabs.example.com), щоб використовувати v1 як версію зберігання. Щоб мігрувати всі наявні збережені ресурси зі старіших версій, створіть StorageVersionMigration:

apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: crontabs-migration
spec:
  resource:
    group: example.com
    resource: crontabs

Застосуйте маніфест за допомогою kubectl:

kubectl apply -f crontabs-migration.yaml

Моніторинг та перевірка міграцій

Контролер StorageVersionMigrator оновлює status обʼєкта StorageVersionMigration у міру виконання міграції. Ви можете переглянути стан міграції за допомогою kubectl:

kubectl get storageversionmigration.storagemigration.k8s.io/crontabs-migration -o yaml

Успішна міграція повідомить про умову Succeeded зі значенням True:

status:
  conditions:
    - type: Running
      status: "False"
      lastUpdateTime: "2026-08-02T10:05:00Z"
      reason: StorageVersionMigrationInProgress
    - type: Succeeded
      status: "True"
      lastUpdateTime: "2026-08-02T10:05:00Z"
      reason: StorageVersionMigrationSucceeded

Після успішної міграції ви можете бути впевнені, що всі екземпляри ресурсу у сховищі збережені у поточній версії зберігання. Для CRD версія зберігання має бути оновлена в .status.storedVersions CRD так, щоб містити лише бажану версію. Якщо .status.storedVersions не оновлено після успішної міграції, це означає, що CRD було оновлено під час міграції. У цьому випадку міграцію слід повторити, щоб безпечно визнати старішу версію зберігання застарілою.

Включення міграцій у ваші маніфести CRD

Оскільки StorageVersionMigration — це стандартний декларативний API Kubernetes, автори CRD можуть постачати або запускати міграції безпосередньо разом з оновленнями CRD. Наприклад, ви можете включити міграцію в той самий маніфест, що й оновлений CustomResourceDefinition:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.example.com
spec:
  group: example.com
  # Оновлений список версій, де v1 має storage: true
  ...
---
apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: crontabs-migration
spec:
  resource:
    group: example.com
    resource: crontabs

Що далі?

• Дізнайтеся більше про концепції, що стоять за версіями зберігання.
• Прочитайте покроковий посібник: міграція обʼєктів Kubernetes з використанням міграції версії зберігання.

SIG API Machinery буде рада почути ваш відгук, коли ви впроваджуватимете вбудовану міграцію версії зберігання у своїх кластерах. Звертайтеся до нас на каналі #sig-api-machinery у Slack або беріть участь у наших обговореннях у спільноті!

• ←Попередня
• Наступна→