From 8923b73fec8faa817368a9d94668f45a60828ec9 Mon Sep 17 00:00:00 2001 From: Dmitry Meyer Date: Wed, 11 Feb 2026 14:28:07 +0000 Subject: [PATCH 1/2] [Docs] Clarify how K8s resources and offers work --- docs/docs/concepts/backends.md | 59 +++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/docs/concepts/backends.md b/docs/docs/concepts/backends.md index da58f36e0..8243338fb 100644 --- a/docs/docs/concepts/backends.md +++ b/docs/docs/concepts/backends.md @@ -1060,7 +1060,64 @@ projects: Ensure you've created a ClusterRoleBinding to grant the role to the user or the service account you're using. -> To learn more, see the [Lambda](../../examples/clusters/lambda/#kubernetes) and [Lambda](../../examples/clusters/crusoe/#kubernetes) examples. +??? info "Resources and offers" + [Resources](../concepts/tasks.md#resources) specified in the run configuration are translated to Kubernetes + [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) as follows: + + - As with other backends, an exact value is translated to a range with the same lower and upper limits, + e.g., `cpu: 4` is the same as `cpu: 4..4`. + - The lower limit, if set, is used as a resource request, meaning that it is guaranteed that the container has at least the specified + amount of the resource. + - For resources other than `gpu`, the upper limit, if set, is used as a resource limit, meaning that the container is not allowed + to consume more resources than specified. If the upper limit is not set, the resource limit is also not set. + - For `gpu` resources, the upper limit is always ignored, and the resource limit is always set to the same value as the resource request, + that is, to the lower limit of the range. + + For example, the following resources specification: + +
+ + ```yaml + resources: + cpu: 32..64 + memory: 1024GB + disk: 100GB.. + gpu: nvidia:4..8 + ``` + +
+ + is translated to: + + | resource | request | limit | + |---------------------|----------|-----------| + | `cpu` | `32` | `64` | + | `memory` | `1024Gi` | `1024Gi` | + | `ephemeral-storage` | `100Gi` | _not set_ | + | `nvidia.com/gpu` | `4` | `4` | + + In offers, `dstack` uses resource requests as offer's resources. + With the resources spec as in the example above, offers would look like the following, + even if nodes have more available resources: + + ``` + # BACKEND RESOURCES INSTANCE TYPE PRICE + 1 kubernetes (-) cpu=32 mem=1024GB disk=100GB H100:80GB:4 h100x8 $0 + ``` + + As a consequence, if you specify `gpu: 0` or don't specify `gpu` at all (the default value is `0`), + you won't see GPU resources in offers, even with GPU nodes. The same is true for the `dstack offer` command, + to see available GPU models, you should specify a miminum amount of GPUs > 0: + +
+ + ```shell + $ dstack offer --gpu 1 + ``` + +
+ +> To learn more, see the [Lambda](../../examples/clusters/lambda/#kubernetes) and [Crusoe](../../examples/clusters/crusoe/#kubernetes) examples. ### RunPod From 8aad4ef925dcf00fb22382413dc51ba45a677f8a Mon Sep 17 00:00:00 2001 From: peterschmidt85 Date: Fri, 20 Feb 2026 15:24:49 +0100 Subject: [PATCH 2/2] [Docs] Minor update to the `Resources and offers` under `Kubernetes` on the Backends page --- docs/docs/concepts/backends.md | 45 +++++++++------------------------- 1 file changed, 12 insertions(+), 33 deletions(-) diff --git a/docs/docs/concepts/backends.md b/docs/docs/concepts/backends.md index 8243338fb..023362ca2 100644 --- a/docs/docs/concepts/backends.md +++ b/docs/docs/concepts/backends.md @@ -1061,23 +1061,21 @@ projects: Ensure you've created a ClusterRoleBinding to grant the role to the user or the service account you're using. ??? info "Resources and offers" - [Resources](../concepts/tasks.md#resources) specified in the run configuration are translated to Kubernetes - [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) as follows: + If you use ranges with [`resources`](../concepts/tasks.md#resources) (e.g. `gpu: 1..8` or `memory: 64GB..`) in fleet or run configurations, other backends collect and try all offers that satisfy the range. - - As with other backends, an exact value is translated to a range with the same lower and upper limits, - e.g., `cpu: 4` is the same as `cpu: 4..4`. - - The lower limit, if set, is used as a resource request, meaning that it is guaranteed that the container has at least the specified - amount of the resource. - - For resources other than `gpu`, the upper limit, if set, is used as a resource limit, meaning that the container is not allowed - to consume more resources than specified. If the upper limit is not set, the resource limit is also not set. - - For `gpu` resources, the upper limit is always ignored, and the resource limit is always set to the same value as the resource request, - that is, to the lower limit of the range. + The `kubernetes` backend handles it differently. + + * For `gpu`, if you specify a range (e.g. `gpu: 4..8`), the `kubernetes` backend only provisions pods with the GPU count equal to the lower limit (`4`). The upper limit of the GPU range is always ignored. + * For other resources such as `cpu`, `memory`, and `disk`, the `kubernetes` backend passes the lower and upper limits of the range as Kubernetes [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) respectively. If the upper limit is not set, the Kubernetes limit is also not set. - For example, the following resources specification: + Example:
```yaml + type: dev-environment + ide: vscode + resources: cpu: 32..64 memory: 1024GB @@ -1087,35 +1085,16 @@ projects:
- is translated to: + This translates to the following Kubernetes resource spec: - | resource | request | limit | + | Resource | Request | Limit | |---------------------|----------|-----------| | `cpu` | `32` | `64` | | `memory` | `1024Gi` | `1024Gi` | | `ephemeral-storage` | `100Gi` | _not set_ | | `nvidia.com/gpu` | `4` | `4` | - In offers, `dstack` uses resource requests as offer's resources. - With the resources spec as in the example above, offers would look like the following, - even if nodes have more available resources: - - ``` - # BACKEND RESOURCES INSTANCE TYPE PRICE - 1 kubernetes (-) cpu=32 mem=1024GB disk=100GB H100:80GB:4 h100x8 $0 - ``` - - As a consequence, if you specify `gpu: 0` or don't specify `gpu` at all (the default value is `0`), - you won't see GPU resources in offers, even with GPU nodes. The same is true for the `dstack offer` command, - to see available GPU models, you should specify a miminum amount of GPUs > 0: - -
- - ```shell - $ dstack offer --gpu 1 - ``` - -
+ This applies to offers shown in `dstack apply` (run plans), during provisioning, and in `dstack offer`. Unlike other backends, offers for the `kubernetes` backend always reflect the lower limit of the range. > To learn more, see the [Lambda](../../examples/clusters/lambda/#kubernetes) and [Crusoe](../../examples/clusters/crusoe/#kubernetes) examples.