Версионирование модуля

Deckhouse Kubernetes Platform (DKP) используется принцип семантического версионирования для модулей.

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

• изменение патч-версии (например, 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.

Порядок публикации новой версии

Рекомендуемая последовательность публикации версии модуля в каналах обновлений:

1. Опубликуйте новую версию модуля в канале Alpha.
2. Если версия работает стабильно, последовательно публикуйте ее в следующих каналах: Beta → EarlyAccess → Stable → RockSolid.
3. При возникновении ошибок остановите публикацию и исправьте их.
4. Повторите публикацию версии, начиная с канала Alpha.

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

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

• Experimental — экспериментальная версия. Функциональность модуля может сильно измениться. Совместимость с будущими версиями не гарантируется.

  Модули на стадии Experimental по умолчанию включить нельзя. Чтобы разрешить использовать такие модули установите параметр allowExperimentalModules в true.

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

Определение стабильности модуля

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

• Эксперименты — проверка функциональности, эксперименты и тестирование.
• Опытная эксплуатация — проверка функциональности, эксперименты и тестирование. Точечное использование опытными пользователями в окружениях, приравненных к production.
• Ограниченная эксплуатация — окружения разработки, пилотные проекты, малозначимые production-окружения.
• Промышленная эксплуатация — production-окружения и приравненные к ним.
• Промышленная эксплуатация в ответственных системах — критически важные production-окружения и приравненные к ним.
• Отказ от использования — необходимо выводить из использования.

Выводы:

• Модуль на стадии Experimental на канале Stable рекомендовано использовать в production-средах только ограниченно.
• Модуль на стадии General Availability на канале Alpha также не рекомендуется использовать в production-средах.
• Для production-сред подходят только модули, находящиеся на стадии 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.

Выпуск новой версии API

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

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

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

Автоматическая конвертация API

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

Рекомендации по выпуску новых версий CRD

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

• Установите предыдущим версиям CRD параметр deprecated: true. За подробностями о работе с устаревшими версиями CRD обратитесь к документации Kubernetes.
• Не меняйте storage-версию, в которой данные хранятся внутри etcd, пока не пройдет как минимум два месяца после выхода новой версии.