Модули

Модуль представляет собой совокупность приложений и ресурсов, которые расширяют возможности Deckhouse Kubernetes Platform.

Данный раздел посвящён устройству модулей DKP. Материал поможет разобраться в их внутренней структуре, принципах разработки и отладки, а также в способах взаимодействия с другими элементами платформы.

Deckhouse Kubernetes Platform (DKP) поддерживает два типа модулей:

• Встроенные модули: Являются неотъемлемой частью DKP. Их жизненный цикл полностью синхронизирован с релизным циклом самой платформы.
• Модули из внешних источников: Разрабатываются и обновляются независимо от графика выхода релизов DKP.

Процесс создания модуля включает несколько ключевых этапов:

• Разработка: На этом этапе создаётся код модуля и формируется структура его хранения в Git-репозитории. В разделе «Структура модуля» подробно описаны все компоненты и их расположение по директориям.
• Сборка и публикация: Процесс создания артефакта модуля с его последующей загрузкой в container registry. В соответствующем разделе рассматривается, какие именно образы попадают в registry и по каким адресам они становятся доступны.
• Запуск в кластере: Этап, описывающий доставку модуля в кластер DKP. Здесь вы узнаете, как активировать модуль, настроить его параметры и проверить корректность работы, включая управление CRD и диагностику возможных ошибок.
• Управление зависимостями: Настройка совместимости модуля с конкретными версиями DKP, Kubernetes и другими критическими компонентами. Детали описаны в разделе «Зависимости модуля».

Для разработки модулей DKP вам понадобятся следующие инструменты:

git — система контроля версий;

sed — редактор потоков;

yq — CLI-утилита для обработки данных в форматах JSON, YAML и XML;

jq — CLI-утилита для обработки данных в форматах JSON, YAML и XML;

werf — (не обязательно) CLI-утилита для сборки образов. Она понадобится, если вы хотите собрать артефакты модуля локально;

crane — (не обязательно) CLI-утилита для работы с container registry. Может понадобиться при отладке.

Container registry, в котором хранятся артефакты модуля, должен поддерживать вложенную структуру репозиториев. Можно использовать такие registry, как Docker Registry v2 или Harbor.

Для глубокого понимания работы модулей DKP необходимо изучить принципы функционирования addon-operator и shell-operator. Эти компоненты лежат в основе логики управления модулями.

Ключевая концепция — хуки (hooks). Рекомендуется ознакомиться с документацией операторов, чтобы понять:

• Конфигурацию хука: что это такое и какие функции она предоставляет. Конфигурация определяет набор данных, доступных внутри хука при его выполнении.
• Биндинги (привязки): это события, которые запускают выполнение хука. Биндинги задаются в конфигурации. Хук может активироваться не только при изменениях в Kubernetes, но и по расписанию (cron) или на определённых этапах жизненного цикла модуля (например, перед запуском).
• Связь хуков и Helm values: Хуки могут сохранять данные в оперативной памяти, которые затем используются при рендеринге Helm-шаблонов. Механизм этого взаимодействия и общий цикл работы модуля подробно описаны в документации «Hooks and Helm values».

Следующая важная концепция — снапшоты (snapshots). Они позволяют реализовать эффективный цикл согласования состояния (reconciliation loop), который является более надёжной альтернативой прямой подписке на события Kubernetes. В DKP именно этот подход используется для работы всех хуков встроенных модулей.

Кроме того, хуки могут выполнять функцию экспортера метрик для Prometheus. Хук способен генерировать метрики, которые платформа DKP будет собирать и экспортировать. Рекомендуется изучить соответствующий раздел документации, посвящённый работе с метриками.

Исходный код модуля и правила его сборки должны храниться в директории, организованной по определённой структуре, напоминающей Helm-чарт, но с расширенным набором элементов. При этом наличие всех папок и файлов не является строго обязательным — включаются только те, которые необходимы для работы конкретного модуля.

Ключевые компоненты структуры модуля:

• module.yaml — обязательный файл метаданных, содержащий основную информацию о модуле.
• templates/ — каталог для Helm-шаблонов, которые формируют набор ресурсов, разворачиваемых в кластере. Если поведение объектов должно зависеть от настроек модуля, соответствующие параметры определяются в спецификации и затем используются внутри шаблонов.
• images/ — директория, где хранятся инструкции (например, Dockerfile) для сборки контейнерных образов, используемых модулем. Если модуль ссылается только на внешние (готовые) образы, эта папка не требуется.
• hooks/ — место для размещения хуков, которые реализуют логику реакции на события Kubernetes или взаимодействия с его API.
• docs/ — каталог для документации модуля. Важно: если документация отсутствует, модуль не будет отображаться в списке модулей веб-интерфейса документации кластера.
• charts/ — папка для хранения вспомогательных Helm-чартов, от которых может зависеть модуль.
• crds/ — директория для размещения спецификаций пользовательских ресурсов (Custom Resource Definitions), если модуль их создаёт.

Для быстрого старта рекомендуется использовать репозиторий-шаблон модуля, в котором уже настроена предлагаемая структура файлов и директорий.

В папке /charts находятся вспомогательные чарты Helm, которые используются при рендере шаблонов.

У Deckhouse Kubernetes Platform (DKP) существует собственная библиотека для работы с шаблонами – lib-helm. О возможностях библиотеки можно почитать в репозитории lib-helm. Чтобы положить библиотеку в модуль, загрузите tgz-архив с нужным релизом и переместите его в директорию /charts модуля.

В этой директории лежат CustomResourceDefinition (CRD), которые используются компонентами модуля. CRD обновляются каждый раз, когда запускается модуль, если есть обновления.

Подпапки в папке /crds игнорируются.

Чтобы отобразить CRD из директории /crds в документации на сайте или модуле documentation в кластере, выполните следующие шаги:

• создайте файл перевода со структурой аналогичной исходному файлу ресурса:
• оставьте только параметры description, в которых укажите текст перевода;
• используйте префикс doc-ru- в названии: например /crds/doc-ru-crd.yaml для /crds/crd.yaml.
• создайте файлы /docs/CR.md и /docs/CR.ru.md.

В папке /docs находится документация к модулю. Следующие подпапки в папке docs игнорируются при сборке документации:

• internal
• internals
• development
• dev

Следующие файлы обязательны:

• README.md и README.ru.md — описание, для чего нужен модуль, какую проблему он решает и общие архитектурные принципы.

Метаданные файла (front matter) в виде YAML-структуры должны быть во всех языковых версиях файла. Параметры, доступные для использования в метаданных:

