Custom Resources

ClusterModel

Scope: Cluster
Version: v1alpha1

• 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 preparation lifecycle phase, reported together with Conditions.

    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

    Resolved carries the model metadata the controller derived from the source.
    • 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

• spec

  object

  ModelCatalogSourceSpec declares an external ClusterModel catalog. The backend is selected by spec.type: a cluster-to-cluster catalog URL (default), or the Hugging Face provider index.
  • 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

    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. Used by the Catalog backend.

    Length: 1..253

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

  • spec.huggingFace

    object

    HuggingFace configures the Hugging Face provider backend. Allowed only when type is HuggingFace.
    • spec.huggingFace.tokenSecretName

      string

      TokenSecretName names an optional d8-system Secret with key token used for gated or private models. Listing and importing public models works anonymously when omitted.

      Length: 1..253

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

  • spec.policy

    object

    Policy defines required bounds for provider indexing and import eligibility. A source that omits scope or exceeds these bounds must stay blocked instead of starting an unbounded provider scan.
    • spec.policy.allowedCollections

      array of strings

      AllowedCollections limits synchronization to specific provider collections, playlists, or curated sets.
      • spec.policy.allowedCollections.Element of the array

        string

        Length: 1..128

    • spec.policy.allowedOrganizations

      array of strings

      AllowedOrganizations limits synchronization to specific provider organizations or namespaces.
      • spec.policy.allowedOrganizations.Element of the array

        string

        Length: 1..128

    • spec.policy.allowedRepositories

      array of strings

      AllowedRepositories limits synchronization to specific provider repositories.
      • spec.policy.allowedRepositories.Element of the array

        string

        Length: 1..256

    • spec.policy.allowedTags

      array of strings

      AllowedTags limits synchronization to remote entries matching at least one of the selected provider tags.
      • spec.policy.allowedTags.Element of the array

        string

        Length: 1..64

    • spec.policy.maxIndexedEntries

      integer

      MaxIndexedEntries caps how many remote entries one source may index.

      Allowed values: 1 <= X <= 10000

    • spec.policy.maxMetadataBytes

      integer

      MaxMetadataBytes caps how much normalized metadata may be stored per indexed remote entry.

      Allowed values: 1024 <= X <= 1048576

    • spec.policy.refreshBudget

      string

      RefreshBudget limits how long one refresh attempt may spend on provider indexing work before it yields and retries later.
  • spec.refreshInterval

    string

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

    string

    Type selects the catalog source backend. Defaults to Catalog (cluster-to-cluster). Existing sources without a type are treated as Catalog.

    Default: Catalog

    Allowed values: Catalog, HuggingFace

  • spec.url

    string

    URL is the HTTPS base URL of the remote catalog endpoint. Required when type is Catalog.

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

    string

    NextRetryTime is the next scheduled retry after provider, policy, or data-service failures when the controller is waiting before the next sync attempt.
  • status.observedGeneration

    integer

    ObservedGeneration is the latest metadata.generation reconciled by the controller.

Model

Scope: Namespaced
Version: v1alpha1

• 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 preparation lifecycle phase, reported together with Conditions.

    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

    Resolved carries the model metadata the controller derived from the source.
    • 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