diff --git a/docs/getting-started.md b/docs/getting-started.md index b83ddfa..6d048d0 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -40,7 +40,7 @@ This section lists the core infrastructure components that ModelPack is working - **[Model CSI Driver](https://github.com/modelpack/model-csi-driver)**: Kubernetes CSI driver for mounting model artifacts as persistent volumes - **[OCI Volume Sources](https://kubernetes.io/blog/2024/08/16/kubernetes-1-31-image-volume-source/)**: Mount model artifacts directly as volumes in Kubernetes pods without init containers -- **[CRI-O](https://cri-o.io/)**: Container runtime that supports OCI artifacts, enabling seamless model deployment in Kubernetes environments +- **[CRI-O](https://cri-o.io/)**: Container runtime that supports OCI artifacts, enabling seamless model deployment in Kubernetes environments. Runtime support varies; see [Runtime Compatibility](./runtime-compatibility.md) for which runtimes support ModelPack artifact mounts. ## Key Benefits @@ -98,12 +98,15 @@ spec: This example shows how to mount a model artifact directly into a Kubernetes pod using the model CSI driver. The contents of the model are available within the /model directory within the running pod. +The CSI driver works on any container runtime; for native image volumes, see [Runtime Compatibility](./runtime-compatibility.md). + ## Next Steps 1. **Get hands-on experience**: Follow the step-by-step guides for [modctl](./modctl.md) or [AIKit](./aikit.md) 2. **Explore the [full ModelPack specification](./spec.md)** for technical implementation details 3. **Join the community** on [CNCF Slack #modelpack](https://cloud-native.slack.com/archives/C07T0V480LF) 4. **Contribute** to the ModelPack project - see our [contributing guidelines](../CONTRIBUTING.md) +5. **Check [Runtime Compatibility](./runtime-compatibility.md)** for current runtime support ## Additional Resources diff --git a/docs/runtime-compatibility.md b/docs/runtime-compatibility.md new file mode 100644 index 0000000..2a07d8a --- /dev/null +++ b/docs/runtime-compatibility.md @@ -0,0 +1,66 @@ +# Runtime Compatibility + +There are two ways to get a ModelPack artifact into a Kubernetes pod: + +1. **Kubernetes image volumes** ([KEP-4639](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/)) — the container runtime pulls and mounts the artifact directly. Support for ModelPack artifacts varies by runtime; see the matrix below. +2. **[Model CSI Driver](https://github.com/modelpack/model-csi-driver)** — a runtime-independent path that works on any CRI runtime and older Kubernetes versions. + +_Last reviewed: 2026-10-28. Status tracked in [#233](https://github.com/modelpack/model-spec/issues/233)._ + +## Kubernetes Requirements + +[Image volumes](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/) (the `volumes[].image` field) require: + +| Kubernetes version | Status | Notes | +|---|---|---| +| 1.31 | Alpha | Feature gate `ImageVolume` must be enabled | +| 1.33 | Beta (off by default) | `subPath`/`subPathExpr` supported | +| ~1.35 | Beta (on by default) | Exact version unconfirmed; see [KEP-4639](https://github.com/kubernetes/enhancements/issues/4639) | +| 1.36+ | GA | Enabled by default | + +## Runtime Matrix + +| Runtime | Min version | ModelPack artifact mounts | Notes | +|---|---|---|---| +| CRI-O | v1.33.0 | Yes | Raw layers only (see [Layer format notes](#layer-format-notes)). Each layer is mounted as a single file, named by the `org.opencontainers.image.title` OCI annotation (standard, not project-specific) or `org.cncf.model.filepath` (see [annotations.md](./annotations.md)) if present; layers with neither annotation are skipped. Can be disabled via CRI-O config. ([cri-o#8953](https://github.com/cri-o/cri-o/pull/8953), [cri-o#9062](https://github.com/cri-o/cri-o/pull/9062), [cri-o#9131](https://github.com/cri-o/cri-o/pull/9131)) | +| containerd | — | No | Tracked in [containerd/containerd#11381](https://github.com/containerd/containerd/issues/11381). Use the Model CSI Driver in the meantime. | +| moby / Docker Engine | — | No | Tracked in [moby/moby#49591](https://github.com/moby/moby/issues/49591). Use the Model CSI Driver in the meantime. | +| Model CSI Driver | v0.1.x | Yes | Runtime-independent. Works with any CRI runtime and compatible with older Kubernetes versions. Pulls and unpacks layers itself; supports P2P distribution via Dragonfly. | + +## Layer Format Notes + +CRI-O mounts each layer blob as a single file — it does **not** extract `.tar`, `.tar+gzip`, or `.tar+zstd` layers. Only `*.raw` media types result in a usable file on the mount path. + +For CRI-O image volumes, use `application/vnd.cncf.model.weight.v1.raw` (or other `*.raw` variants) and set the `org.cncf.model.filepath` annotation on each layer so CRI-O names the mounted file correctly. See [annotations.md](./annotations.md) for the full annotation reference. + +When packaging a model, ensure layers use `*.raw` media types. Consult your build tool's documentation for how to configure the layer format. + +## Example: Image Volume with CRI-O + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: model-server +spec: + containers: + - name: server + image: myregistry.com/myserver:latest + volumeMounts: + - name: model + mountPath: /model + readOnly: true + volumes: + - name: model + image: + reference: myregistry.com/mymodel:v1.0 + pullPolicy: IfNotPresent +``` + +## Model CSI Driver + +The Model CSI Driver is the recommended path on containerd- or Docker-based nodes, or on Kubernetes older than 1.31. It handles both raw and tar layers independently of the container runtime. + +See the [Model CSI Driver repository](https://github.com/modelpack/model-csi-driver) for installation and usage, including Helm-based deployment. + +For the CSI driver usage example, see [Use Models in Kubernetes](./getting-started.md#use-models-in-kubernetes). diff --git a/docs/spec.md b/docs/spec.md index 911f94f..4661d37 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -172,7 +172,7 @@ The generated artifact can then be pushed to OCI registries (e.g., Harbor, Docke ### PULL & SERVE -Once the model artifact is stored in an OCI registry, the container runtime (e.g., containerd, CRI-O) can pull it from the OCI registry and mount it as a read-only volume during the model serving process, if required. +Once the model artifact is stored in an OCI registry, a supporting container runtime or the Model CSI Driver can pull it from the OCI registry and mount it as a read-only volume during the model serving process, if required. See [Runtime Compatibility](./runtime-compatibility.md) for current runtime support. ![pull-serve](./img/pull-and-serve.png)