• title — (рекомендуется) Заголовок страницы описания модуля. Пример — “Веб-консоль администратора Deckhouse”. Он же используется в навигации, если не указан параметр linkTitle.
• menuTitle — (желательно) Название модуля в меню слева на странице (sidebar). Пример — “Deckhouse Admin”. Если отсутствует, то используется название директории или репозитория, например deckhouse-admin.
• linkTitle — (опционально) Отдельный заголовок для навигации, если, например, title очень длинный. Если отсутствует, то используется параметр title.
• description — (желательно) Краткое уникальное описание содержимого страницы (до 150 символов). Не повторяет title. Служит продолжением названия и раскрывает его детальнее. Используется при генерации превью-ссылок и индексации поисковыми системами. Пример — «Модуль позволяет полностью управлять кластером Kubernetes через веб-интерфейс, имея только навыки работы мышью.»

Пример метаданных:

Следующие файлы не обязательны, но имеют предопределенное название пункта в sidebar (меню слева) и заголовок страницы:

• EXAMPLES.md и EXAMPLES.ru.md — примеры конфигурации модуля с описанием.

Метаданные файла (front matter) в виде YAML-структуры должны быть во всех языковых версиях файла. Параметры, доступные для использования в метаданных:

• title – (рекомендуется) Заголовок страницы. Пример: “Примеры”. Он же используется в навигации, если нет linkTitle.
• description – (желательно) Краткое уникальное описание содержимого страницы (до 150 символов). Не повторяет title. Служит продолжением названия и раскрывает его детальнее. Используется при генерации превью-ссылок, индексации поисковиками. Пример: “Примеры хранения секретов в нейронной сети с автоматической подстановкой в мысли при общении.”
• linkTitle – (опционально) Отдельный заголовок для навигации, если, например, title очень длинный. Если отсутствует, то используется title.

Пример метаданных:

• FAQ.md и FAQ.ru.md — часто задаваемые вопросы, касающиеся эксплуатации модуля (“Какой сценарий выбрать: А или Б?”).

Метаданные файла (front matter) в виде YAML-структуры должны быть во всех языковых версиях файла. Параметры, доступные для использования в метаданных:

• title – (рекомендуется) Заголовок страницы.
• description – (желательно) Краткое уникальное описание содержимого страницы (до 150 символов).
• linkTitle – (опционально) Отдельный заголовок для навигации, если, например, title очень длинный. Если отсутствует, то используется title.

Пример метаданных:

• ADVANCED_USAGE.md и ADVANCED_USAGE.ru.md — расширенные инструкции по использованию и отладке модуля.

Метаданные файла (front matter) в виде YAML-структуры должны быть во всех языковых версиях файла. Параметры, доступные для использования в метаданных:

• title – (рекомендуется) Заголовок страницы.
• description – (желательно) Краткое уникальное описание содержимого страницы (до 150 символов).
• linkTitle – (опционально) Отдельный заголовок для навигации, если, например, title очень длинный. Если отсутствует, то используется title.

Пример метаданных:

• CR.md и CR.ru.md — файлы для генерации ресурсов из папки /crds/. Добавьте эти файлы, если необходима генерация ресурсов из папки /crds модуля.

Пример метаданных:

CONFIGURATION.md и CONFIGURATION.ru.md — файлы для рендеринга OpenAPI-спецификаций из файлов /openapi/config-values.yaml и /openapi/doc--config-values.yaml. Добавьте эти файлы, если необходима генерация таких спецификаций.

Пример метаданных:

Все изображения, PDF-файлы и другие медиафайлы нужно хранить в директории /docs или ее подкаталогах (например, /docs/images/). Все ссылки на файлы должны быть относительными.

Для каждого языка нужен файл с соответствующим суффиксом. Например, image1.jpg и image1.ru.jpg. Используйте ссылки:

• [image1](image1.jpg) в англоязычном документе;
• [image1](image1.ru.jpg) в русскоязычном документе.

В директории /hooks/batch находятся хуки модуля. Хук — это исполняемый файл, выполняемый при реакции на событие. Хуки используются модулем также для динамического взаимодействия с API Kubernetes. Например, они могут быть использованы для обработки событий, связанных с созданием или удалением объектов в кластере.

Познакомьтесь с концепцией хуков, прежде чем начать разрабатывать свой собственный хук. Для ускорения разработки хуков можно воспользоваться Go-библиотекой от команды Deckhouse.

Требования к работе хука:

• При запуске с аргументами hook config должна выводиться конфигурация хуков в формате JSON.
• При запуске с аргументами hook list должен выводиться список всех хуков с их порядковым номером.
• При запуске с аргументами hook run 0 должна выполняться логика хука под номером 0.

Файлы хуков должны иметь права на выполнение. Добавьте их командой chmod +x <путь до файла с хуком>.

В директории /images находятся инструкции по сборке образов контейнеров модуля. На первом уровне находятся директории для файлов, используемых при создании образа контейнера, на втором — контекст для сборки.

Существует два способа описания образа контейнера:

1. Dockerfile — файл, который содержит команды для быстрой сборки образов. Если необходимо собрать приложение из исходного кода, поместите его рядом с Dockerfile и включите его в образ с помощью команды COPY.
2. Файл werf.inc.yaml, который является аналогом секции описания образа из werf.yaml.

Имя образа совпадает с именем директории для этого модуля, записанным в нотации camelCase с маленькой буквы. Например, директории /images/echo-server соответствует имя образа echoServer.

Собранные образы имеют content-based теги, которые можно использовать в сборке других образов. Чтобы использовать content-based теги образов, подключите библиотеку lib-helm. Вы также можете воспользоваться другими функциями библиотеки helm_lib Deckhouse Kubernetes Platform.

Пример использования content-based тега образа в Helm-чарте:

В директории /openapi/conversions находятся файлы конверсий параметров модуля и их тесты.

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

Каждая конверсия возможна только между двумя смежными версиями (например с первой версии на вторую). Конверсий может быть несколько, и цепочка конверсий должна последовательно покрывать все версии спецификации параметров модуля, без “пропусков”.

Файл конверсии — это YAML-файл с именем v.yaml или v.yml, где — версия конверсии. Его структура:

Описание действий, указываемое в секции description файла конверсий, должно быть понятным и содержать информацию о том, какие параметры и в каком порядке нужно изменить в спецификации параметров модуля, чтобы перейти к новой версии.

Пример файла конверсии параметров модуля v2.yaml, где в версии 2 удаляется параметр .auth.password:

