Конфигурация

Модуль настраивается через ModuleConfig. Контракт содержит параметры платформенного уровня: уровень логирования, объектное хранилище, способ доставки и режим раздачи каталога. Списки моделей, внешние каталоги и пользовательские импорты не хранятся в ModuleConfig.

Пример минимальной конфигурации

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: ai-models
spec:
  enabled: true
  version: 1
  settings:
    artifacts:
      bucket: ai-models
      endpoint: https://s3.example.com
      region: us-east-1
      credentialsSecretName: ai-models-artifacts
      usePathStyle: true

Объектное хранилище и DMCR

artifacts задаёт S3-совместимое объектное хранилище для данных DMCR, временных загрузок и служебных данных передачи. Все модели проходят через управляемый контроллером путь подготовки независимо от источника: URL, загрузка или импорт из внешнего каталога.

DMCR (Deckhouse Model Container Registry) — служебный OCI-реестр модуля. Он хранит подготовленные модели как внутренние OCI-артефакты поверх bucket, настроенного в artifacts.

Учётные данные задаются Secret в d8-system:

apiVersion: v1
kind: Secret
metadata:
  name: ai-models-artifacts
  namespace: d8-system
type: Opaque
stringData:
  accessKey: "<access-key>"
  secretKey: "<secret-key>"

Для частного центра сертификации укажите artifacts.caSecretName или добавьте ca.crt в тот же Secret.

Доставка

delivery.type выбирает способ доставки модели в рабочую нагрузку:

• SharedPVC — значение по умолчанию. Требует StorageClass, подходящий для PVC с RWX.
• NodeCache — локальный кэш на узле поверх SDS и CSI-монтирования.

Параметры доставки являются плоскими полями внутри delivery, чтобы в UI был один переключатель и только релевантные настройки выбранного режима.

Раздача каталога

Раздача каталога включается через distribution.mode=PublicCatalog. Модуль готовит публичный каталог и путь копирования на публичном адресе модуля из глобальных настроек Deckhouse.

spec:
  settings:
    distribution:
      mode: PublicCatalog

Адрес локально не настраивается. Он всегда строится из global.modules.publicDomainTemplate как публичный адрес модуля.

При включении PublicCatalog публикуются два маршрута:

• /api/distribution/v1/models — каталог ClusterModel в фазе Ready;
• /v2 — OCI-путь для управляемого контроллером копирования и импорта.

Это отдельная ось конфигурации от доставки. Доставка внутри потребляющего кластера остаётся SharedPVC или NodeCache; владение каталогом остаётся в раздающем кластере.

Доступ к публичному каталогу задаётся не в ModuleConfig, а через Kubernetes RBAC в раздающем кластере. Привяжите субъект потребителя к ClusterRole d8:ai-models:distribution:reader. Внешние каталоги в потребляющем кластере описываются отдельными ModelCatalogSource. Такой контракт позволяет добавлять или удалять сотни моделей через ClusterModel без изменения конфигурации модуля.

Учётные данные и сертификаты для импортируемых источников тоже не хранятся в ModuleConfig. Поместите их в Secret пространства имён d8-system и укажите эти Secret в ModelCatalogSource.

Требования

К версии Kubernetes: 1.34 и выше.

К версии Deckhouse: 1.75.0 и выше.

Параметры

Версия схемы: 1

