The module lifecycle stage: Experimental
The module has requirements for installation

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.

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.

How to explicitly enable the module…

You may explicitly enable or disable the module in one of the following ways:

  • Via Deckhouse web UI. In the “System” → “System Management” → “Deckhouse” → “Modules” section, open the ai-models module and enable (or disable) the “Module enabled” toggle. Save changes.

    Example:

    Module enable/disable interface

  • Via Deckhouse CLI (d8).

    Use the d8 system module enable command for enabling, or d8 system module disable command for disabling the module (you need Deckhouse CLI (d8), configured to work with the cluster).

    Example of enabling the module:

    d8 system module enable ai-models

  • Using ModuleConfig ai-models.

    Set spec.enabled to true or false in ModuleConfig ai-models (create it if necessary);

    Example of a manifest to enable module ai-models:

    apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: ai-models
spec:
  enabled: true

How to configure the module…

You can configure the module in one of the following ways:

  • Via Deckhouse web UI.

    In the “System” → “System Management” → “Deckhouse” → “Modules” section, open the ai-models module and enable the “Advanced Settings” switch. Fill in the required fields in the “Configuration” tab or specify the module settings in YAML format on the “YAML” tab, excluding the settings section. Save the changes.

    Example:

    Module Setup Interface

    You can also edit the ModuleConfig object ai-models on the “YAML” tab in the module settings window (“System” → “System Management” → “Deckhouse” → “Modules”, open the module ai-models) by specifying the schema version in the spec.version parameter and the necessary module parameters in the spec.settings section.

  • Via Deckhouse CLI (d8) (requires Deckhouse CLI (d8) configured to work with the cluster).

    Edit the existing ModuleConfig ai-models (for more details on configuring Deckhouse, see the documentation) by executing the following command:

    d8 k edit mc ai-models

    Make the necessary changes in the spec.settings section. If necessary, specify the schema version in the spec.version parameter. Save the changes.

    You can also create a file with manifest for ModuleConfig ai-models using the example below. Fill in the spec.settings section with the required module parameters. If necessary, specify the schema version in the spec.version parameter.

    Apply the manifest using the following command (indicate the manifest file name):

    d8 k apply -f <FILENAME>

    Example of a manifest for ModuleConfig ai-models:

    apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: ai-models
spec:
  version: 1
  enabled: true
  settings: # Module parameters from the "Parameters" section below.

How to change the module release channel…

To change the module release channel, follow the instruction.

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.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 and be unambiguous before workload delivery can create the shared ReadWriteMany PVC.

        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. If the resolved class is absent, workloads stay gated with reason SharedPVCStorageClassMissing. If multiple Kubernetes default StorageClass objects exist, workloads stay gated with reason SharedPVCStorageClassAmbiguous until the module or Deckhouse global storage class selects one class explicitly. The storage provisioner is responsible for binding the resulting ReadWriteMany PVC; provisioner failures are visible in PVC events.

        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.logLevel
      string
      Logging level for module runtime components.

      Default: Info

      Allowed values: Debug, Info, Warn, Error