Allow configurable modelArtifacts readOnly for PVC mounts

Add a modelArtifacts.readOnly value and wire it into PVC volume and volumeMount rendering so pvc+hf deployments can opt into writable mounts for Hugging Face cache metadata while keeping read-only defaults.

Signed-off-by: Kay Yan <kay.yan@daocloud.io>

Author: yankay

charts/llm-d-modelservice/templates/_helpers.tpl

@@ -373,7 +373,7 @@ Context is .Values.modelArtifacts
 - name: model-storage
   persistentVolumeClaim:
     claimName: {{ $claim }}
-    readOnly: true
+    readOnly: {{ .readOnly }}
 {{- else if eq $protocol "oci" }}
 - name: model-storage
   image:
@@ -398,12 +398,13 @@ volumeMounts:
 {{- if .container.mountModelVolume }}
   - name: model-storage
     mountPath: {{ .Values.modelArtifacts.mountPath }}
-{{- /* enforce readOnly volumeMounts for OCI and PVCs */}}
+{{- /* enforce readOnly volumeMounts for OCI and PVC variants */}}
 {{- $parsedArtifacts := regexSplit "://" .Values.modelArtifacts.uri -1 -}}
 {{- $protocol := first $parsedArtifacts -}}
-{{- $path := last $parsedArtifacts -}}
-{{- if or (eq $protocol "oci") (eq $protocol "pvc") }}
+{{- if eq $protocol "oci" }}
     readOnly: true
+{{- else if hasPrefix "pvc" $protocol }}
+    readOnly: {{ .Values.modelArtifacts.readOnly }}
 {{- end -}}
 {{- end }}
 {{- end }}

charts/llm-d-modelservice/values.schema.json

@@ -1955,6 +1955,12 @@
                     "title": "mountPath",
                     "type": "string"
                 },
+                "readOnly": {
+                    "default": true,
+                    "description": "Whether model volume mounts should be read-only. Set to false for pvc+hf:// when Hugging Face cache writes are needed.",
+                    "title": "readOnly",
+                    "type": "boolean"
+                },
                 "name": {
                     "default": "random/model",
                     "description": " Required",

charts/llm-d-modelservice/values.yaml

@@ -76,6 +76,9 @@ modelArtifacts:
   authSecretName: ""
   # location where model volume will be mounted (used when mountModelVolume: true)
   mountPath: /model-cache
+  # Whether model volume mounts should be read-only.
+  # Set to false for pvc+hf:// when Hugging Face cache writes are needed.
+  readOnly: true
 
 # When true, a LeaderWorkerSet is used instead of a Deployment
 multinode: false

examples/output-dra.yaml

@@ -108,6 +108,7 @@ spec:
           volumeMounts:
             - name: model-storage
               mountPath: /model-cache
+              readOnly: true
 ---
 # Source: llm-d-modelservice/templates/resource-claim-template.yaml
 apiVersion: resource.k8s.io/v1

examples/output-gaudi.yaml

@@ -101,3 +101,4 @@ spec:
           volumeMounts:
             - name: model-storage
               mountPath: /model-cache
+              readOnly: true

examples/output-pvc-hf.yaml

@@ -121,6 +121,7 @@ spec:
           volumeMounts:
             - name: model-storage
               mountPath: /model-cache
+              readOnly: true
 ---
 # Source: llm-d-modelservice/templates/prefill-deployment.yaml
 apiVersion: apps/v1
@@ -214,3 +215,4 @@ spec:
           volumeMounts:
             - name: model-storage
               mountPath: /model-cache
+              readOnly: true

examples/pvc/README.md

@@ -86,8 +86,8 @@ Note that the path after the `<pvc-name>` is the path on the PVC which the downl
 Make sure that for the container of your interst in `prefill.containers` or `decode.containers`, there's a field called `mountModelVolume: true` ([see example](../values-pd.yaml#L87)) for the volume mounts to be created correctly.
 
 ### Behavior
-- A read-only PVC volume with the name `model-storage` is created for the deployment
-- A read-only volumeMount with the mountPath: `model-cache` is created for each container where `mountModelVolume: true`
+- A PVC volume with the name `model-storage` is created for the deployment (read-only by default)
+- A volumeMount with the mountPath: `model-cache` is created for each container where `mountModelVolume: true` (read-only by default)
 - `--model` arg for that container is set to `model-cache/<path/to/model>` where `mountModelVolume: true`
 
 ⚠️ You do **not** need to configure volumeMounts for containers where  `mountModelVolume: true`. ModelService will automatically populate the pod specification and mount the model files.
@@ -96,7 +96,7 @@ However, if you want to add your own volume specifications, you may do so under
 
 💡 You may optionally set the `--served-model-name`  in your container to be used for the OpenAI request, otherwise the request name must be a long string like `"model": "model-cache/<path/to/model>"`. Note that this argument is added automatically using the option `modelCommand: vllmServe` or `imageDefault`, using `routing.modelName` as the value to the `--served-model-name` argument.
 
-> For security purposes, a read-only volume is mounted to the pods to prevent a pod from deleting the model files in case another model service installation uses the same PVC. If you would like to write to the PVC, you should not do so through ModelService, but rather through your own pod like the download-model/pvc-debugger without the read-only restriction.
+> For security, this chart mounts model volumes as read-only by default to prevent accidental deletion or mutation when a PVC is shared. If your workflow needs writes (for example, Hugging Face cache lock files), set `modelArtifacts.readOnly: false`.
 
 
 ## Use HF-downloaded models with PVCs
@@ -121,7 +121,15 @@ helm install pvc-hf-example llm-d-modelservice/llm-d-modelservice \
 Make sure that for the container of your interst in `prefill.containers` or `decode.containers`, there's a field called `mountModelVolume: true` ([see example](../values-pd.yaml#L87)) for the volume mounts to be created correctly.
 
 ### Behavior
-- A read-only PVC volume with the name `model-storage` is created for the deployment
-- A read-only volumeMount with the mountPath: `model-cache` is created for each container where `mountModelVolume: true`
+- A PVC volume with the name `model-storage` is created for the deployment (read-only by default)
+- A volumeMount with the mountPath: `model-cache` is created for each container where `mountModelVolume: true` (read-only by default)
 - `HF_HUB_CACHE` environment variable for that container is set to `model-cache/path/to/hf_hub_cache` where `mountModelVolume: true`
 - `--model` arugment is set to `facebook/opt-125m`
+
+If your runtime needs to write Hugging Face cache metadata or lock files, set:
+
+```yaml
+modelArtifacts:
+  uri: pvc+hf://pvc-name/path/to/hf_hub_cache/namespace/modelID
+  readOnly: false
+```