• settings

  объект
  • settings.artifacts

    объект

    S3-совместимое хранилище для загружаемых файлов, подготовленных моделей в DMCR и служебных данных передачи. Внутренние префиксы объектов принадлежат модулю.
    • settings.artifacts.bucket

      строка

      Обязательный параметр

      Имя bucket для загружаемых файлов и подготовленных моделей.

      По умолчанию: ‘’

    • settings.artifacts.caSecretName

      строка

      Необязательный существующий Secret в d8-system с ключом ca.crt для доверия частному центру сертификации S3-совместимого хранилища. Если поле пустое, модуль использует credentialsSecretName как источник ca.crt, когда этот Secret содержит такой ключ.

      По умолчанию: ‘’

    • settings.artifacts.capacityLimit

      строка

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

      По умолчанию: ‘’

    • settings.artifacts.credentialsSecretName

      строка

      Обязательный параметр

      Существующий Secret в d8-system с ключами accessKey и secretKey. Secret также может содержать ca.crt, если тот же Secret используется как источник доверенного сертификата для частного центра сертификации S3. Модуль синхронизирует нужные данные в своё служебное пространство имён после его создания. Учётные данные прямо в ModuleConfig не поддерживаются.

      По умолчанию: ‘’

    • settings.artifacts.endpoint

      строка

      Обязательный параметр

      Адрес S3-совместимого хранилища.

      По умолчанию: ‘’

    • settings.artifacts.insecure

      булевый

      Отключает проверку TLS при обращении к S3-совместимому хранилищу.

      По умолчанию: false

    • settings.artifacts.region

      строка

      Регион S3, который использует клиент.

      По умолчанию: us-east-1

    • settings.artifacts.usePathStyle

      булевый

      Использовать path-style запросы S3.

      По умолчанию: true

  • settings.delivery

    объект

    Способ доставки модели в рабочие нагрузки. Активен ровно один вариант: SharedPVC для управляемого контроллером RWX PVC или NodeCache для локального кэша на выбранных узлах и CSI-монтирования только для чтения. Раздача каталога между кластерами отделена от доставки в приложения и не является дополнительным значением delivery.type.
    • settings.delivery.nodeCacheBlockDeviceSelector

      объект

      Селектор matchLabels для ресурсов BlockDevice, из которых строится группа томов локального кэша. Пустое значение означает ai.deckhouse.io/model-cache=true.

      Пример:

      
      

      ai.deckhouse.io/model-cache: 'true'
      

    • settings.delivery.nodeCacheNodeSelector

      объект

      Селектор matchLabels для нод, где должен работать локальный кэш. Пустое значение означает ai.deckhouse.io/model-cache=true.

      Пример:

      
      

      ai.deckhouse.io/model-cache: 'true'
      

    • settings.delivery.nodeCacheSize

      строка

      Размер кэша на каждом выбранном узле для NodeCache. То же значение используется для локального хранилища и PVC кэша на узле. Пустое значение означает 200Gi.

      Пример:

      
      

      nodeCacheSize: 200Gi
      

    • settings.delivery.sharedPVCStorageClassName

      строка

      StorageClass для режима SharedPVC. Пустое значение означает: сначала глобальные настройки класса хранения Deckhouse, затем Kubernetes default StorageClass. Найденный класс должен существовать, быть выбран однозначно и поддерживать PVC с ReadWriteMany.

      Примеры:

      
      

      sharedPVCStorageClassName: rwx-storage-class
      

      sharedPVCStorageClassName: nfs-rwx
      

    • settings.delivery.type

      строка

      Обязательный параметр

      Способ доставки модели в рабочие нагрузки.

      SharedPVC используется по умолчанию. Он создаёт управляемый контроллером RWX PVC в пространстве имён рабочей нагрузки. Пустой delivery.sharedPVCStorageClassName выбирается через глобальные настройки класса хранения Deckhouse (global.modules.storageClass, затем global.defaultClusterStorageClass) и затем default StorageClass. Если найденный класс отсутствует, рабочая нагрузка остаётся в ожидании с причиной SharedPVCStorageClassMissing. Если в кластере несколько default StorageClass, рабочая нагрузка остаётся в ожидании с причиной SharedPVCStorageClassAmbiguous, пока модуль или глобальные настройки Deckhouse не выберут один класс явно. Провайдер хранилища отвечает за привязку итогового PVC с ReadWriteMany; его ошибки видны в событиях PVC.

      NodeCache создаёт локальный кэш на выбранных узлах поверх SDS и CSI-монтирования только для чтения.

      По умолчанию: SharedPVC

      Допустимые значения: SharedPVC, NodeCache

  • settings.distribution

    объект

    Режим раздачи каталога подготовленных кластерных моделей. Эта настройка независима от доставки в рабочие нагрузки: delivery.type выбирает, как приложения получают файлы модели внутри кластера, а distribution.mode выбирает, открыт ли защищённый публичный интерфейс для импорта моделей в другие кластеры.
    • settings.distribution.mode

      строка

      Обязательный параметр

      Режим раздачи каталога.

      InternalOnly оставляет DMCR доступным только внутри кластера.

      PublicCatalog открывает защищённый /v2 endpoint на публичном адресе модуля. Список моделей и импорт описываются через ModelCatalogSource; внутренние пути реестра, список моделей и отдельный host здесь не настраиваются.

      По умолчанию: InternalOnly

      Допустимые значения: InternalOnly, PublicCatalog

  • settings.logLevel

    строка

    Уровень логирования служебных компонентов модуля.

    По умолчанию: Info

    Допустимые значения: Debug, Info, Warn, Error