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

The Deckhouse Kubernetes Platform installs CRDs but does not remove them when a module is disabled. If you no longer need the created CRDs, delete them.

ClusterModel

Scope: Cluster
Version: v1alpha1

ClusterModel describes one cluster-scoped shared model prepared from a remote source or external catalog. Workloads consume it with the top-level annotation ai.deckhouse.io/clustermodel after the model gets status.phase=Ready.
  • spec
    object
    ClusterModelSpec declares the immutable source for one cluster-scoped model.
    • spec.source
      object

      Required value

      • spec.source.catalog
        object
        Catalog imports a cluster model entry from a ModelCatalogSource.
        • spec.source.catalog.name
          string

          Required value

          Name is the public catalog model name.

          Length: 1..253

          Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        • spec.source.catalog.sourceName
          string
          SourceName selects a ModelCatalogSource. When omitted, the controller may use the only Ready ModelCatalogSource in the cluster.

          Length: 1..253

          Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        • spec.source.catalog.version
          string
          Version selects a catalog version when the upstream exposes more than one active version for the same name.

          Length: 1..128

      • spec.source.upload
        object
        Upload requests a controller-owned upload session for a local file or archive.
      • spec.source.url
        string
        URL points to a Hugging Face repository or an Ollama registry reference.

        Minimal length: 1

        Pattern: ^https:\/\/(((www\.)?huggingface\.co|hf\.co)\/.+|(www\.)?ollama\.com\/library\/[^:\/?#]+(:[^\/?#]+)?([\/?#].*)?)$

  • status
    object
    ClusterModelStatus reports preparation state, artifact digest, and resolved model metadata for a cluster-scoped ClusterModel.
    • status.artifact
      object
      • status.artifact.digest
        string
        Digest is the digest of the prepared OCI artifact.
      • status.artifact.kind
        string
        Kind is the artifact location kind exposed by the public API.

        Allowed values: OCI

      • status.artifact.mediaType
        string
        MediaType is the OCI artifact media type.
      • status.artifact.sizeBytes
        integer
        SizeBytes is the prepared OCI artifact size.

        Allowed values: 1 <= X

    • status.conditions
      array of objects
      • status.conditions.lastTransitionTime
        string
        lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
      • status.conditions.message
        string
        message is a human readable message indicating details about the transition. This may be an empty string.

        Maximum length: 32768

      • status.conditions.observedGeneration
        integer
        observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

        Allowed values: 0 <= X

      • status.conditions.reason
        string
        reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

        Length: 1..1024

        Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

      • status.conditions.status
        string
        status of the condition, one of True, False, Unknown.

        Allowed values: True, False, Unknown

      • status.conditions.type
        string
        type of condition in CamelCase or in foo.example.com/CamelCase.

        Maximum length: 316

        Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

    • status.observedGeneration
      integer
      ObservedGeneration is the latest metadata.generation reconciled by the controller.
    • status.phase
      string
      Phase is the high-level model preparation lifecycle phase.

      Allowed values: Pending, WaitForUpload, Publishing, Ready, Failed, Deleting

    • status.progress
      string
      Progress reports bounded controller-computed completion percentage for model preparation flows when runtime progress is available.
    • status.resolved
      object
      • status.resolved.architecture
        string
        Architecture is the model architecture when it is available.
      • status.resolved.contextWindowTokens
        integer
        ContextWindowTokens is the context window size when it is available.

        Allowed values: 1 <= X

      • status.resolved.family
        string
        Family is the model family inferred from source metadata.
      • status.resolved.format
        string
        Format is the resolved input format.

        Allowed values: Safetensors, GGUF, Diffusers

      • status.resolved.parameterCount
        integer
        ParameterCount is the number of model parameters when it is available.

        Allowed values: 1 <= X

      • status.resolved.quantization
        string
        Quantization is the model quantization when it is available.
      • status.resolved.sourceCapabilities
        object
        SourceCapabilities are provider-level capabilities discovered from source metadata.
        • status.resolved.sourceCapabilities.features
          array of strings
          Features are provider-specific feature names.
          • status.resolved.sourceCapabilities.features.Element of the array
            string

            Length: 1..128

        • status.resolved.sourceCapabilities.provider
          string
          Provider is the source provider that supplied the capabilities.

          Allowed values: HuggingFace, Ollama, Upload, Catalog

        • status.resolved.sourceCapabilities.tasks
          array of strings
          Tasks are provider-specific task names.
          • status.resolved.sourceCapabilities.tasks.Element of the array
            string

            Length: 1..128

      • status.resolved.supportedEndpointTypes
        array of strings
        • status.resolved.supportedEndpointTypes.Element of the array
          string

          Allowed values: Chat, TextGeneration, Embeddings, Rerank, SpeechToText, TextToSpeech, Translation, ImageClassification, ObjectDetection, ImageSegmentation, ImageToText, VisualQuestionAnswering, ImageGeneration, VideoGeneration, AudioGeneration

      • status.resolved.supportedFeatures
        array of strings
        • status.resolved.supportedFeatures.Element of the array
          string

          Allowed values: VisionInput, AudioInput, AudioOutput, ImageOutput, VideoInput, VideoOutput, MultiModalInput, ToolCalling

    • status.source
      object
      • status.source.catalog
        object
        Catalog contains frozen external catalog provenance for catalog imports.
        • status.source.catalog.catalogRevision
          string
          CatalogRevision is the upstream catalog revision used for resolution.
        • status.source.catalog.name
          string
          Name is the resolved public catalog model name.

          Minimal length: 1

        • status.source.catalog.remoteDigest
          string
          RemoteDigest is the pinned upstream OCI artifact digest.
        • status.source.catalog.sourceName
          string
          SourceName is the resolved ModelCatalogSource name.

          Minimal length: 1

        • status.source.catalog.version
          string
          Version is the resolved catalog version when one was selected.
      • status.source.resolvedRevision
        string
        ResolvedRevision is the source revision, tag, or digest when the provider exposes one.
      • status.source.resolvedType
        string
        ResolvedType is the source provider detected by the controller.

        Allowed values: HuggingFace, Ollama, Upload, Catalog

    • status.upload
      object
      • status.upload.expiresAt
        string
        ExpiresAt is the upload session expiration time.
      • status.upload.secretName
        string
        SecretName points to the Secret containing the upload URL and bearer token. The Secret key names are fixed by the controller contract and are not part of status.

        Minimal length: 1

      • status.upload.secretNamespace
        string
        SecretNamespace is the namespace of the Secret containing the upload URL and bearer token.

        Minimal length: 1

ModelCatalogSource

Scope: Cluster
Version: v1alpha1

ModelCatalogSource describes an external ClusterModel catalog. The controller can import selected entries as local Model or ClusterModel objects.
  • spec
    object
    ModelCatalogSourceSpec declares an external ClusterModel catalog.
    • spec.caSecretName
      string
      CASecretName names an optional d8-system Secret with ca.crt.

      Length: 1..253

      Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

    • spec.credentialsSecretName
      string

      Required value

      CredentialsSecretName names a d8-system Secret used for the semantic catalog API and grant exchange. The controller reads this Secret directly and never copies it into workload namespaces.

      Length: 1..253

      Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

    • spec.refreshInterval
      string
      RefreshInterval controls how often the controller refreshes catalog metadata. The controller uses a safe default when omitted.
    • spec.url
      string

      Required value

      URL is the HTTPS base URL of the remote catalog endpoint.

      Minimal length: 9

      Pattern: ^https:\/\/[^:\/?#@]+(:[0-9]+)?(\/[^?#]*)?$

  • status
    object
    ModelCatalogSourceStatus reports remote catalog health without embedding the remote inventory or secret material.
    • status.catalogRevision
      string
      CatalogRevision is the last successfully observed remote catalog revision.
    • status.conditions
      array of objects
      • status.conditions.lastTransitionTime
        string
        lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
      • status.conditions.message
        string
        message is a human readable message indicating details about the transition. This may be an empty string.

        Maximum length: 32768

      • status.conditions.observedGeneration
        integer
        observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

        Allowed values: 0 <= X

      • status.conditions.reason
        string
        reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

        Length: 1..1024

        Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

      • status.conditions.status
        string
        status of the condition, one of True, False, Unknown.

        Allowed values: True, False, Unknown

      • status.conditions.type
        string
        type of condition in CamelCase or in foo.example.com/CamelCase.

        Maximum length: 316

        Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

    • status.entryCount
      integer
      EntryCount is the number of active entries in the last successful refresh.

      Allowed values: 0 <= X

    • status.lastSuccessfulRefreshTime
      string
      LastSuccessfulRefreshTime is the time of the last successful catalog refresh.
    • status.observedGeneration
      integer
      ObservedGeneration is the latest metadata.generation reconciled by the controller.

Model

Scope: Namespaced
Version: v1alpha1

Model describes one namespace-scoped model prepared from a remote source, upload session, or external catalog. Workloads in the same namespace consume it with the top-level annotation ai.deckhouse.io/model after the model gets status.phase=Ready.
  • spec
    object
    ModelSpec declares the immutable source for one namespace-scoped model.
    • spec.source
      object

      Required value

      • spec.source.authSecretRef
        object
        AuthSecretRef names a Secret from the same namespace as the Model. It is supported for private Hugging Face sources.
        • spec.source.authSecretRef.name
          string

          Required value

          Name is the Secret name.

          Minimal length: 1

      • spec.source.catalog
        object
        Catalog imports a model entry from a ModelCatalogSource.
        • spec.source.catalog.name
          string

          Required value

          Name is the public catalog model name.

          Length: 1..253

          Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        • spec.source.catalog.sourceName
          string
          SourceName selects a ModelCatalogSource. When omitted, the controller may use the only Ready ModelCatalogSource in the cluster.

          Length: 1..253

          Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

        • spec.source.catalog.version
          string
          Version selects a catalog version when the upstream exposes more than one active version for the same name.

          Length: 1..128

      • spec.source.upload
        object
        Upload requests a controller-owned upload session for a local file or archive.
      • spec.source.url
        string
        URL points to a Hugging Face repository or an Ollama registry reference.

        Minimal length: 1

        Pattern: ^https:\/\/(((www\.)?huggingface\.co|hf\.co)\/.+|(www\.)?ollama\.com\/library\/[^:\/?#]+(:[^\/?#]+)?([\/?#].*)?)$

  • status
    object
    ModelStatus reports preparation state, upload session details, artifact digest, and resolved model metadata for a namespaced Model.
    • status.artifact
      object
      • status.artifact.digest
        string
        Digest is the digest of the prepared OCI artifact.
      • status.artifact.kind
        string
        Kind is the artifact location kind exposed by the public API.

        Allowed values: OCI

      • status.artifact.mediaType
        string
        MediaType is the OCI artifact media type.
      • status.artifact.sizeBytes
        integer
        SizeBytes is the prepared OCI artifact size.

        Allowed values: 1 <= X

    • status.conditions
      array of objects
      • status.conditions.lastTransitionTime
        string
        lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
      • status.conditions.message
        string
        message is a human readable message indicating details about the transition. This may be an empty string.

        Maximum length: 32768

      • status.conditions.observedGeneration
        integer
        observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

        Allowed values: 0 <= X

      • status.conditions.reason
        string
        reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

        Length: 1..1024

        Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

      • status.conditions.status
        string
        status of the condition, one of True, False, Unknown.

        Allowed values: True, False, Unknown

      • status.conditions.type
        string
        type of condition in CamelCase or in foo.example.com/CamelCase.

        Maximum length: 316

        Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

    • status.observedGeneration
      integer
      ObservedGeneration is the latest metadata.generation reconciled by the controller.
    • status.phase
      string
      Phase is the high-level model preparation lifecycle phase.

      Allowed values: Pending, WaitForUpload, Publishing, Ready, Failed, Deleting

    • status.progress
      string
      Progress reports bounded controller-computed completion percentage for upload and model preparation flows when runtime progress is available.
    • status.resolved
      object
      • status.resolved.architecture
        string
        Architecture is the model architecture when it is available.
      • status.resolved.contextWindowTokens
        integer
        ContextWindowTokens is the context window size when it is available.

        Allowed values: 1 <= X

      • status.resolved.family
        string
        Family is the model family inferred from source metadata.
      • status.resolved.format
        string
        Format is the resolved input format.

        Allowed values: Safetensors, GGUF, Diffusers

      • status.resolved.parameterCount
        integer
        ParameterCount is the number of model parameters when it is available.

        Allowed values: 1 <= X

      • status.resolved.quantization
        string
        Quantization is the model quantization when it is available.
      • status.resolved.sourceCapabilities
        object
        SourceCapabilities are provider-level capabilities discovered from source metadata.
        • status.resolved.sourceCapabilities.features
          array of strings
          Features are provider-specific feature names.
          • status.resolved.sourceCapabilities.features.Element of the array
            string

            Length: 1..128

        • status.resolved.sourceCapabilities.provider
          string
          Provider is the source provider that supplied the capabilities.

          Allowed values: HuggingFace, Ollama, Upload, Catalog

        • status.resolved.sourceCapabilities.tasks
          array of strings
          Tasks are provider-specific task names.
          • status.resolved.sourceCapabilities.tasks.Element of the array
            string

            Length: 1..128

      • status.resolved.supportedEndpointTypes
        array of strings
        • status.resolved.supportedEndpointTypes.Element of the array
          string

          Allowed values: Chat, TextGeneration, Embeddings, Rerank, SpeechToText, TextToSpeech, Translation, ImageClassification, ObjectDetection, ImageSegmentation, ImageToText, VisualQuestionAnswering, ImageGeneration, VideoGeneration, AudioGeneration

      • status.resolved.supportedFeatures
        array of strings
        • status.resolved.supportedFeatures.Element of the array
          string

          Allowed values: VisionInput, AudioInput, AudioOutput, ImageOutput, VideoInput, VideoOutput, MultiModalInput, ToolCalling

    • status.source
      object
      • status.source.catalog
        object
        Catalog contains frozen external catalog provenance for catalog imports.
        • status.source.catalog.catalogRevision
          string
          CatalogRevision is the upstream catalog revision used for resolution.
        • status.source.catalog.name
          string
          Name is the resolved public catalog model name.

          Minimal length: 1

        • status.source.catalog.remoteDigest
          string
          RemoteDigest is the pinned upstream OCI artifact digest.
        • status.source.catalog.sourceName
          string
          SourceName is the resolved ModelCatalogSource name.

          Minimal length: 1

        • status.source.catalog.version
          string
          Version is the resolved catalog version when one was selected.
      • status.source.resolvedRevision
        string
        ResolvedRevision is the source revision, tag, or digest when the provider exposes one.
      • status.source.resolvedType
        string
        ResolvedType is the source provider detected by the controller.

        Allowed values: HuggingFace, Ollama, Upload, Catalog

    • status.upload
      object
      • status.upload.expiresAt
        string
        ExpiresAt is the upload session expiration time.
      • status.upload.secretName
        string
        SecretName points to the Secret containing the upload URL and bearer token. The Secret key names are fixed by the controller contract and are not part of status.

        Minimal length: 1

      • status.upload.secretNamespace
        string
        SecretNamespace is the namespace of the Secret containing the upload URL and bearer token.

        Minimal length: 1