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

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

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

    1git clone git@github.com:deckhouse/modules-template.git helloworld \
    2  && cd helloworld
    
  3. Укажите имя модуля в файле module.yaml.

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

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

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

    1sed -i -e 's/^name:.*$/name: helloworld/' module.yaml
    
  4. Склонируйте исходный код чарта hello-world во временную директорию.

    1git clone https://github.com/giantswarm/hello-world-app .tmp-chart
    
  5. Скопируйте шаблоны чарта в директорию templates модуля, предварительно очистив ее.

    1rm -rf templates/*
    2cp -fR .tmp-chart/helm/hello-world/templates/* templates/
    3cp .tmp-chart/helm/hello-world/values.yaml values.yaml
    
  6. Замените в шаблонах чарта путь .Values на .Values.helloworld.

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

    1sed -i -e 's/.Values/.Values.helloworld/g' $(find templates/ -type f)
    
  7. Добавьте 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
    
  8. Опишите правило сборки образа контейнера приложения.

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

    1rm -rf images/*
    2mkdir images/helloworld
    3echo "FROM quay.io/giantswarm/helloworld:0.2.0" > images/helloworld/Dockerfile
    
  9. Замените образ в манифесте Deployment на хелпер библиотеки Deckhouse Kubernetes Platform. Это позволит использовать актуальный content-based-тэг образа.

    1sed -Ei 's/image\:(.*)/image: {{ include "helm_lib_module_image" (list . "helloworld") }}/g' templates/deployment.yaml
    
  10. Удалите хуки модуля, CRD и временные файлы.

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

    1rm -rf hooks/
    2rm -rf crds/
    3rm -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-репозитория модуля).

    1git add .
    2git commit -m "Initial Commit"
    3git 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 и токен доступа:

    1base64 -w0 <<EOF
    2{
    3  "auths": {
    4    "ghcr.io": {
    5      "auth": "$(echo -n '<OWNER>:<TOKEN>' | base64 -w0)"
    6    }
    7  }
    8}
    9EOF
    
  3. Создайте в кластере ресурс 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
    

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

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

    1$ kubectl get module
    2NAME       WEIGHT   SOURCE   PHASE       ENABLED   READY
    3...
    4helloworld                   Available   False     False     
    5...
    
  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
    
  6. Создайте 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
    
  7. Проверьте ModuleSource (в статусе не должно содержаться ошибок и должны быть перечислены доступные модули):

    1kubectl get ms ghcr -o yaml
    
  8. Убедитесь, что были созданы новые объекты ModuleRelease для модуля:

    1kubectl get mr
    

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

    1$ kubectl get mr
    2NAME                                PHASE        UPDATE POLICY        TRANSITIONTIME   MESSAGE
    3helloworld-v0.0.1                   Deployed     helloworld-policy    22m            
    
  9. В случае успешной установки релизов дождитесь перезапуска пода 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": {"": ""}}]'