Shared Volumes

A shared volume mounts a persistent volume claim that already exists in your cluster into every replica of a deployment endpoint. All replicas see the same files, and the files are there before the endpoint starts and stay after it stops.

Shared volumes apply to deployment endpoints on Kubernetes deployment targets.

When you need one

• Your replicas load the same model files and you do not want each replica to download its own copy.

• You keep a reference dataset or a lookup table that the endpoint reads at request time.

• Something outside Valohai writes data that the endpoint needs to read.

When each replica needs its own empty disk instead, use a workspace volume.

Before you start

Create the persistent volume claim in the namespace of the deployment target, or ask your cluster administrator to create it, and put the data on it. Use a ReadWriteMany claim so that every replica can mount it at the same time.

Add a shared volume to an endpoint

1. Create a new deployment version.

2. Open the resource configuration of the endpoint.

3. Find the Shared Volumes row and select a claim from the list.

4. Enter the mount path, the absolute path inside the container where the volume appears, for example /models.

5. Optionally enter a sub-path to mount only one directory from the claim rather than the whole thing.

6. Select read only if the endpoint should not be able to write to the volume.

You can add several shared volumes to the same endpoint. Each one needs its own mount path, and no shared volume may use the same mount path as the workspace volume of that endpoint.

The configured volumes are listed on the endpoint details page after the version is created.

Define them in valohai.yaml

Valohai pre-fills the deployment version form from the YAML whenever the request does not set the field itself, so the configuration stays in version control.

- endpoint:
    name: predict
    image: python:3.13
    server-command: python predict.py
    shared-volumes:
      - pvc-name: shared-models
        mount-path: /models
        sub-path: predict
        read-only: true

sub-path and read-only are optional. A sub-path must be relative to the root of the claim.

What to expect

A shared volume is ordinary storage. Valohai mounts it and nothing more, so its contents, its size and its lifetime are yours to manage. Mounting it read only is the safest default when the endpoint only needs to read, because it stops one replica from corrupting data that every other replica depends on.

Shared volumes require a deployment target that supports persistent storage. They are not available on public deployment targets.

Troubleshooting

• Replicas stay pending.

  • The claim may not exist in the namespace of the deployment target, or it may not be ReadWriteMany, in which case only replicas on one node can mount it.

• The endpoint cannot write to the volume.

  • Check whether read only is selected. If it is not, make sure the user that your image runs as has write permission to the data on the claim.

• Saving a deployment version fails with a mount path conflict.

  • Two volumes on the endpoint are using the same mount path. Mount paths must be unique across shared volumes and the workspace volume.