[Defilan]

What

Adds a "vLLM and SGLang: safetensors checkpoints" section to docs/site/guides/air-gapped.md, and corrects stale statements on the same page.

• Stage and verify: download one pinned commit, verify every file against the Hub's digests (hf cache verify, or a short stdlib-only Python script), build a sha256 manifest, verify again on the target, and check for custom code before transfer.
• Option A: a static NFS PersistentVolume, a pre-bound PVC and a pvc:// directory source, with a complete PV / PVC / Model / InferenceService example (vLLM, Qwen/Qwen3-8B-FP8 pinned to a commit).
• Option B: an internal S3-compatible store with an s3:// prefix, spec.files and spec.fileSha256 (using the Hub's real LFS digests), and spec.format: safetensors set explicitly.
• Mirroring the runtime images and pinning digests through runtimeImages.*.
• Gotchas: a memory-backed /dev/shm through spec.extraVolumes / spec.extraVolumeMounts for tensor parallel > 1, the vLLM served model name, HF_HUB_OFFLINE, and leaving skipModelInit unset.

Corrections elsewhere on the page: Step 3 uses the chart value controllerManager.caCertConfigMap instead of patching the Deployment; the note saying there is no Hugging Face repo-ID source was wrong (hf:// and bare org/repo exist but need Hub egress); a single-file pvc:// source can set spec.sha256; a new storage-strategy row.

Why

The guide only covered single GGUF files, so a cluster whose security policy blocks Hugging Face had no documented path for vLLM or SGLang, which serve a checkpoint directory.

Fixes #1992

How

Every behaviour claim was checked against the code: model_storage.go (pvc:// directory resolution), model_controller.go, deployment_builder.go, runtime_vllm.go / runtime_sglang.go, and the CRD validation rules. Some behaviour worth knowing that the section now documents:

• spec.sha256 on a pvc:// directory fails the pod (the verify step refuses directories), and pvc:// with spec.files ends up Failed/InvalidFileSet, so a pvc:// checkpoint gets no in-cluster digest check; the guide points to the s3:// option when one is needed.
• An oci:// source hands the runtime a file path inside the artifact rather than the tree root, so it does not fit safetensors today.
• vLLM gets no --served-model-name unless extraArgs adds one, so its model id is otherwise the mount path.

Validation: every YAML block passes scripts/validate-samples.py, and all objects (PV, PVC, both Models, both InferenceServices) pass kubectl apply --dry-run=server against a local test API server loaded with config/crd/bases; two deliberately broken Models were rejected by the CRD rules. The verification script and the manifest / sha256sum -c commands were run against a real small Hub repo, including a tampered file and a branch name in place of a commit. make validate-samples (41) and make check-agents-md pass.

AI assistance: drafted and verified with Claude Code (Claude Opus) under the maintainer's direction; the maintainer owns review.

Checklist

• Tests added/updated (docs only)
• make test passes locally (docs only, not run)
• make lint passes locally (docs only, not run)
• Commit messages follow conventional commits
• All commits are signed off (git commit -s) per DCO
• AI assistance (if any) is disclosed above, per CONTRIBUTING.md
• Documentation updated (if user-facing change)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!