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

При выборе номера версии используйте следующие рекомендации:

  • изменение патч-версии (например, c 0.0.1 на 0.0.2) — исправление дефекта;
  • изменение минорной версии (например, c 0.0.1 на 0.1.0) — добавление новой функции;
  • изменение мажорной версии (например, c 0.0.1 на 1.0.0) — добавление функции, которая кардинально меняет возможности модуля; масштабное изменение интерфейса или завершение крупного этапа работы.

Перед номером версии в теге git и контейнере registry всегда добавляется буква “v”. Например: v0.0.73, v1.0.0.

Каналы обновлений

Каналы обновлений позволяют публиковать версию модуля не для всех пользователей сразу, а для некоторой части пользователей. Вы сами определяете степень стабильности версии модуля, на какой максимальный канал обновлений ее можно опубликовать.

Важно понимать, что выбор канала обновлений не определяет, насколько стабилен сам модуль. Каналы являются инструментом доставки и определяют степень стабильности конкретного релиза.

При публикации новой версии модуля на канал обновлений сначала используйте канал обновлений Alpha. Далее, если работа версии модуля не вызывает нареканий, публикуйте версию модуля последовательно на другие каналы обновлений, с учетом их стабильности: Alpha → Beta → Early Access → Stable → Rock Solid. Если версия модуля требует исправления ошибок, то публикация такой версии должна быть остановлена. После выпуска версии с исправлениями, необходимо повторить этап публикации версии начиная с канала обновлений Alpha.

Жизненный цикл модуля

За время своего жизненного цикла модуль может проходить следующие стадии:

  • Experimental — экспериментальная версия. Функциональность модуля может сильно измениться. Совместимость с будущими версиями не гарантируется.
  • Preview — предварительная версия. Функциональность модуля может измениться, но основные возможности сохранятся. Совместимость с будущими версиями обеспечивается, но может потребовать дополнительных действий по миграции.
  • General Availability (GA) — общедоступная версия. Модуль готов к использованию в production-средах.
  • Deprecated — модуль устарел, развитие модуля и его поддержка прекращены.

Как понять, насколько модуль стабилен?

В зависимости от стадии жизненного цикла модуля и канала обновлений, из которого была установлена версия модуля, общая стабильность может быть определена в соответствии со следующей таблицей:

Стадия жизненного цикла Каналы обновлений
Alpha Beta Early Access Stable Rock Solid
Experimental Эксперименты Эксперименты Эксперименты Опытная эксплуатация Опытная эксплуатация
Preview Эксперименты Ограниченная эксплуатация Ограниченная эксплуатация Промышленная эксплуатация Промышленная эксплуатация
General Availability Эксперименты Ограниченная эксплуатация Ограниченная эксплуатация Промышленная эксплуатация Промышленная эксплуатация в ответственных системах
Deprecated Отказ от использования Отказ от использования Отказ от использования Отказ от использования Отказ от использования
  • Эксперименты — Проверка функциональности, эксперименты и тестирование;
  • Опытная эксплуатация — Проверка функциональности, эксперименты и тестирование. Точечное использование опытными пользователями в окружениях, приравненных к продуктивным.
  • Ограниченная эксплуатация — Окружения разработки, пилотные проекты, малозначимые продуктивные окружения;
  • Промышленная эксплуатация — Продуктивные окружения и приравненные к ним;
  • Промышленная эксплуатация в ответственных системах — Критично важные продуктивные окружения и приравненные к ним;
  • Отказ от использования — Необходимо выводить из использования.

Выводы:

  • Модуль в статусеExperimental на канале Stable рекомендовано использовать в продуктивных средах только ограниченно.
  • Модуль в статусе General Availability на канале Alpha также не рекомендуется использовать в продуктивных средах.
  • Для продуктивных сред подходят только модули, находящиеся в статусе General Availability, установленные из каналов Early Access, Stable, или Rock Solid.
  • Модули, находящиеся в статусеDeprecated, рекомендуется заменить.

Версионирование API

Модули в DKP используют кастомные ресурсы для взаимодействия с пользователями. Параметр apiVersion с версией API этих ресурсов обновляется в соответствии со следующими правилами:

  • v1alphaX — только что опубликованный API. Нужно проверить, насколько он удобен и понятен для пользователей, а также насколько корректны и логичны его настройки.
  • v1betaX — API прошел первичное тестирование. Продолжается его логическое развитие и доработка.
  • v1stableX — стабильный API. С этого момента его поля не удаляются из спецификации и правила валидации не меняются в сторону большей строгости.

Можно выпустить новую версию API v2, которая проходит те же этапы, но с префиксом v2. Важно помнить, что после выпуска версии v1stableX Kubernetes будет считать её более приоритетной, чем alpha- или beta-версии, до выпуска новой стабильной версии v2stableX. При выполнении команд kubectl apply и kubectl edit будет использоваться именно v1stableX.

Причины для выпуска новой версии:

  • изменение структуры;
  • обновление устаревших параметров.

Добавлять новые параметры можно без изменения версии.

Для автоматической конвертации параметров модуля из одной версии в другую включите в модуль соответствующие конверсии. Это может понадобиться, например, при переименовании или перемещении параметра в новой версии OpenAPI-спецификации.

При выходе новой версии CustomResourceDefinition (CRD) используйте следующие рекомендации:

  • Установите предыдущим версиям CRD параметр deprecated: true. Подробнее в документации Kubernetes.
  • Версию, в которой данные хранятся внутри etcd (storage-версия), меняйте не ранее чем через два месяца после выхода новой версии.