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

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

Источник модулей

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

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

apiVersion: deckhouse.io/v1alpha1
kind: ModuleSource
metadata:
  name: example
spec:
  registry:
    repo: registry.example.com/deckhouse/modules
    dockerCfg: <base64 encoded credentials>

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

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

kubectl get ms

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

$ kubectl get ms
NAME        COUNT   SYNC   MSG
example     2       16s    Ready

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

$ kubectl get ms
NAME        COUNT   SYNC   MSG
example     2       16s    Some errors occurred. Inspect status for details

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

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

$ kubectl get ms example -o jsonpath='{range .status.modules[*]}{.name}{" module error:\n\t"}{.pullError}{"\n"}{end}'
module-1 module error:
  fetch image error: GET https://registry.example.com/v2/deckhouse/modules/module-1/release/manifests/stable: MANIFEST_UNKNOWN: manifest unknown; map[Tag:stable]
module-2 module error:
  fetch image error: GET https://registry.example.com/v2/deckhouse/modules/module-2/release/manifests/stable: MANIFEST_UNKNOWN: manifest unknown; map[Tag:stable]

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

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

$ kubectl get ms example -o jsonpath='{.status.modules[*].name}'
module-1 module-2

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

kubectl get ms  -o jsonpath='{.items[*].status.modules[*].name}'

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

kubectl get module

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

$ kubectl get module
NAME       WEIGHT   SOURCE   PHASE       ENABLED   READY
module-one                   Available   False     False                      
module-two                   Available   False     False                      

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

kubectl get module module-one -oyaml

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

apiVersion: deckhouse.io/v1alpha1
kind: Module
metadata:
  creationTimestamp: "2024-12-12T10:49:40Z"
  generation: 1
  name: module-one
  resourceVersion: "241504954"
  uid: 3ae75474-8e96-4105-a939-6df71cba82d8
properties:
  availableSources:
  - example
status:
  conditions:
  - lastProbeTime: "2024-12-12T10:49:41Z"
    lastTransitionTime: "2024-12-12T10:49:41Z"
    message: disabled
    reason: Disabled
    status: "False"
    type: EnabledByModuleConfig
  - lastProbeTime: "2024-12-12T10:49:41Z"
    lastTransitionTime: "2024-12-12T10:49:41Z"
    status: "False"
    type: EnabledByModuleManager
  - lastProbeTime: "2024-12-16T15:46:26Z"
    lastTransitionTime: "2024-12-12T10:49:41Z"
    message: not installed
    reason: NotInstalled
    status: "False"
    type: IsReady
  phase: Available

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

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

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

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

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

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: module-one
spec:
  enabled: true
  source: example

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

$ kubectl get module module-one
NAME        WEIGHT   SOURCE   PHASE         ENABLED   READY
module-one           example  Downloading   False     False

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

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

$ kubectl get module module-one
NAME        WEIGHT   SOURCE   PHASE         ENABLED   READY
module-one  900      example  Installing    False     False

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

$ kubectl get module module-one
NAME        WEIGHT   SOURCE   PHASE  ENABLED  READY
module-one  900      example  Ready  True     True

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

apiVersion: deckhouse.io/v1alpha1
kind: Module
metadata:
  creationTimestamp: "2024-11-18T15:34:15Z"
  generation: 1
  name: module-one
  resourceVersion: "242153004"
  uid: 7111cee7-50cd-4ecf-ba20-d691b13b0f59
properties:
  availableSources:
  - example
  releaseChannel: Stable
  requirements:
    deckhouse: '> v1.63.0'
    kubernetes: '> v1.25.0'
  source: example
  version: v0.7.24
  weight: 910