Для написания тестов конверсий можно использовать функцию conversion.TestConvert, которой нужно передать:

• путь до исходного файла конфигурации (версия до конвертации);
• путь до ожидаемого файла конфигурации (версия после конвертации).

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

Чтобы схема была представлена в документации на сайте или в модуле documentation в кластере, создайте:

• файл doc-ru-config-values.yaml со структурой, аналогичной структуре файла config-values.yaml. В файле doc-ru-config-values.yaml оставьте только переведенные параметры description;
• файлы /docs/CONFIGURATION.md и /docs/CONFIGURATION.ru.md — это включит показ данных из файлов /openapi/config-values.yaml и /openapi/doc-ru-config-values.yaml.

Пример схемы /openapi/config-values.yaml с одним настраиваемым параметром nodeSelector:

Пример файла /openapi/doc-ru-config-values.yaml для русскоязычного перевода схемы:

При разработке модуля для Deckhouse Kubernetes Platform вы можете использовать расширение OpenAPI x-deckhouse-validations для описания сложных правил валидации параметров модуля на языке CEL (Common Expression Language).

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

• Валидации можно размещать как на корневом уровне, так и внутри любого свойства (в том числе внутри объектов, массивов и additionalProperties).
• В выражениях доступны все параметры текущего уровня через переменную self.
• Валидация работает рекурсивно: все вложенные объекты, массивы и карты также могут содержать свои x-deckhouse-validations.
• Поддерживаются скалярные типы, массивы, объекты и карты (additionalProperties).
• В случае множественных ошибок валидации пользователю будут показаны все сообщения из соответствующих правил.

Ниже представлены примеры описаний сложных правил валидации на языке CEL:

• Проверка попадания значения параметра в диапазон:

• Проверка наличия ключа:

• Проверка, что хотя бы один из двух списков не пуст:

• Проверка значения по регулярному выражению:

Валидации скалярных значений и массивов имеют следующие особенности:

• Если свойство — скаляр (например, число или строка), то в CEL-выражении self будет этим значением.
• Если свойство — массив, то self будет массивом, и можно использовать методы .size(), .all(), .exists() и т.д.

Пример для массива:

Для объектов с additionalProperties (map) можно валидировать ключи и значения через методы .all(key, ...), .exists(key, ...) и т.д.

Пример:

Необходим для проверки исходных данных при рендере шаблонов без использования дополнительных функций Helm chart. Ближайший аналог — schema-файлы из Helm.

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

В директории /templates находятся шаблоны Helm.

• Для доступа к настройкам модуля в шаблонах используйте путь .Values.<имяМодуля>, а для глобальных настроек .Values.global. Имя модуля конвертируется в нотации camelCase.
• Для упрощения работы с шаблонами используйте lib-helm – это набор дополнительных функций, которые облегчают работу с глобальными и модульными значениями.
• Доступы в registry из ресурса ModuleSource доступны по пути .Values.<имяМодуля>.registry.dockercfg.
• Чтобы использовать эти функции для пула образов в контроллерах, создайте секрет и добавьте его в соответствующий параметр: "imagePullSecrets": [{"name":"registry-creds"}].

Модуль может иметь параметры, с помощью которых может менять свое поведение. Параметры модуля и схема их валидации описываются в OpenAPI-схемах в директории /openapi.

Настройки лежат в двух файлах: config-values.yaml и values.yaml.

Исключите файлы из Helm-релиза с помощью .helmignore. В случае модулей DKP директории /crds, /images, /hooks, /openapi обязательно добавляйте в .helmignore, чтобы избежать превышения лимита размера Helm-релиза в 1 Мб.

Файл для чарта, аналогичный Chart.yaml из Helm. Должен содержать, как минимум, параметр name с именем модуля и параметр version с версией. Вы можете не создавать данный файл, Deckhouse создаст его автоматически.

Пример:

Файл module.yaml в корне папки модуля содержит метаданные модуля.

Файл может отсутствовать, но рекомендуется его заполнить. Большинство метаданных будут доступны в объекте Module) и успешной синхронизации.

Параметры, которые можно использовать в module.yaml:

• namespace — Строка. Пространство имён, где будут развернуты компоненты модуля.
• subsystems — Массив строк. Список подсистем, к которым относится модуль.
• accessibility — Объект. Настройки доступности модуля.
• editions — Объект. Настройки работы модуля в редакциях Deckhouse.
• available — Булевый. Определяет доступность модуля в редакции Deckhouse.
• enabledInBundles — Массив строк. Список наборов модулей (bundles), в которых модуль должен быть включен по умолчанию.
• descriptions — Объект. Произвольное текстовое описание назначения модуля.
• en — Строка. Текстовое описание на английском языке.
• ru — Строка. Текстовое описание на русском языке.
• disable — Объект. Параметры, связанные с поведением при отключении модуля.
• confirmation — Булевый. Требовать подтверждение при отключении модуля.
• message — Строка. Сообщение с информацией о том, что произойдёт при отключении модуля.

Если для отключения модуля требуется подтверждение (параметр confirmation установлен в true), то отключение будет возможно только в случае, если на соответствующем объекте ModuleConfig установлена аннотация modules.deckhouse.io/allow-disabling=true. Если такой аннотации нет, при попытке отключить модуль будет выведено предупреждение, включающее сообщение из параметра message.

• name — Строка, обязательный параметр. Имя модуля в Kebab Case. Например, echo-server.
• exclusiveGroup — Строка. Если несколько модулей принадлежат к одной и той же exclusiveGroup, то только один из них может быть активен в системе одновременно. Это предотвращает конфликты между модулями, выполняющими схожие или несовместимые задачи.
• requirements — Объект. Зависимости модуля — условия, при которых Deckhouse Kubernetes Platform (DKP) может запустить модуль.
• deckhouse — Строка. Зависимость от версии Deckhouse Kubernetes Platform.
• kubernetes — Строка. Зависимость от версии Kubernetes.
• modules — Объект. Зависимость от версий других модулей.
• stage — Строка. Стадия жизненного цикла модуля. Допустимые значения: Experimental, Preview, General Availability, Deprecated. Если stage установлен в Experimental, модуль нельзя включить по умолчанию. Чтобы разрешить использовать такие модули установите параметр allowExperimentalModules в true.
• tags — Массив строк. Дополнительные теги модуля. Теги преобразуются в лейблы объекта Module по шаблону module.deckhouse.io/="".

