> For the complete documentation index, see [llms.txt](https://docs.valohai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valohai.com/data/kubernetes-volumes/shared-volumes.md).

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

```yaml
- 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.valohai.com/data/kubernetes-volumes/shared-volumes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.