status:
  conditions:
  - lastProbeTime: "2024-12-12T15:49:35Z"
    lastTransitionTime: "2024-12-12T15:49:35Z"
    status: "True"
    type: EnabledByModuleConfig
  - lastProbeTime: "2024-12-17T09:35:27Z"
    lastTransitionTime: "2024-12-12T15:49:39Z"
    status: "True"
    type: EnabledByModuleManager
  - lastProbeTime: "2024-12-17T09:35:27Z"
    lastTransitionTime: "2024-12-17T09:35:25Z"
    status: "True"
    type: IsReady
  - lastProbeTime: "2024-12-17T09:32:50Z"
    lastTransitionTime: "2024-12-17T09:32:50Z"
    status: "False"
    type: IsOverridden
  hooksState: 'v0.7.24/hooks/moduleVersion.py: ok'
  phase: Ready

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

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

$ kubectl get module module-one
NAME        WEIGHT   SOURCE   PHASE  ENABLED  READY
module-one  910      example  Error  True     Error

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

$ kubectl get module module-one
NAME        WEIGHT   SOURCE   PHASE     ENABLED  READY
module-one                    Conflict  False    False

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

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

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

kubectl get mr

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

$ kubectl get mr
NAME                       PHASE        UPDATE POLICY   TRANSITIONTIME   MESSAGE
module-one-v0.7.23         Superseded   deckhouse       33h              
module-one-v0.7.24         Deployed     deckhouse       33h              
module-two-v1.2.0          Superseded   deckhouse       48d              
module-two-v1.2.1          Superseded   deckhouse       48d              
module-two-v1.2.3          Deployed     deckhouse       48d              
module-two-v1.2.4          Superseded   deckhouse       44d              
module-two-v1.2.5          Pending      deckhouse       44d              Waiting for the 'release.deckhouse.io/approved: \"true\"' annotation

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

Если релиз модуля находится в статусе Pending, то это значит что он требует ручного подтверждения для установки (смотри далее про политику обновления модуля). Подтвердить релиз модуля можно следующей командой (укажите имя moduleRelease):

kubectl annotate mr <module_release_name> modules.deckhouse.io/approved="true"

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

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

  1. Создайте новый ресурс ModuleSource.

  2. Укажите его в поле source в ModuleConfig.

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

    kubectl get mr
    

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

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

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

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

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

apiVersion: deckhouse.io/v1alpha2
kind: ModuleUpdatePolicy
metadata:
  name: example-update-policy
spec:
  releaseChannel: Alpha
  update:
    mode: Auto
    windows:
    - days:
      - "Mon"
      - "Wed"
      from: "13:30"
      to: "14:00"

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

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

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

kubectl get modules

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

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

$ kubectl get module
NAME       WEIGHT   SOURCE   PHASE       ENABLED   READY
...
module-one                   Available   False     False                      
module-two                   Available   False     False     
...

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

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

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

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

    kubectl -ti -n d8-system exec svc/deckhouse-leader -c deckhouse -- deckhouse-controller module enable <MODULE_NAME>
    
  • Создать ресурс ModuleConfig с параметром enabled: true и настройками модуля.

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

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: module-one
    spec:
      enabled: true
      settings:
        parameter: value
      version: 1
    

Если что-то пошло не так

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

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

    kubectl -n d8-system logs -l app=deckhouse
    
  • Посмотреть объект Module подробнее:

    kubectl get module module-one -oyaml
    
  • Посмотреть объект ModuleConfig модуля:

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

    $ kubectl get moduleconfig module-one
    NAME        ENABLED   VERSION   AGE   MESSAGE
    module-one  true                7s    Ignored: unknown module name
    
  • Посмотреть объект ModuleSource:

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

    $ kubectl get ms
    NAME        COUNT   SYNC   MSG
    example     2       16s    Some errors occurred. Inspect status for details
    

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

kubectl get mr

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

$ kubectl get mr
NAME                 PHASE        UPDATE POLICY          TRANSITIONTIME   MESSAGE
module-1-v1.23.2     Pending      example-update-policy  3m               Waiting for the 'release.deckhouse.io/approved: "true"' annotation

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

kubectl annotate mr module-1-v1.23.2 modules.deckhouse.io/approved="true"