Например, если указать tags: ["test", "myTag"], то объект Module получит лейблы module.deckhouse.io/test="" и module.deckhouse.io/myTag="".

• weight — Число. Вес модуля. Влияет на порядок запуска модулей: модули с меньшим значением weight запускаются раньше. По умолчанию — 900.

На порядок запуска также влияют зависимости модуля.

Пример описания метаданных модуля hello-world:

Параметр accessibility позволяет задать редакции DKP и наборы модулей (bundles), в которых будет доступен модуль, а также определить, будет ли он включаться по умолчанию.

Описание параметров:

• accessibility — Объект. Корневой блок настройки доступности модуля.
• editions — Объект. Набор ключей с названиями редакций. Для каждой редакции можно задать собственные настройки доступности.
• _default — Объект. Настройка по умолчанию, если отсутствует конфигурация для конкретной редакции.
• available — Булевый. Определяет, доступен ли модуль в рамках указанной редакции.
• enabledInBundles — Массив строк. Наборы модулей, в которых модуль будет включён по умолчанию. Поддерживаемые наборы модулей (состав каждого из наборов доступен на этой странице):
• Default — рекомендованный набор модулей для работы кластера. Включает средства мониторинга, контроля авторизации, организации работы сети и другие необходимые компоненты.
• Managed — набор модулей для кластеров, управляемых облачными провайдерами (например, Google Kubernetes Engine).
• Minimal — минимальный набор, включающий только текущий модуль.

Обратите внимание, что в этот набор не входят базовые модули (например, модуль работы с CNI). Без включения базовых модулей Deckhouse может работать только в уже развернутом кластере.

• Блоки с названиями редакций. Позволяют задать поведение модуля в указанных редакциях. Возможные значения: be, ce, ee, se, se-plus.

Схема ниже показывает логику определения доступности и включения модуля в зависимости от настроек:

В следующем примере конфигурации модуль будет недоступен во всех редакциях, кроме DKP Enterprise Edition. В DKP Enterprise Edition модуль будет включён по умолчанию в наборе модулей Managed.

В следующем примере конфигурации модуль будет доступен во всех редакциях DKP. В наборах модулей Managed и Default модуль будет включён по умолчанию.

В следующем примере модуль будет доступен во всех редакциях DKP. Модуль будет включён в наборах модулей Default и Managed во всех редакциях, кроме DKP Basic Edition и DKP Community Edition.

Deckhouse Kubernetes Platform (DKP) использует container registry для загрузки и обновления модуля. В container registry хранятся артефакты модуля. Артефакты модуля появляются в результате сборки модуля, после чего их можно загрузить (опубликовать) в registry.

В результате сборки модуля формируются три типа артефактов, которые затем загружаются в container registry:

1. Образы контейнеров приложений

• Правила сборки и исходный код находятся в директории с именем приложения внутри папки images.
• Готовые образы указываются в Helm-шаблонах и запускаются в кластере.
• Тегирование образов выполняется на основе содержимого (content-based теги).
• Для использования образов в шаблонах необходимо подключить библиотеку lib-helm.

2. Образ модуля

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

3. Релиз

• Артефакт, представляющий собой версию модуля. На основе данных релиза DKP принимает решение об обновлении модуля в кластере.
• Релизы имеют два типа тегов:

Тег семантического версионирования (аналогично образу модуля);

Тег, соответствующий каналу обновлений (например, alpha, beta и т.д.).

• В шаблоне модуля предусмотрен пример workflow для GitHub Actions, автоматически создающего релиз при сборке.

Для сборки артефактов модуля и загрузки их в container registry в рамках процесса CI/CD мы предлагаем воспользоваться подготовленными GitHub Actions.

В репозитории шаблона модуля представлен пример модуля, который содержит простой workflow для GitHub Actions и использует GitHub Packages (ghcr.io) в качестве container registry. В представленном примере workflow используется следующая логика:

• Сборка артефактов модуля при изменениях в рамках PR и при слиянии изменений в ветку main.
• Сборка артефактов модуля из тегов с использованием продуктивного container registry.
• Публикация модуля в container registry GitHub Packages в выбранный канал обновлений из тега.

Артефакты модуля будут загружаться по адресу ghcr.io//modules/, который будет являться источником модулей.

Выполните следующие настройки в свойствах вашего проекта на GitHub, чтобы workflow модуля работал корректно:

• Откройте страницу Settings -> Actions -> General.
• Установите параметр Read and write permissions в разделе Workflow permissions.

Вы также можете модифицировать workflow, предусмотреть использование своего container registry и более сложный процесс сборки и публикации (например, с использованием отдельных container registry для разработки и промышленной эксплуатации).

Артефакты модуля также можно собрать локально с помощью werf (это может потребоваться, например, при отладке).

Вы также можете самостоятельно сделать сборку артефактов модуля и публикацию для вашей системы CI/CD по аналогии с workflow для GitHub Actions, приведенном в шаблоне модуля, но это может потребовать глубокого понимания процессов сборки и публикации модуля. Обратитесь к сообществу при появлении вопросов и затруднений.

Общий сценарий работы с workflow, приведенным в шаблоне модуля:

1. Опубликуйте изменения в коде модуля в ветке проекта на GitHub. Это запустит сборку артефактов модуля и их публикацию в container registry.
2. Создайте новый релиз модуля или установите тег в формате семантического версионирования на нужном коммите.
3. Перейдите в раздел Actions репозитория модуля на GitHub и слева, в списке workflow, выберите Deploy.
4. В правой части страницы нажмите на выпадающий список Run workflow, выберите необходимый канал обновлений и укажите нужный тег в поле ввода тега. Нажмите кнопку Run workflow.
5. После успешного выполнения workflow в container registry появится новая версия модуля. Опубликованную версию модуля можно использовать в кластере.

Чтобы запустить модуль в кластере, необходимо выполнить следующие шаги:

• Определить источник модулей (ресурс ModuleSource).
• (не обязательно) Определить политику обновления модуля (ресурс ModuleUpdatePolicy).
• Включить модуль в кластере (ресурс ModuleConfig).

Deckhouse Kubernetes Platform (DKP) может работать со следующими видами модулей:

• Встроенные модули. Входят в состав DKP. Релизный цикл привязан к релизному циклу DKP.
• Модули из источника модулей. Релизный цикл таких модулей не привязан к релизному циклу DKP.

Чтобы указать, откуда кластеру получать информацию о модулях, создайте ресурс ModuleSource. В нем задаются адрес хранилища образов контейнеров, из которого DKP будет загружать модули, параметры аутентификации и другие настройки доступа.

