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