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

Модуль настраивается через 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.

Учётные данные задаются секретом в 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 в тот же секрет.

Службы данных для внешнего каталога provider’а

Внешние каталоги provider’ов, например Hugging Face, могут содержать гораздо больше записей, чем Kubernetes API должен хранить или отслеживать через watch. Поэтому модуль хранит данные поиска и индекса внешнего provider’а вне etcd. Только модель, которую пользователь или администратор явно импортировал, становится локальным Model или ClusterModel.

Когда включён просмотр, поиск и импорт из внешнего каталога provider’а, модулю нужны две уже созданные службы данных:

• PostgreSQL-совместимая база данных для долговечного индекса внешнего каталога, состояния синхронизации, состояния миграций схемы и истории импортов.
• Valkey-совместимая служба для краткоживущего кэша поиска, счётчиков лимитов provider API, распределённых блокировок и временной координации.

ai-models не создаёт экземпляры PostgreSQL или Valkey. Администратор передаёт модулю Secret с настройками подключения к уже существующим службам. Эти службы можно создать через DKP managed-postgres и managed-valkey, через корпоративный DBaaS или другим эксплуатационным процессом. DKP managed-модули — удобный способ подготовить службы, но не архитектурная зависимость ai-models.

Настройте модуль с именами существующих Secret:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: ai-models
spec:
  enabled: true
  version: 1
  settings:
    externalCatalog:
      enabled: true
      dataServices:
        postgresConnectionSecretName: ai-models-catalog-postgres
        valkeyConnectionSecretName: ai-models-catalog-valkey

Указанные Secret должны находиться в d8-system. Если внешний каталог включён, readiness check контроллера проверяет Secret и выполняет ограниченные live probes перед тем, как считать службы данных внешнего каталога готовыми.

Рекомендуемая форма Secret:

apiVersion: v1
kind: Secret
metadata:
  name: ai-models-catalog-postgres
  namespace: d8-system
type: Opaque
stringData:
  dsn: "postgres://ai_models:<password>@postgres.example.com:5432/ai_models_catalog?sslmode=require"
  ca.crt: |-
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

apiVersion: v1
kind: Secret
metadata:
  name: ai-models-catalog-valkey
  namespace: d8-system
type: Opaque
stringData:
  url: "rediss://:<password>@valkey.example.com:6379/0"
  ca.crt: |-
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

ca.crt нужен только если служба использует частный центр сертификации. Значения Secret, provider tokens и пароли базы данных нельзя копировать в Model, ClusterModel, события, labels метрик или пользовательские status messages.

Перед синхронизацией provider source задайте безопасные границы источника: разрешённые организации, репозитории, коллекции или теги, максимальное число индексируемых записей, лимиты размера metadata, интервал обновления и бюджет обновления. Слишком широкий источник должен оставаться заблокированным с понятной причиной, например SourcePolicyTooBroad, а не начинать безлимитное сканирование provider’а.

Готовность внешнего каталога отделена от готовности модели. Текущий readiness check контроллера проверяет PostgreSQL connection/auth/database reachability через временную read/write-пробу, а Valkey — через PING, TTL read/write, lock и rate-limit key probes. Следующие source/status slices будут выводить отдельные причины для сбоев PostgreSQL, сбоев Valkey, лимитов provider API, невалидных Secret служб данных и нарушений source policy. Если PostgreSQL или Valkey недоступны, поиск и импорт из внешнего каталога должны оставаться недоступными или в ожидании; модуль не должен переходить к хранению записей внешнего provider’а в etcd или безлимитном in-memory индексе.

Пользовательский сценарий с внешним каталогом provider’а:

1. Администратор настраивает подключения к службам данных и bounded provider source.
2. Модуль проверяет готовность PostgreSQL, Valkey и provider/source.
3. Пользователь ищет или просматривает записи внешнего provider’а.
4. Пользователь явно импортирует одну запись.
5. Только выбранная запись становится локальным Model или ClusterModel и дальше проходит обычный путь подготовки в DMCR.

Доставка

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. Поместите их в секрет неймспейса d8-system и укажите эти секреты в 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.maxConcurrentMaterializations

      целочисленный

      Максимальное число одновременно выполняющихся Job-материализаторов SharedPVC в пределах кластера. Каждый namespace-потребитель материализует модель в свой ReadWriteMany PVC, и эти материализации конкурируют за полосу чтения из реестра и записи в хранилище, поэтому пропускная способность насыщается уже при низкой конкурентности и деградирует выше неё. Консервативное значение снижает задержку материализации, чтобы поды не оставались в SchedulingGated минутами; увеличивайте на кластерах с бо́льшим числом узлов или более быстрым хранилищем. Пустое значение означает 2.

      Допустимые значения: 1 <= X <= 64

      Примеры:

      maxConcurrentMaterializations: 2
      

      maxConcurrentMaterializations: 4
      

    • 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 и использовать volumeBindingMode: Immediate. Класс с WaitForFirstConsumer использовать нельзя: доставка ждёт привязки тома, прежде чем создать его потребителя, поэтому такой том не будет привязан никогда.

      Примеры:

      sharedPVCStorageClassName: rwx-storage-class
      

      sharedPVCStorageClassName: nfs-rwx
      

    • settings.delivery.type

      строка

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

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

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

      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.externalCatalog

    объект

    Настройка просмотра, поиска и импорта из внешнего каталога provider’а. Эта настройка включает будущий путь индексации provider’ов, например Hugging Face. Записи внешнего provider’а хранятся вне Kubernetes etcd и становятся локальными Model или ClusterModel только после явного импорта. Службы PostgreSQL и Valkey должны уже существовать; модуль только читает Secret с настройками подключения и не создаёт базу данных или кэш.
    • settings.externalCatalog.dataServices

      объект

      Имена Secret с подключениями к уже созданным службам данных внешнего каталога. PostgreSQL хранит долговечные данные индекса provider’а. Valkey хранит краткоживущий кэш, счётчики лимитов и блокировки. Модуль проверяет наличие Secret, форму строки подключения и ограниченные live probes перед тем, как считать внешний каталог готовым. PostgreSQL проверяется временной read/write-пробой. Valkey проверяется через PING, TTL read/write, lock и rate-limit key probes.
      • settings.externalCatalog.dataServices.postgresConnectionSecretName

        строка

        Имя существующего Secret в d8-system с ключом dsn. Значение должно быть PostgreSQL DSN со схемой postgres:// или postgresql:// и именем базы данных. Secret также может содержать ca.crt для частного центра сертификации.

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

      • settings.externalCatalog.dataServices.valkeyConnectionSecretName

        строка

        Имя существующего Secret в d8-system с ключом url. Значение должно быть Valkey-compatible URL со схемой redis:// или rediss://. Secret также может содержать ca.crt для частного центра сертификации.

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

    • settings.externalCatalog.enabled

      булевый

      Включает проверки готовности служб данных внешнего каталога provider’а. Если значение true, поля dataServices.postgresConnectionSecretName и dataServices.valkeyConnectionSecretName обязательны и должны указывать на существующие Secret в d8-system.

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

  • settings.logLevel

    строка

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

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

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