Пример ресурса ModuleSource:

После создания ресурса ModuleSource DKP начнет выполнять периодическую (раз в три минуты) синхронизацию данных с источником модулей (загружать информацию о модулях, доступны в источнике).

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

Пример вывода в случае успешной синхронизации:

В случае ошибок синхронизации в столбце MSG будет указано общее описание ошибки. Пример:

Подробную информацию об ошибках можно получить в поле pullError в статусе ресурса ModuleSource.

Пример получения подробной информации об ошибках из источника модулей example:

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

Пример получения списка модулей, доступных из источника модулей example:

Полный список модулей, доступных из всех созданных в кластере источников модулей, можно получить с помощью следующей команды:

После создания ресурса ModuleSource и успешной синхронизации, в кластере должны начать появляться модули — ресурсы Module (DKP создает их автоматически, создавать их не нужно). Посмотреть список модулей можно с помощью следующей команды:

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

Чтобы получить дополнительную информацию о модуле, выполните следующую команду:

Пример вывода:

В Module указаны доступные источники из которых его можно скачать (в примере он только один).

Далее нужно включить модуль. Для этого нужно создать ModuleConfig с названием модуля.

За включение модуля отвечает параметр enabled ModuleConfig. Если модуль доступен из нескольких источников (ресурс ModuleSource), необходимый источник можно указать в параметре source.

Политику обновления (имя ModuleUpdatePolicy) можно указать в параметре updatePolicy. Политику обновления можно не указывать, — в этом случае она будет унаследована от параметров обновления Deckhouse Kubernetes Platform (releaseChannel и upd ate ModuleConfig deckhouse).

Пример ModuleConfig для включения модуля module-one из источника example:

Убедитесь, что вы указываете необходимые параметры конфигурации в ModuleConfig согласно документации модуля.

После включения модуля, он должен перейти в фазу скачивания (Downloading):

После успешного скачивания модуль перейдет в фазу установки (Installing):

Если модуль успешно установился, то он перейдет в фазу готовности (Ready):

Пример объекта Module в кластере, когда модуль успешно установился:

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

При возникновении каких либо ошибок, модуль перейдет в фазу ошибки (Error):

Если у включенного модуля есть несколько доступных источников, и в его ModuleConfig явно не выбран источник модуля, модуль перейдет в фазу конфликта (Conflict):

Чтобы разрешить конфликт, укажите источник модуля (имя ModuleSource) явно в ModuleConfig.

После скачивания модуля в кластере появятся релизы модуля — объекты ModuleRelease.

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

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

Если релиз модуля находится в статусе Superseded, это значит что релиз модуля устарел, и есть более новый релиз, который его заменил.

Если необходимо развернуть модуль из другого источника модулей, выполните следующие шаги:

1. Создайте новый ресурс ModuleSource.
2. Укажите его в поле source в ModuleConfig.
3. Проверьте, что новые релизы модуля (объекты ModuleRelease) создаются из нового источника модулей в соответствии с политикой обновления:

Политика обновления модуля — это правила, по которым DKP обновляет модули в кластере. Она определяется ресурсом ModuleUpdatePolicy, в котором можно настроить:

• режим обновления модуля (автоматический, ручной, обновления отключены);
• канал стабильности, используемый при обновлении;
• окна автоматического обновления, в пределах которых разрешено обновление модуля.

Создавать ресурс ModuleUpdatePolicy не обязательно. Если политика обновления для модуля не определена (отсутствует соответствующий ресурс ModuleUpdatePolicy), то настройки обновления соответствуют настройкам обновления самого DKP (параметр update модуля deckhouse).

Пример ресурса ModuleUpdatePolicy, политика обновления которого разрешает автоматическое обновление модуля по понедельникам и средам с 13:30 до 14:00 UTC:

Политика обновления указывается в поле updatePolicy в ModuleConfig.

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

Модуль должен быть в списке.

Пример вывода:

Вывод показывает, что модуль module-one доступен для включения.

Если модуля нет в списке, то проверьте что определен источник модулей и модуль есть в списке в источнике модулей. Также проверьте политику обновления модуля (если она определена). Если политика обновления модуля не определена, то она соответствует политике обновления DKP (параметр releaseChannel и секция update параметров модуля deckhouse).

Включить модуль можно аналогично встроенному модулю DKP любым из следующих способов:

• Выполнить следующую команду (укажите имя модуля):

• Создать ресурс ModuleConfig с параметром enabled: true и настройками модуля.

Пример ModuleConfig, для включения и настройки модуля module-one в кластере:

Если при включении модуля в кластере возникли ошибки, то получить информацию о них можно следующими способами:

• Посмотреть журнал Deckhouse:

• Посмотреть объект Module подробнее:

Посмотреть объект ModuleConfig модуля:

Пример вывода информации об ошибке модуля module-one:

• Посмотреть объект ModuleSource:

Пример вывода если у источника модуля есть проблемы со скачиванием модуля:

По аналогии с DeckhouseRelease (ресурсом релиза DKP) у модулей есть аналогичный ресурс — ModuleRelease. DKP создает ModuleRelease исходя из того, что хранится в container registry. При поиске проблем с модулем проверьте также доступные в кластере ModuleRelease:

Пример вывода:

