From 95ae71ddebb66f78043e26ba4babac04e430e66e Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov Date: Thu, 24 Sep 2026 11:52:21 +0200 Subject: [PATCH 1/3] Clarify Kubernetes volume context selection --- mkdocs/docs/concepts/volumes.md | 16 +++++++++++++--- mkdocs/docs/reference/dstack.yml/volume.md | 8 ++++++++ 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/mkdocs/docs/concepts/volumes.md b/mkdocs/docs/concepts/volumes.md index da0c0254c..d9d06e2c8 100644 --- a/mkdocs/docs/concepts/volumes.md +++ b/mkdocs/docs/concepts/volumes.md @@ -43,13 +43,19 @@ 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`: + With the `kubernetes` backend, set `region` to an enabled kubeconfig context name from the + [backend configuration](backends.md#kubernetes), even if only one context is enabled. + You can omit `region` only with the legacy backend configuration without `contexts`, which + uses the kubeconfig's `current-context` and the backend's `namespace` setting. + + You can optionally specify `storage_class_name` and/or `access_modes`:
```yaml type: volume backend: kubernetes + region: gpu-cluster-a name: my-volume size: 100GB @@ -57,7 +63,8 @@ If you use this configuration, `dstack` will create a new volume based on the sp
- This automatically creates a `PersistentVolumeClaim` and associates it with the volume. + This creates a `PersistentVolumeClaim` in the selected context's namespace and associates it + with the volume. If you don't specify `storage_class_name`, the decision is delegated to the `DefaultStorageClass` admission controller, if enabled. @@ -110,13 +117,16 @@ 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`: + With the `kubernetes` backend, to reuse an existing `PersistentVolumeClaim`, specify its name + in `claim_name` and select its cluster with `region`, as when creating a volume. + The claim must exist in the selected context's namespace.
```yaml type: volume backend: kubernetes + region: gpu-cluster-a name: my-volume claim_name: existing-pvc diff --git a/mkdocs/docs/reference/dstack.yml/volume.md b/mkdocs/docs/reference/dstack.yml/volume.md index d3f851c8c..c1fbca8db 100644 --- a/mkdocs/docs/reference/dstack.yml/volume.md +++ b/mkdocs/docs/reference/dstack.yml/volume.md @@ -30,11 +30,18 @@ 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. + Set `region` to an enabled kubeconfig context name from the + [backend configuration](../../concepts/backends.md#kubernetes), even if only one context is enabled. + The claim is created or looked up in that context's namespace. + You can omit `region` only with the legacy backend configuration without `contexts`, which + uses the kubeconfig's `current-context` and the backend's `namespace` setting. + 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 @@ -51,6 +58,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 ``` From 26d22abb72e4994a57abb780c5a8e36a495e61ff Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov Date: Thu, 24 Sep 2026 13:58:13 +0200 Subject: [PATCH 2/3] Tighten Kubernetes volume documentation --- mkdocs/docs/concepts/volumes.md | 12 ++++-------- mkdocs/docs/reference/dstack.yml/volume.md | 7 ++----- 2 files changed, 6 insertions(+), 13 deletions(-) diff --git a/mkdocs/docs/concepts/volumes.md b/mkdocs/docs/concepts/volumes.md index d9d06e2c8..be7128b8a 100644 --- a/mkdocs/docs/concepts/volumes.md +++ b/mkdocs/docs/concepts/volumes.md @@ -43,10 +43,8 @@ size: 100GB If you use this configuration, `dstack` will create a new volume based on the specified options. ??? info "Kubernetes" - With the `kubernetes` backend, set `region` to an enabled kubeconfig context name from the - [backend configuration](backends.md#kubernetes), even if only one context is enabled. - You can omit `region` only with the legacy backend configuration without `contexts`, which - uses the kubeconfig's `current-context` and the backend's `namespace` setting. + 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`: @@ -63,8 +61,7 @@ If you use this configuration, `dstack` will create a new volume based on the sp
- This creates a `PersistentVolumeClaim` in the selected context's namespace and associates it - with the volume. + This creates a `PersistentVolumeClaim` in the context's namespace. If you don't specify `storage_class_name`, the decision is delegated to the `DefaultStorageClass` admission controller, if enabled. @@ -117,8 +114,7 @@ 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` and select its cluster with `region`, as when creating a volume. + To reuse an existing `PersistentVolumeClaim`, specify `claim_name` and `region`. The claim must exist in the selected context's namespace.
diff --git a/mkdocs/docs/reference/dstack.yml/volume.md b/mkdocs/docs/reference/dstack.yml/volume.md index c1fbca8db..5ba492770 100644 --- a/mkdocs/docs/reference/dstack.yml/volume.md +++ b/mkdocs/docs/reference/dstack.yml/volume.md @@ -30,11 +30,8 @@ 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. - Set `region` to an enabled kubeconfig context name from the - [backend configuration](../../concepts/backends.md#kubernetes), even if only one context is enabled. - The claim is created or looked up in that context's namespace. - You can omit `region` only with the legacy backend configuration without `contexts`, which - uses the kubeconfig's `current-context` and the backend's `namespace` setting. + With `contexts` configured in the [backend](../../concepts/backends.md#kubernetes), set `region` to a kubeconfig context name. + Claims use that context's namespace. To create a new claim, specify `size` and optionally `storage_class_name` and/or `access_modes`: From d15642615b9a59c85b5125e6eb1777e4ace1b156 Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov Date: Thu, 24 Sep 2026 14:03:11 +0200 Subject: [PATCH 3/3] Remove redundant Kubernetes namespace notes --- mkdocs/docs/concepts/volumes.md | 3 +-- mkdocs/docs/reference/dstack.yml/volume.md | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/mkdocs/docs/concepts/volumes.md b/mkdocs/docs/concepts/volumes.md index be7128b8a..19be81952 100644 --- a/mkdocs/docs/concepts/volumes.md +++ b/mkdocs/docs/concepts/volumes.md @@ -61,7 +61,7 @@ If you use this configuration, `dstack` will create a new volume based on the sp
- This creates a `PersistentVolumeClaim` in the context's namespace. + This automatically creates a `PersistentVolumeClaim` and associates it with the volume. If you don't specify `storage_class_name`, the decision is delegated to the `DefaultStorageClass` admission controller, if enabled. @@ -115,7 +115,6 @@ If you register an existing volume, you must ensure the volume already has a fil ??? info "Kubernetes" To reuse an existing `PersistentVolumeClaim`, specify `claim_name` and `region`. - The claim must exist in the selected context's namespace.
diff --git a/mkdocs/docs/reference/dstack.yml/volume.md b/mkdocs/docs/reference/dstack.yml/volume.md index 5ba492770..23eccccd1 100644 --- a/mkdocs/docs/reference/dstack.yml/volume.md +++ b/mkdocs/docs/reference/dstack.yml/volume.md @@ -31,7 +31,6 @@ 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. - Claims use that context's namespace. To create a new claim, specify `size` and optionally `storage_class_name` and/or `access_modes`: