Configuration

The module is configured through ModuleConfig. The contract contains platform-level settings: logging level, object storage, delivery mode, and distribution mode. Model lists, upstreams, and user catalog imports are not stored in ModuleConfig.

Minimal Configuration

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

Object Storage and DMCR

artifacts configures S3-compatible object storage for DMCR data, upload staging, and module byte-path data. Every model goes through this controller-owned preparation path regardless of source: URL, upload, or catalog import.

DMCR (Deckhouse Model Container Registry) is the module’s internal OCI registry. It stores prepared models as internal OCI artifacts on top of the bucket configured in artifacts.

Credentials are provided through a Secret in d8-system:

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

For a custom CA, set artifacts.caSecretName or add ca.crt to the same Secret.

External Provider Catalog Data Services

External provider catalogs, such as Hugging Face, can contain far more entries than the Kubernetes API should store or watch. The module therefore keeps remote provider search/index data outside etcd. Only a model that a user or administrator explicitly imports becomes a local Model or ClusterModel.

When external provider browse/search/import is enabled, the module requires two already provisioned data services:

• PostgreSQL-compatible database for the durable external catalog index, synchronization state, schema migration state, and import history.
• Valkey-compatible service for short-lived search cache, provider rate-limit counters, distributed locks, and temporary coordination.

ai-models does not create PostgreSQL or Valkey instances. The administrator provides connection Secrets for existing services. Those services can be created with DKP managed-postgres and managed-valkey modules, by a corporate DBaaS, or by another operational process. The DKP managed modules are a convenient provisioning option, not an architectural dependency of ai-models.

Configure the module with existing Secret names:

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

The referenced Secrets must be in d8-system. When external catalog is enabled, the controller readiness probe validates the Secrets and performs bounded live probes before reporting the external catalog data services as ready.

Recommended Secret shape:

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 is needed only when the service uses a private CA. Secret values, provider tokens, and database passwords must not be copied into Model, ClusterModel, events, metrics labels, or user-facing status messages.

Before synchronizing a provider source, configure safe bounds for the source: allowed organizations, repositories, collections or tags, maximum indexed entries, metadata-size limits, refresh interval, and refresh budget. A source that is too broad must stay blocked with an actionable reason such as SourcePolicyTooBroad instead of starting an unbounded provider scan.

External catalog readiness is separate from model readiness. The current controller readiness check verifies PostgreSQL connection/auth/database reachability with a temporary read/write probe, and verifies Valkey with PING, TTL read/write, lock and rate-limit key probes. Future source/status slices will project distinct reasons for PostgreSQL failures, Valkey failures, provider rate limits, invalid data-service Secrets, and source-policy violations. If PostgreSQL or Valkey is unavailable, external catalog search/import must remain unavailable or waiting; the module must not fall back to storing remote provider entries in etcd or an unbounded in-memory index.

A user flow with an external provider catalog is:

1. The administrator configures data-service connections and a bounded provider source.
2. The module checks PostgreSQL, Valkey, and provider/source readiness.
3. A user searches or previews remote provider entries.
4. The user explicitly imports one entry.
5. Only that selected entry becomes a local Model or ClusterModel and then follows the normal preparation path into DMCR.

Delivery

delivery.type selects how models in the Ready phase are mounted into workloads:

• SharedPVC — the default value. Requires a StorageClass suitable for RWX PVCs.
• NodeCache — node-local cache backed by SDS and a CSI mount.

Delivery parameters are flat fields inside delivery, so the UI has one selector and only the relevant settings for the selected mode.

Distribution

Distribution is enabled through distribution.mode=PublicCatalog. It prepares the public catalog/import surface on the module public host from global Deckhouse settings.

spec:
  settings:
    distribution:
      mode: PublicCatalog

The host is not configured locally. It is always derived from global.modules.publicDomainTemplate as the module public host.

When PublicCatalog is enabled, two routes are published:

• /api/distribution/v1/models — the semantic catalog of ClusterModel objects in the Ready phase;
• /v2 — the OCI byte path for controller-owned copy/import workflows.

This is separate from delivery. Workload delivery inside the consuming cluster remains SharedPVC or NodeCache; catalog ownership remains in the publishing cluster.

Production public catalog access is configured with Kubernetes RBAC in the publishing cluster, not in ModuleConfig. Bind the consuming subject to ClusterRole d8:ai-models:distribution:reader. External catalogs on a consuming cluster are described with ModelCatalogSource. This keeps adding or removing hundreds of ClusterModel objects out of module configuration.

Catalog credentials and custom CA for imported sources are also not stored in ModuleConfig. Put them into d8-system Secrets and reference them from ModelCatalogSource.

Requirements

To the Kubernetes version: 1.34 and above.

To the Deckhouse version: 1.75.0 and above.

Parameters

Schema version: 1

• settings

  object
  • settings.artifacts

    object

    S3-compatible storage for upload staging, the publication store, and module byte-path data. Internal object prefixes are module-owned.
    • settings.artifacts.bucket

      string

      Required value

      Bucket name for upload staging and published model artifacts.

      Default: ‘’

    • settings.artifacts.caSecretName

      string

      Optional existing Secret in d8-system with key ca.crt used to trust a custom CA for the S3-compatible endpoint. When empty, the module uses credentialsSecretName as the CA source if that Secret contains ca.crt.

      Default: ‘’

    • settings.artifacts.capacityLimit

      string

      Optional total capacity budget for module-owned artifacts, for example 500Gi. When set, upload sessions must declare payload size and the upload gateway reserves capacity before staging. Empty value disables admission enforcement and reports capacity as unknown.

      Default: ‘’

    • settings.artifacts.credentialsSecretName

      string

      Required value

      Existing Secret in d8-system with accessKey and secretKey. The Secret may also contain ca.crt when the same Secret is used as the custom S3 trust source. The module synchronizes the required data into its service namespace after the Helm-owned namespace exists. This Secret is required; inline credentials are not supported.

      Default: ‘’

    • settings.artifacts.endpoint

      string

      Required value

      S3-compatible endpoint URL.

      Default: ‘’

    • settings.artifacts.insecure

      boolean

      Disable TLS verification for S3-compatible endpoint access.

      Default: false

    • settings.artifacts.region

      string

      S3 region value used by the client.

      Default: us-east-1

    • settings.artifacts.usePathStyle

      boolean

      Use path-style S3 requests.

      Default: true

  • settings.delivery

    object

    Workload delivery backend. Exactly one backend is active: SharedPVC for controller-owned RWX PVC materialization, or NodeCache for SDS-backed node-local cache and CSI delivery. Perimeter distribution is separate from workload delivery and is not an additional delivery.type value.
    • settings.delivery.maxConcurrentMaterializations

      integer

      Maximum number of SharedPVC materializer Jobs running concurrently cluster-wide. Each consumer namespace materializes the model into its own ReadWriteMany PVC; these materializations contend for registry read and storage write bandwidth, so throughput saturates at low concurrency and degrades beyond it. A conservative bound keeps per-materialization latency low so pods do not sit in SchedulingGated for minutes; raise it on clusters with more nodes or faster storage. Empty value means 2.

      Allowed values: 1 <= X <= 64

      Examples:

      maxConcurrentMaterializations: 2
      

      maxConcurrentMaterializations: 4
      

    • settings.delivery.nodeCacheBlockDeviceSelector

      object

      MatchLabels selector for BlockDevice resources used to build the managed cache volume group. Empty value means ai.deckhouse.io/model-cache=true.

      Example:

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

    • settings.delivery.nodeCacheNodeSelector

      object

      MatchLabels selector for nodes that should host managed node-local cache substrate. Empty value means ai.deckhouse.io/model-cache=true.

      Example:

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

    • settings.delivery.nodeCacheSize

      string

      Per-node cache size for NodeCache. The same value is used for managed local storage capacity and for the per-node shared cache PVC. Empty value means 200Gi.

      Example:

      nodeCacheSize: 200Gi
      

    • settings.delivery.sharedPVCStorageClassName

      string

      StorageClass name for SharedPVC delivery. Empty value means Deckhouse global storage class settings first, then Kubernetes default StorageClass. The resolved class must exist, be unambiguous and use volumeBindingMode: Immediate before workload delivery can create the shared ReadWriteMany PVC. A WaitForFirstConsumer class cannot be used: delivery waits for the volume to bind before creating its consumer, so such a volume would never bind.

      Examples:

      sharedPVCStorageClassName: rwx-storage-class
      

      sharedPVCStorageClassName: nfs-rwx
      

    • settings.delivery.type

      string

      Required value

      Workload delivery backend.

      SharedPVC is the default. It creates controller-owned RWX PVCs in workload namespaces. Empty delivery.sharedPVCStorageClassName resolves through Deckhouse global storage class settings (global.modules.storageClass, then global.defaultClusterStorageClass) and then Kubernetes default StorageClass. The resolved class must exist, be unambiguous and use volumeBindingMode: Immediate. Unmet prerequisites are reported at the module level as soon as the module starts, through the d8_ai_models_storage_prerequisites_satisfied metric and the D8AIModelsStoragePrerequisitesNotSatisfied alert, without waiting for a workload; the module stays enabled and its catalog surfaces keep working while degraded. Per workload the same defects appear as gate reasons SharedPVCStorageClassMissing and SharedPVCStorageClassAmbiguous. The storage provisioner is responsible for provisioning the resulting ReadWriteMany PVC; a failure it reports is surfaced with reason SharedPVCProvisioningFailed, and a volume left unprovisioned with no reported cause becomes SharedPVCProvisioningTimedOut instead of waiting indefinitely.

      NodeCache creates managed SDS-backed node-local cache substrate and read-only CSI mounts.

      Default: SharedPVC

      Allowed values: SharedPVC, NodeCache

  • settings.distribution

    object

    Distribution mode for published model artifacts. This setting is independent from workload delivery: delivery.type controls how workloads mount artifacts, while distribution.mode controls whether the module exposes the publication byte path as a controller-owned distribution surface for downstream catalog/import topologies.
    • settings.distribution.mode

      string

      Required value

      Distribution mode.

      InternalOnly keeps the publication registry available only inside the cluster.

      PublicCatalog exposes a public /v2 transport endpoint on the module public host. Semantic catalog API and ModelCatalogSource import are implemented in the controller/API slice; users do not configure model lists, registry paths, or custom hosts here.

      Default: InternalOnly

      Allowed values: InternalOnly, PublicCatalog

  • settings.externalCatalog

    object

    External provider catalog browse/search/import configuration. This enables the future provider-index path for sources such as Hugging Face. Remote provider entries are stored outside Kubernetes etcd and become local Model or ClusterModel objects only after explicit import. PostgreSQL and Valkey services must already exist; the module only reads connection Secrets and does not provision database or cache instances.
    • settings.externalCatalog.dataServices

      object

      Connection Secret names for already provisioned external catalog data services. PostgreSQL stores durable provider index data. Valkey stores short-lived cache, rate-limit counters and locks. The module validates Secret presence, connection string shape and bounded live probes before reporting external catalog readiness. PostgreSQL is checked with a temporary read/write probe. Valkey is checked with PING, TTL read/write, lock and rate-limit key probes.
      • settings.externalCatalog.dataServices.postgresConnectionSecretName

        string

        Existing Secret name in d8-system with key dsn. The value must be a PostgreSQL DSN using postgres:// or postgresql:// and include a database name. The Secret may also contain ca.crt for a private CA.

        Default: ‘’

      • settings.externalCatalog.dataServices.valkeyConnectionSecretName

        string

        Existing Secret name in d8-system with key url. The value must be a Valkey-compatible URL using redis:// or rediss://. The Secret may also contain ca.crt for a private CA.

        Default: ‘’

    • settings.externalCatalog.enabled

      boolean

      Enable external provider catalog data-service readiness checks. When true, dataServices.postgresConnectionSecretName and dataServices.valkeyConnectionSecretName are required and must name existing Secrets in d8-system.

      Default: false

  • settings.logLevel

    string

    Logging level for module runtime components.

    Default: Info

    Allowed values: Debug, Info, Warn, Error