В примере вывода показан ModuleRelease, когда режим обновления (параметр update.mode ModuleUpdatePolicy установлен в Manual. В этом случае необходимо вручную подтвердить установку новой версии модуля, установив на ModuleRelease аннотацию modules.deckhouse.io/approved="true":

Для автоматической проверки структуры модуля и, при необходимости, отправки статистики, в сборку можно подключить Deckhouse Module Tools (DMT).

Для GitHub доступен отдельный GitHub Action для подключения DMT к модулю.

Чтобы подключить DMT, в конфигурации workflow сборки [project].github/workflows/build.yml добавьте шаг для выполнения проверки:

Переменные DMT_METRICS_URL и DMT_METRICS_TOKEN – необязательные. При их наличии DMT будет отправлять телеметрию на указанный адрес.

Если модуль находится в GitHub-группе deckhouse, значения этих переменных будут автоматически получены из настроенных секретов.

Для GitLab также доступны готовые шаблоны, которые можно подключить в .gitlab-ci.yml для автоматической настройки процессов сборки и проверки корректности:

• Setup: Шаблон конфигурации для настройки.
• Build: Шаблон конфигурации для процесса сборки.

1. В файле .gitlab-ci.yml вашего проекта добавьте ссылки на шаблоны:

Пример добавления ссылок расположен в GitLab.

2.После подключения шаблонов, в той же конфигурации .gitlab-ci.yml добавьте шаг для выполнения проверки:

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

Зависимости — это набор условий (требований), которые должны выполняться, чтобы Deckhouse Kubernetes Platform (DKP) мог запустить модуль.

DKP поддерживает следующие зависимости для модуля:

• зависимость от версии Deckhouse Kubernetes Platform;
• зависимость от версии Kubernetes;
• зависимость от версии других модулей.

Эта зависимость определяет минимальную или максимальную версию DKP, с которой совместим модуль.

Пример настройки зависимости модуля от версии DKP 1.61 и выше в файле module.yaml:

Зависимость проверяется в следующих случаях:

1. При установке или обновлении модуля. Если версия DKP не соответствует требованиям, указанным в зависимостях модуля релиза, его установка или обновление не будут выполнены.

Пример ресурса ModuleRelease, когда версия DKP не соответствует требованиям модуля:

Выводимая информация:

2. При обновлении DKP. Проверяется, соответствует ли новая версия DKP зависимостям установленных и активных модулей. Если хотя бы один модуль несовместим с новой версией, обновление DKP не выполнится.

Пример ресурса DeckhouseRelease, когда версия DKP не соответствует требованиям модуля:

Выводимая информация:

3. При первичном анализе модулей. Проверяются текущая версия DKP и зависимости уже установленных модулей. Если обнаружено несоответствие, модуль будет отключён.

Эта зависимость определяет минимальную или максимальную версию Kubernetes, с которой совместим модуль.

Пример настройки зависимости от Kubernetes 1.28 и выше в файле module.yaml:

Зависимость проверяется в следующих случаях:

1. При установке или обновлении модуля. Если версия Kubernetes не соответствует требованиям, указанным в зависимостях модуля релиза, установка или обновление не будут выполнены.

Пример ресурса ModuleRelease, когда версия Kubernetes не соответствует требованиям модуля:

Выводимая информация:

2. При обновлении версии Kubernetes. Проверяются зависимости активных модулей, и если хотя бы один модуль несовместим с новой версией Kubernetes, изменение версии не будет принято.

Пример вывода при несовместимости модуля с новой версией Kubernetes:

Выводимая информация:

3. При первичном анализе модулей. Если версия Kubernetes не соответствует зависимостям уже установленных модулей, DKP отключит такие модули.

4. При обновлении DKP. Проверяется значение версии Kubernetes, установленной по умолчанию для DKP, если оно несовместимо с активными модулями, обновление DKP не будет выполнено.

Пример ресурса DeckhouseRelease, когда версия Kubernetes не соответствует требованиям модуля:

Выводимая информация:

Зависимости от версии других модулей описывают условия включения, обновления и выключения модуля. Модуль в Deckhouse Kubernetes Platform может иметь обязательные и необязательные зависимости от версий других модулей.

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

Если необходимо указать, чтобы какой-то модуль был просто включен, не важно какой версии, то можно использовать следующий синтаксис (на примере модуля user-authn):

Пример настройки зависимости от трех модулей:

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

Чтобы указать, что зависимость является необязательной, добавьте !optional к строке ограничения версии модуля, от которого может зависеть целевой модуль:

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

1. Если в кластере не включен test, prometheus может быть включен.

Пример: test выключен + для prometheus задано необязательное требование test: ">v0.22.1 !optional" → prometheus будет включен, требование пропускается.

2. Если в кластере уже включен test, включение prometheus с requirements возможно только, если в requirements указаны требования, которым соответствует текущая версия test.

Пример: в кластере включен test версии v0.21.1 + для prometheus задано необязательное требование test: ">v0.22.1 !optional" → установка/включение prometheus завершится ошибкой о несоответствии зависимости (текущая версия test не соответствует requirements).

3. Если test будет выключен в кластере, prometheus останется включенным.

Пример: в кластере включен test + для prometheus задано необязательное требование test: ">v0.22.1 !optional" → выключение test пройдет успешно, prometheus выключен не будет.

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

1. prometheus может быть обновлен, даже если в кластере нет модуля test.

Пример: test выключен + для prometheus задано необязательное требование test: ">v0.22.1 !optional" → prometheus будет обновлен.

2. Обновление для prometheus будет заблокировано, пока в кластере не обновится test указанной в requirements версии.

Пример: test включен + для prometheus задано необязательное требование test: ">v0.22.1 !optional" → prometheus не будет обновлен, пока не обновится test.

Если модуль prometheus включен, невозможно включить test, версия которого не соответствует выражению, указанному в requirements для prometheus.

Пример: prometheus включен + для prometheus задано необязательное требование test: ">v0.22.1 !optional" → попытка включения test v0.21.1 завершится ошибкой о несоответствии зависимости (версия test v0.21.1 не соответствует условию в requirements для prometheus).

Если prometheus и test включены в кластере, обновление test возможно только на версию которая соответствует требованиям, указанным в requirements для prometheus.

Пример: Модули prometheus и test включены в кластере + для prometheus задано необязательное требование test: "=v0.22.1 !optional" + попытка обновления test до версии 0.23.1 → test не будет обновлен, т.к. требуемая версия не соответствует requirements для prometheus.

В 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 — экспериментальная версия. Функциональность модуля может сильно измениться. Совместимость с будущими версиями не гарантируется.

• 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 рекомендуется заменить.

Модули в 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. За подробностями о работе с устаревшими версиями CRD обратитесь к документации Kubernetes.
• Не меняйте storage-версию, в которой данные хранятся внутри etcd, пока не пройдет как минимум два месяца после выхода новой версии.

1. Установите необходимые утилиты.

• git
• sed
• yq

3. Укажите имя модуля в файле module.yaml.

В примере будет использоваться имя модуля helloworld, но вы можете выбрать свое, заменив helloworld в командах и в названии вашего репозитория.

Выполните следующую команду, чтобы указать имя модуля в файле module.yaml, либо отредактируйте его вручную:

4. Склонируйте исходный код чарта hello-world во временную директорию.

5. Скопируйте шаблоны чарта в директорию templates модуля, предварительно очистив ее.

6. Замените в шаблонах чарта путь .Values на .Values.helloworld.

7. Добавьте OpenAPI-схему настроек модуля.

Параметры модуля указываются в OpenAPI-схеме в директории openapi. Выполните следующую команду, чтобы преобразовать JSON-схему параметров чарта в OpenAPI-схему модуля:

8. Опишите правило сборки образа контейнера приложения.

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

9. Замените образ в манифесте Deployment на хелпер библиотеки Deckhouse Kubernetes Platform. Это позволит использовать актуальный content-based-тэг образа.

10. Удалите хуки модуля, CRD и временные файлы.

Пример не использует хуки и CustomResourceDefinition. Выполните следующие команды, чтобы очистить папки hooks и crds:

11. Настройте CI/CD.

В шаблоне проекта в директории .github находятся готовые файлы workflow GitHub Actions, которые реализуют простую схему сборки и публикации модуля с использованием registry GitHub Packages (ghcr.io). Артефакты модуля будут загружаться по адресу ghcr.io//modules/, который будет являться источником модулей. Внесите изменения в файлы workflow, если вам не подходит предложенный вариант.

Выполните следующие настройки в свойствах вашего проекта на GitHub, чтобы workflow модуля работал корректно:

• Откройте страницу Settings -> Actions -> General.
• Установите параметр Read and write permissions в разделе Workflow permissions.

12. Зафиксируйте изменения в репозитории (укажите адрес Git-репозитория модуля).

13. Убедитесь, что сборка модуля выполнилась успешно.

Перейдите в раздел Actions репозитория модуля и слева, в списке workflow, выберите Build. Workflow, запущенный после того, как вы выполнили команду git push на предыдущем шаге, должен выполниться успешно.

Пример:

Пример публикации версии v0.0.1 модуля на канале обновлений Alpha:

1. Создайте новый релиз модуля v0.0.1 в репозитории GitHub или установите тег v0.0.1.
2. Перейдите в раздел Actions репозитория модуля и слева, в списке workflow, выберите Deploy.
3. В правой части страницы нажмите на выпадающий список Run workflow и выберите alpha. Укажите тег v0.0.1 в поле ввода тега. Нажмите кнопку Run workflow.

4. Убедитесь, что workflow публикации модуля выполнился успешно.

Модуль стал доступным для подключения в кластере Deckhouse Kubernetes Platform.

Пример подключения модуля helloworld в кластере Deckhouse Kubernetes Platform.

1. Создайте токен доступа в репозитории GitHub с правами для работы с GitHub Packages.

2. Сгенерируйте строку аутентификации для доступа к GitHub Packages container registry в формате dockerconfigjson, указав имя пользователя (или организации) GitHub и токен доступа:

3. Создайте в кластере ресурс ModuleSource (укажите адрес container registry и строку аутентификации).

Синхронизация данных после создания ресурса может занять несколько секунд.

4. Посмотрите список доступных модулей:

5. Создайте ресурс ModuleUpdatePolicy, определяющий политику обновления модуля.

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

6. Создайте ModuleConfig, где укажите источник модуля (параметр source), политику обновления (параметр updatePolicy) и установите параметр enabled в true:

7. Проверьте ModuleSource (в статусе не должно содержаться ошибок и должны быть перечислены доступные модули):

8. Убедитесь, что были созданы новые объекты ModuleRelease для модуля:

Пример вывода:

9. В случае успешной установки релизов дождитесь перезапуска пода Deckhouse Kubernetes Platform.

Через некоторое время объекты модуля появятся в кластере.

Если при запуске модуля возникли ошибки, посмотрите журнал DKP:

или проверьте состояние очереди DKP:

Если в кластере существует ModuleUpdatePolicy версии v1alpha1, то необходимо выполнить следующие шаги по миграции на версию v1alpha2:

Если в кластере в каком-либо ModuleUpdatePolicy версии v1alpha1 определен moduleReleaseSelector, то для всех модулей, которые подходят под этот селектор, в системе мониторинга будут гореть алерты ModuleHasDeprecatedUpdatePolicy. В этом случае выполните следующие шаги по миграции на версию v1alpha2 ModuleUpdatePolicy:

• Укажите политику обновления для соответствующих модулей в параметре spec.updatePolicy ModuleConfig.
• Выполните следующую команду, указав необходимый ModuleUpdatePolicy:

При разработке модулей может возникнуть необходимость загрузить и развернуть модуль в обход каналов обновления. Для этого используется ресурс ModulePullOverride.

Пример ModulePullOverride:

Также для целей разработки может использоваться режим обслуживания модуля (maintenance mode). В этом режиме Deckhouse отключает управление ресурсами модуля и не применяет изменения автоматически. Этот режим не предназначен для эксплуатации в production-кластерах.

Пример:

Требования к параметрам ресурса:

• Имя модуля (metadata.name) должно соответствовать имени модуля в ModuleSource (.status.modules.[].name).
• Тег образа контейнера (spec.imageTag) может быть любым. Например, pr333, my-branch.

Необязательный параметр spec.scanInterval устанавливает интервал времени для проверки образов в registry. По умолчанию задан интервал в 15 секунд. Для принудительного обновления можно изменить интервал, либо установить на ModulePullOverride аннотацию renew="".

Необязательный параметр spec.rollback — если установить этот параметр в true, это восстановит развернутый модуль до предыдущего состояния после удаления ModulePullOverride.

Результат применения ModulePullOverride можно увидеть в сообщении (колонка MESSAGE) при получении информации об ModulePullOverride. Значение Ready означает применение параметров ModulePullOverride. Любое другое значение означает конфликт.

Пример отсутствия конфликтов при применении ModulePullOverride:

Требования к модулю:

• Модуль должен существовать, иначе сообщение у ModulePullOverride будет The module not found.

Пример:

• Модуль не должен быть встроенным модулем Deckhouse, иначе сообщение у ModulePullOverride будет The module is embedded.

Пример:

• Модуль должен быть включен, иначе сообщение у ModulePullOverride будет The module disabled.

Пример:

• Модуль должен иметь источник, иначе сообщение у ModulePullOverride будет The module does not have an active source.

Пример:

• Источник модуля должен существовать, иначе сообщение у ModulePullOverride будет The source not found.

Пример:

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

Чтобы назначить редакции Deckhouse, в которых должен быть доступен модуль, а также наборы модулей (bundles), в составе которых модуль должен быть включен по умолчанию, используйте поле accessibility в файле module.yaml:

В данном примере модуль будет доступен в редакции ee (DKP Enterprise Edition) и может быть включен через объект ModuleConfig, а также будет по умолчанию включен в составе набора модулей Default.

После создания ModulePullOverride, соответствующий модуль не будет учитывать ModuleUpdatePolicy, а также не будет загружать и создавать объекты ModuleRelease. Модуль будет загружаться при каждом изменении параметра imageDigest, после чего будет применяться в кластере. В статусе ModuleSource модуль получит признак overridden: true, который указывает на то, что используется ModulePullOverride, а не ModuleUpdatePolicy. Также, соответствующий объект Module будет иметь в своем статусе поле IsOverridden и версию модуля из imageTag.

Пример:

После удаления ModulePullOverride модуль продолжит работать. Но, если для модуля существует ModuleUpdatePolicy, то загрузятся новые релизы модуля (ModuleRelease), которые заменят текущую “версию разработчика”.

1. В ModuleSource присутствуют два модуля echo и hello-world. Для них определена политика обновления, они загружаются и устанавливаются в DKP:

2. Включите модуль и создайте ModulePullOverride для модуля echo:

После создания ModulePullOverride, для модуля будет использоваться тег образа registry.example.com/deckhouse/modules/echo:main-patch-03354 (ms:spec.registry.repo/mpo:metadata.name:mpo:spec.imageTag).

3. Данные ModulePullOverride будут меняться при каждом обновлении модуля:

где:

• imageDigest — уникальный идентификатор образа контейнера, который был загружен.
• lastUpdated — время последней загрузки образа.

4. При этом ModuleSource приобретет вид:

1. Установка модуля. При включении модуля (enable module ) в кластер автоматически загружается и разворачивается актуальная версия модуля из выбранного канала стабильности. Это может быть, например, ModuleRelease v1.0.0. Загружается последняя доступная версия, старые версии не устанавливаются.

2. Отключение модуля. При отключении модуля (disable module ):

• Модуль перестаёт получать новые версии.
• Текущая версия остаётся в кластере в состоянии Deployed.

3. Поведение при повторном включении.

Если модуль включён в течение 72 часов:

• Используется та же версия, которая была задеплоена ранее (ModuleRelease v1.0.0).
• Проверяются новые релизы.
• При их наличии они загружаются (например, v1.1.0, v1.1.1).
• Далее модуль обновляется в соответствии с обычными правилами обновления (Update). Подробнее.

Если модуль включён позже 72 часов:

• Старая версия удаляется (delete ModuleRelease v1.0.0).
• При включении модуля повторно, загружается последняя актуальная версия (например, v1.1.1).
• Начинается тот же цикл, что и при первоначальном включении (см. шаг 1).

4. Поведение выключенного модуля. Если модуль отключён, то релизы для него не загружаются. Задеплоенная версия модуля (последняя включённая) удаляется через 72 часа, если модуль так и не был повторно включён.

Механизм from-to позволяет пропускать пошаговые обновления модуля. Если текущая установленная версия модуля (в статусе Deployed) попадает в диапазон from-to, DKP пропускает промежуточные релизы и устанавливает последнюю доступную версию в пределах to.

Чтобы включить механизм, задайте правила перехода в конфигурации модуля (module.yaml). Пример:

Условия применения from-to:

• Версия релиза назначения — правило читается из релиза, на который нужно перейти — значение to должно совпадать с версией самого этого релиза (constrained release).
• Текущая установленная версия модуля (Deployed) должна быть не ниже значения from. Если текущая версия ниже from, переход по правилу не выполняется — обновление идёт по порядку.
• Если одновременно подходят несколько релизов, выбирается вариант с наибольшим to (правила могут находиться в разных объектах ModuleRelease одного модуля).
• Если ни один релиз не подходит под эти условия, обновление выполняется как обычно — без пропуска промежуточных версий.

Проверить доступные релизы (ModuleRelease) можно с помощью команды:

Пример вывода, если текущая версия модуля — 0.3.33, а в module.yaml задано правило from: "0.3" → to: "0.7":

В этом примере вывода текущая установленная версия — 0.3.33 (в статусе Deployed). По правилу from: 0.3 → 0.7 к установке выбирается последняя доступная версия в пределах 0.7 — p-o-test-v0.7.25 (в статусе Pending). После подтверждения версии 0.4.1, 0.5.27 и 0.6.11 становятся в статусе Skipped, а p-o-test-v0.7.25 в статусе Deployed.

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

Пример вывода после подтверждения:

Нужна ли аннотация зависит от политики обновления модуля. Подробнее — Политика обновления модуля.

Пример 1. Релиз назначения содержит правило, и его версия совпадает с to — переход выполняется.

В этом примере правило from-to прописано в самом релизе назначения, и значение to равно версии этого релиза. Текущая установленная версия (Deployed) не ниже значения from, значит переход возможен. Как только релиз появляется в кластере, DKP готовит обновление. Если по политике обновления требуется подтверждение — пометьте релиз аннотацией. После подтверждения промежуточные релизы будут пропущены, релиз назначения станет Deployed:

Также если текущая версия ещё выше значения from, переход также выполняется:

Пример 2. Текущая версия ниже from — переход не выполняется.

Если текущая установленная версия меньше значения from, правило не применяется. Обновление идёт по порядку (без пропуска):

Пример 3. Несовпадение to с версией релиза с правилом — переход не выполняется.

Переход возможен только в релиз, где to равно версии этого релиза. Если правило описано в другом релизе (например, to: "1.74" лежит в релизе v1.75.25), оно не сработает — обновление пойдёт по порядку.

После сборки модуля его артефакты должны быть загружены в хранилище образов контейнеров по пути, который является источником для загрузки и запуска модулей в DKP. Путь, по которому загружаются артефакты модулей в хранилище образов, указывается в ресурсе ModuleSource.

Пример иерархии образов контейнеров после загрузки артефактов модулей module-1 и modules-2 в registry:

Пример:

Пример: 

В примере в модуле module-1 присутствуют два образа модуля и два образа контейнеров приложений.

Пример:

Модули могут включать дополнительные образы (например, базы данных уязвимостей или другие вспомогательные данные) путем добавления файла extra_images.json. Этот файл указывает дополнительные образы, которые необходимо вручную загрузить в реестр и которые отделены от основных образов модуля.

Для просмотра конфигурации дополнительных образов:

Пример файла extra_images.json для базы уязвимостей neuvector:

Важные замечания:

• Дополнительные образы должны быть вручную загружены в реестр модулей по пути extra/.
• Используйте команду d8 mirror pull --only-extra-images для загрузки только дополнительных образов.
• Дополнительные образы хранятся в реестре как <имя-модуля>/extra/<имя-образа>.

Пример: 

 примере в хранилище образов два релиза и используются два канала обновлений: alpha и beta.

Пример: