Пример создания модуля helloworld
на основе шаблона модуля и адаптации Helm-чарта hello-world.
Подготовка исходного кода модуля и сборка
- Установите необходимые утилиты.
-
Сделайте форк или скопируйте репозиторий шаблона модуля.
1git clone git@github.com:deckhouse/modules-template.git helloworld \ 2 && cd helloworld
-
Укажите имя модуля в файле
module.yaml
.В примере будет использоваться имя модуля
helloworld
, но вы можете выбрать свое, заменивhelloworld
в командах и в названии вашего репозитория.Обратите внимание, что в некоторых местах в примере имя модуля может быть записано в разных форматах — kebab-case или camelCase. Если вы используете свое имя модуля, то учитывайте изменение формата имени модуля в приводимых командах.
Выполните следующую команду, чтобы указать имя модуля в файле
module.yaml
, либо отредактируйте его вручную:1sed -i -e 's/^name:.*$/name: helloworld/' module.yaml
-
Склонируйте исходный код чарта hello-world во временную директорию.
1git clone https://github.com/giantswarm/hello-world-app .tmp-chart
-
Скопируйте шаблоны чарта в директорию
templates
модуля, предварительно очистив ее.1rm -rf templates/* 2cp -fR .tmp-chart/helm/hello-world/templates/* templates/ 3cp .tmp-chart/helm/hello-world/values.yaml values.yaml
-
Замените в шаблонах чарта путь
.Values
на.Values.helloworld
.Это архитектурная особенность addon-operator, ей необходимо следовать для обращения к values модуля.
1sed -i -e 's/.Values/.Values.helloworld/g' $(find templates/ -type f)
-
Добавьте OpenAPI-схему настроек модуля.
Параметры модуля указываются в OpenAPI-схеме в директории openapi. Выполните следующую команду, чтобы преобразовать JSON-схему параметров чарта в OpenAPI-схему модуля:
1jq 'walk( 2 if type == "object" and .type == "object" and (keys | length) == 1 3 then . + {additionalProperties: true} 4 else . 5 end 6)' .tmp-chart/helm/hello-world/values.schema.json > openapi/config-values.yaml
-
Опишите правило сборки образа контейнера приложения.
Правила сборки образов контейнеров приложений должны находиться в подкаталоге директории images модуля. Выполните следующую команду, чтобы создать директорию образа приложения и Dockerfile с правилами сборки образа.
1rm -rf images/* 2mkdir images/helloworld 3echo "FROM quay.io/giantswarm/helloworld:0.2.0" > images/helloworld/Dockerfile
-
Замените образ в манифесте Deployment на хелпер библиотеки Deckhouse Kubernetes Platform. Это позволит использовать актуальный content-based-тэг образа.
1sed -Ei 's/image\:(.*)/image: {{ include "helm_lib_module_image" (list . "helloworld") }}/g' templates/deployment.yaml
-
Удалите хуки модуля, CRD и временные файлы.
Пример не использует хуки и CustomResourceDefinition. Выполните следующие команды, чтобы очистить папки
hooks
иcrds
:1rm -rf hooks/ 2rm -rf crds/ 3rm -rf .tmp-chart
-
Настройте CI/CD.
В шаблоне проекта в директории
.github
находятся готовые файлы workflow GitHub Actions, которые реализуют простую схему сборки и публикации модуля с использованием registry GitHub Packages (ghcr.io). Артефакты модуля будут загружаться по адресуghcr.io/<OWNER>/modules/
, который будет являться источником модулей. Внесите изменения в файлы workflow, если вам не подходит предложенный вариант.Выполните следующие настройки в свойствах вашего проекта на GitHub, чтобы workflow модуля работал корректно:
- Откройте страницу Settings -> Actions -> General.
- Установите параметр Read and write permissions в разделе Workflow permissions.
-
Зафиксируйте изменения в репозитории (укажите адрес Git-репозитория модуля).
1git add . 2git commit -m "Initial Commit" 3git push --set-upstream origin <GIT_REPO_URL>
-
Убедитесь, что сборка модуля выполнилась успешно.
Перейдите в раздел Actions репозитория модуля и слева, в списке workflow, выберите Build. Workflow, запущенный после того, как вы выполнили команду
git push
на предыдущем шаге, должен выполниться успешно.Пример:
Публикация модуля на канале обновлений
Пример публикации версии v0.0.1
модуля на канале обновлений Alpha:
-
Создайте новый релиз модуля
v0.0.1
в репозитории GitHub или установите тегv0.0.1
. -
Перейдите в раздел Actions репозитория модуля и слева, в списке workflow, выберите Deploy.
-
В правой части страницы нажмите на выпадающий список Run workflow и выберите
alpha
. Укажите тегv0.0.1
в поле ввода тега. Нажмите кнопку Run workflow. -
Убедитесь, что workflow публикации модуля выполнился успешно.
Модуль стал доступным для подключения в кластере Deckhouse Kubernetes Platform.
Подключение модуля в кластере
Пример подключения модуля helloworld
в кластере Deckhouse Kubernetes Platform.
- Создайте токен доступа в репозитории GitHub с правами для работы с GitHub Packages.
-
Сгенерируйте строку аутентификации для доступа к GitHub Packages container registry в формате dockerconfigjson, указав имя пользователя (или организации) GitHub и токен доступа:
1base64 -w0 <<EOF 2{ 3 "auths": { 4 "ghcr.io": { 5 "auth": "$(echo -n '<OWNER>:<TOKEN>' | base64 -w0)" 6 } 7 } 8} 9EOF
-
Создайте в кластере ресурс ModuleSource (укажите адрес container registry и строку аутентификации).
1kubectl apply -f - <<EOF 2apiVersion: deckhouse.io/v1alpha1 3kind: ModuleSource 4metadata: 5 name: ghcr 6spec: 7 registry: 8 # Укажите имя пользователя (или организации) GitHub. Например: ghcr.io/octocat/modules 9 repo: ghcr.io/<!OWNER>/modules 10 # Строка аутентификации для доступа к GitHub Packages из предыдущего шага. 11 dockerCfg: <!REGISTRY_CREDENTIALS> 12EOF
Синхронизация данных после создания ресурса может занять несколько секунд.
-
Посмотрите список доступных модулей:
1$ kubectl get module 2NAME WEIGHT SOURCE PHASE ENABLED READY 3... 4helloworld Available False False 5...
-
Создайте ресурс ModuleUpdatePolicy, определяющий политику обновления модуля.
Выполните следующую команду, чтобы создать политику обновления с каналом обновления Alpha и режимом обновления Auto:
1kubectl apply -f - <<EOF 2apiVersion: deckhouse.io/v1alpha2 3kind: ModuleUpdatePolicy 4metadata: 5 name: helloworld-policy 6spec: 7 releaseChannel: Alpha 8 update: 9 mode: Auto 10EOF
-
Создайте ModuleConfig, где укажите источник модуля (параметр
source
), политику обновления (параметрupdatePolicy
) и установите параметрenabled
вtrue
:1kubectl apply -f - <<EOF 2 apiVersion: deckhouse.io/v1alpha1 3 kind: ModuleConfig 4 metadata: 5 name: helloworld 6 spec: 7 enabled: true 8 source: ghcr 9 updatePolicy: helloworld-policy
-
Проверьте ModuleSource (в статусе не должно содержаться ошибок и должны быть перечислены доступные модули):
1kubectl get ms ghcr -o yaml
-
Убедитесь, что были созданы новые объекты ModuleRelease для модуля:
1kubectl get mr
Пример вывода:
1$ kubectl get mr 2NAME PHASE UPDATE POLICY TRANSITIONTIME MESSAGE 3helloworld-v0.0.1 Deployed helloworld-policy 22m
-
В случае успешной установки релизов дождитесь перезапуска пода Deckhouse Kubernetes Platform.
1kubectl -n d8-system get pod -l app=deckhouse
Через некоторое время объекты модуля появятся в кластере.
Если при запуске модуля возникли ошибки, посмотрите журнал DKP:
1kubectl -n d8-system logs deploy/deckhouse -f | jq -rc '.msg'
или проверьте состояние очереди DKP:
1kubectl -n d8-system exec svc/deckhouse-leader -c deckhouse -- deckhouse-controller queue list
Миграция ModuleUpdatePolicy на версию v1alpha2
Если в кластере существует ModuleUpdatePolicy версии v1alpha1, то необходимо выполнить следующие шаги по миграции на версию v1alpha2:
Если в кластере в каком-либо ModuleUpdatePolicy версии v1alpha1 определен moduleReleaseSelector
, то для всех модулей, которые подходят под этот селектор, в системе мониторинга будут гореть алерты ModuleHasDeprecatedUpdatePolicy. В этом случае выполните следующие шаги по миграции на версию v1alpha2 ModuleUpdatePolicy:
- Укажите политику обновления для соответствующих модулей в параметре
spec.updatePolicy
ModuleConfig. -
Выполните следующую команду, указав необходимый ModuleUpdatePolicy:
1kubectl patch moduleupdatepolicies.v1alpha1.deckhouse.io <MUP_NAME> --type='json' \ 2 -p='[{"op": "replace", "path": "/spec/moduleReleaseSelector/labelSelector/matchLabels", "value": {"": ""}}]'