Skip to content

Clarify Kubernetes volume context selection #4311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
peterschmidt85 merged 3 commits into from
Sep 24, 2026
+11 −2
Merged

Clarify Kubernetes volume context selection #4311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
95ae71d
Clarify Kubernetes volume context selection
Sep 24, 2026
26d22ab
Tighten Kubernetes volume documentation
Sep 24, 2026
d156426
Remove redundant Kubernetes namespace notes
Sep 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions mkdocs/docs/concepts/volumes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,17 @@ size: 100GB
If you use this configuration, `dstack` will create a new volume based on the specified options.

??? info "Kubernetes"
With the `kubernetes` backend, you don't have to specify `region`, but you can optionally specify `storage_class_name` and/or `access_modes`:
Set `region` to a kubeconfig context name enabled in the [backend configuration](backends.md#kubernetes).
Omit it only for legacy configurations without `contexts`.

You can optionally specify `storage_class_name` and/or `access_modes`:

<div editor-title="volume.dstack.yml">

```yaml
type: volume
backend: kubernetes
region: gpu-cluster-a
name: my-volume

size: 100GB
Expand Down Expand Up @@ -110,13 +114,14 @@ If you register an existing volume, you must ensure the volume already has a fil

??? info "Kubernetes"

With the `kubernetes` backend, to reuse an existing `PersistentVolumeClaim`, specify its name in `claim_name`:
To reuse an existing `PersistentVolumeClaim`, specify `claim_name` and `region`.

<div editor-title="volume.dstack.yml">

```yaml
type: volume
backend: kubernetes
region: gpu-cluster-a
name: my-volume

claim_name: existing-pvc
Expand Down
4 changes: 4 additions & 0 deletions mkdocs/docs/reference/dstack.yml/volume.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,14 @@ The `volume` configuration type allows creating, registering, and updating [volu

Kubernetes backend volumes are mapped to [`PersistentVolumeClaim`](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) objects.

With `contexts` configured in the [backend](../../concepts/backends.md#kubernetes), set `region` to a kubeconfig context name.

To create a new claim, specify `size` and optionally `storage_class_name` and/or `access_modes`:

```yaml
type: volume
backend: kubernetes
region: gpu-cluster-a
name: new-volume
size: 100GB
# By default, storage_class_name is not set, and the decision is delegated to
Expand All @@ -51,6 +54,7 @@ The `volume` configuration type allows creating, registering, and updating [volu
```yaml
type: volume
backend: kubernetes
region: gpu-cluster-a
name: existing-volume
claim_name: existing-pvc
```
Expand Down
Loading