Пример создания модуля helloworld на основе шаблона модуля и адаптации Helm-чарта hello-world.

Подготовка исходного кода модуля и сборка

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

  2. Сделайте форк или скопируйте репозиторий шаблона модуля.

    git clone git@github.com:deckhouse/modules-template.git helloworld \
  && cd helloworld

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

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

    Обратите внимание, что в некоторых местах в примере имя модуля может быть записано в разных форматах — kebab-case или camelCase. Если вы используете свое имя модуля, то учитывайте изменение формата имени модуля в приводимых командах.

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

    sed -i -e 's/^name:.*$/name: helloworld/' module.yaml

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

    git clone https://github.com/giantswarm/hello-world-app .tmp-chart

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

    rm -rf templates/*
cp -fR .tmp-chart/helm/hello-world/templates/* templates/
cp .tmp-chart/helm/hello-world/values.yaml values.yaml

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

    Это архитектурная особенность addon-operator, ей необходимо следовать для обращения к values модуля.

    sed -i -e 's/.Values/.Values.helloworld/g' $(find templates/ -type f)

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

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

    jq 'walk(
   if type == "object" and .type == "object" and (keys | length) == 1
   then . + {additionalProperties: true}
   else .
   end
)' .tmp-chart/helm/hello-world/values.schema.json > openapi/config-values.yaml

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

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

    rm -rf images/*
mkdir images/helloworld
echo "FROM quay.io/giantswarm/helloworld:0.2.0" > images/helloworld/Dockerfile

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

    sed -Ei 's/image\:(.*)/image: {{ include "helm_lib_module_image" (list . "helloworld") }}/g' templates/deployment.yaml

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

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

    rm -rf hooks/
rm -rf crds/
rm -rf .tmp-chart

  11. Настройте 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.

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

    git add .
git commit -m "Initial Commit"
git push --set-upstream origin <GIT_REPO_URL>

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

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

    Пример:

    Пример workflow сборки модуля

Публикация модуля на канале обновлений

Пример публикации версии 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.

    Пример запуска workflow публикации модуля

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

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

Подключение модуля в кластере

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

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

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

    base64 -w0 <<EOF
{
  "auths": {
    "ghcr.io": {
      "auth": "$(echo -n '<OWNER>:<TOKEN>' | base64 -w0)"
    }
  }
}
EOF

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

    kubectl apply -f - <<EOF
apiVersion: deckhouse.io/v1alpha1
kind: ModuleSource
metadata:
  name: ghcr
spec:
  registry:
    # Укажите имя пользователя (или организации) GitHub. Например: ghcr.io/octocat/modules
    repo: ghcr.io/<!OWNER>/modules
    # Строка аутентификации для доступа к GitHub Packages из предыдущего шага.
    dockerCfg: <!REGISTRY_CREDENTIALS>
EOF

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

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

    $ kubectl get module
NAME       WEIGHT   SOURCE   PHASE       ENABLED   READY
...
helloworld                   Available   False     False     
...

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

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

    kubectl apply -f - <<EOF
apiVersion: deckhouse.io/v1alpha2
kind: ModuleUpdatePolicy
metadata:
  name: helloworld-policy
spec:
  releaseChannel: Alpha
  update:
    mode: Auto
EOF

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

    kubectl apply -f - <<EOF
   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: helloworld
   spec:
      enabled: true
      source: ghcr
      updatePolicy: helloworld-policy

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

    kubectl get ms ghcr -o yaml

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

    kubectl get mr

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

    $ kubectl get mr
NAME                                PHASE        UPDATE POLICY        TRANSITIONTIME   MESSAGE
helloworld-v0.0.1                   Deployed     helloworld-policy    22m

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

    kubectl -n d8-system get pod -l app=deckhouse

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

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

    kubectl -n d8-system logs deploy/deckhouse -f | jq -rc '.msg'

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

    kubectl -n d8-system exec svc/deckhouse-leader -c deckhouse -- deckhouse-controller queue list

Миграция ModuleUpdatePolicy на версию v1alpha2

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

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

  • Укажите политику обновления для соответствующих модулей в параметре properties.updatePolicy moduleConfig.

  • Выполните следующую команду, указав необходимый ModuleUpdatePolicy:

    kubectl patch moduleupdatepolicies.v1alpha1.deckhouse.io <MUP_NAME> --type='json' \
  -p='[{"op": "replace", "path": "/spec/moduleReleaseSelector/labelSelector/matchLabels", "value": {"": ""}}]'