- [Docs] Added the Clouds guide

- [Docs] Lots of minor edits
dstackai · Aug 24, 2023 · b65f584 · b65f584
1 parent 35044db
commit b65f584
Show file tree

Hide file tree

Showing 10 changed files with 314 additions and 433 deletions.
diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css
@@ -344,7 +344,7 @@
 }
 
 .md-typeset :not(pre) > a code {
-    color: #8752d7;
+    color: #ce00ff;
 }
 
 .md-typeset pre > code {
@@ -483,9 +483,9 @@ code .md-code__nav:hover .md-code__button {
 }
 
 [data-md-color-scheme=slate][data-md-color-primary=black], [data-md-color-primary=white] {
-    --md-primary-fg-color: #6e14ed;
-    --md-accent-fg-color: #6e14ed;
-    --md-typeset-a-color: #6e14ed;
+    --md-primary-fg-color: #0048ff;
+    --md-accent-fg-color: #ce00ff;
+    --md-typeset-a-color: #ce00ff;
     --md-code-hl-function-color: #e3b4fb;
     --md-code-hl-keyword-color: #e37cff;
     --md-code-hl-string-color: #b4f9c6;
@@ -858,14 +858,16 @@ html .md-footer-meta.md-typeset a:is(:focus,:hover) {
     color: var(--md-typeset-a-color);
 }
 
-.md-typeset .grid.cards>:-webkit-any(ul,ol)>li a, .md-typeset .grid>.card a {
+.md-typeset .grid.cards > :-webkit-any(ul,ol) > li a,
+.md-typeset .grid.cards > :-webkit-any(ul,ol) > li span,
+.md-typeset .grid > .card a {
     color: var(--md-default-fg-color);
     text-decoration: none;
     display: block;
     margin: 0;
     padding: 1rem 1.4rem;
     border-radius: 6px;
-    border: rgba(0,0,0,0.6) 1px solid;
+    border: rgba(0,0,0,0.6) 0.5px solid;
 }
 
 .md-typeset .grid.cards>ol>li:focus-within,.md-typeset .grid.cards>ol>li:hover,.md-typeset .grid.cards>ul>li:focus-within,.md-typeset .grid.cards>ul>li:hover,.md-typeset .grid>.card:focus-within,.md-typeset .grid>.card:hover {

diff --git a/docs/docs/guides/clouds.md b/docs/docs/guides/clouds.md
@@ -0,0 +1,81 @@
+# Clouds
+
+With `dstack`, you can run LLM workloads using compute resources from multiple cloud GPU providers. 
+All you need to do is sign up with these providers, and then pass
+their credentials to `dstack`.
+
+### Why multiple clouds?
+
+<div class="grid cards" markdown>
+- <span>**GPU availability**
+   Because of high demand, it's easier to obtain GPU from various cloud providers through a single interface.</span>
+- <span>**GPU price**
+   Leverage smaller cloud services (e.g., Lambda Cloud) and spot instances across larger providers.</span>
+- <span>**No vendor lock-in**
+   An open-source and cloud-agnostic interface enables easy switching between cloud providers.</span>
+</div>
+
+## Creating cloud accounts
+
+First, you have to create accounts with each cloud provider.
+
+Currently, `dstack` supports [AWS](https://portal.aws.amazon.com/billing/signup), 
+[GCP](https://console.cloud.google.com/freetrial), 
+[Azure](https://azure.microsoft.com/en-us/free), and [Lambda](https://cloud.lambdalabs.com/sign-up). 
+To request support for more providers, please submit or upvote
+relevant issues in [our tracker](https://github.com/dstackai/dstack/issues).
+
+??? info "Applying for cloud credits"
+    Startups can apply for extra credits, usually by reaching out directly to the provider in the case of smaller providers,
+    or through a partner program (such as [NVIDIA Inception](https://www.nvidia.com/en-us/startups/)) for larger providers.
+
+??? info "Requesting GPU quotas"
+
+    Larger providers require you to request GPU quotas, essentially obtaining permission from their support
+    team, prior to utilizing GPUs with your account. If planning to use GPU through credits, approval for the request might
+    take extra time.
+
+    Quotas need to be requested separately for each family of GPUs and for each region where GPU usage is intended.
+
+    To use spot instances with certain cloud providers (e.g. AWS), you should request quotes
+    for such instances separately.
+
+## Configuring clouds with dstack
+
+First, you need to start the `dstack` server, log in to the UI, open the project settings, and add a backend for each
+cloud.
+
+![](../../assets/images/dstack-hub-view-project-empty.png){ width=800 }
+
+Configuring backends involves providing cloud credentials, and specifying storage.
+
+<div class="grid cards" markdown>
+- [**AWS**
+   Learn how to set up an Amazon Web Services backend.
+  ](../../reference/backends/aws/)
+- [**GCP**
+   Learn how to set up a Google Cloud backend.
+  ](../../reference/backends/gcp/)
+- [**Azure**
+   Learn how to set up an Microsoft Azure backend.
+  ](../../reference/backends/azure/)
+- [**Lambda**
+   Learn how to set up a Lambda Cloud backend.
+  ](../../reference/backends/lambda/)
+
+</div>
+
+## Requesting resources
+
+You can request resources using the [`--gpu`](../reference/cli/run.md#GPU) 
+and [`--memory`](../reference/cli/run.md#MEMORY) arguments with `dstack run`, 
+or through [`resources`](../reference/profiles.yml.md#RESOURCES) with `.dstack/profiles.yml`.
+
+Both the [`dstack run`](../reference/cli/run.md) command and [`.dstack/profiles.yml`](../reference/profiles.yml.md)
+support various other options, including requesting spot instances, defining the maximum run duration or price, and
+more.
+
+!!! info "Automatic instance discovery"
+    Remember, you can't specify an instance type by name. Instead, ask for resources by GPU name or memory amount. 
+    `dstack` will automatically select the suitable instance type from a cloud provider and region with the best
+    price and availability.
diff --git a/docs/docs/guides/dev-environments.md b/docs/docs/guides/dev-environments.md
@@ -89,7 +89,7 @@ You can install packages using `pip` and `conda` executables from `setup`.
     If there is no pre-built image, the `dstack run` command will build it and upload it to the storage. If the pre-built
     image is already available, the `dstack run` command will reuse it.
 
-The `.dstack.yml` has many other properties. To view them all, refer to the [Reference](../reference/dstack.yml/dev-environment.md).
+For more details on the file syntax, refer to [`.dstack.yml`](../reference/dstack.yml/dev-environment.md).
 
 ## Run the configuration
 
@@ -122,58 +122,18 @@ To open the dev environment via a desktop IDE, click the URL in the output.
 
 By default, VS Code comes with pre-installed Python and Jupyter extensions.
 
-### Configure resources, price, etc
+### Requesting resources
 
-For every run, you can specify hardware resources like memory and GPU, along with various run policies (e.g., maximum
-hourly price, use of spot instances, etc.).
+You can request resources using the [`--gpu`](../reference/cli/run.md#GPU) 
+and [`--memory`](../reference/cli/run.md#MEMORY) arguments with `dstack run`, 
+or through [`resources`](../reference/profiles.yml.md#RESOURCES) with `.dstack/profiles.yml`.
 
-| Example                     | Description                                |
-|-----------------------------|--------------------------------------------|
-| `dstack run . --gpu A10`    | Use an instance with `NVIDIA A10` GPU      |
-| `dstack run . --gpu A100:8` | Use an instance with 8 `NVIDIA A100` GPUs  |
-| `dstack run . --gpu 24GB`   | Use an instance with a GPU that has `24GB` |
+Both the [`dstack run`](../reference/cli/run.md) command and [`.dstack/profiles.yml`](../reference/profiles.yml.md)
+support various other options, including requesting spot instances, defining the maximum run duration or price, and
+more.
 
-The `dstack run` command has many options. To view them, refer to the [Reference](../reference/cli/run.md).
+!!! info "Automatic instance discovery"
+    `dstack` will automatically select the suitable instance type from a cloud provider and region with the best
+    price and availability.
 
-??? info "Profiles"
-    ### Configure profiles (optional)
-
-    Instead of configuring resources, price, and policies through `dstack run`, you can use profiles. To set up a profile, 
-    create the `.dstack/profiles.yml` file in the root folder of the project. 
-
-    <div editor-title=".dstack/profiles.yml"> 
-
-    ```yaml
-    profiles:
-      - name: large
-
-        resources:
-          memory: 24GB  # (Optional) The minimum amount of RAM memory
-          gpu:
-            memory: 48GB  # (Optional) The minimum amount of GPU memory 
-            
-        max_price: 1.5 # (Optional) The maximim price per instance, in dollards.
-
-        max_duration: 1d # (Optional) The maximum duration of the run.
-
-        spot_policy: auto # (Optional) The spot policy. Supports `spot`, `on-demand, and `auto`.
-
-        backends: [azure, lambda]  # (Optional) Use only listed backends 
-
-        default: true # (Optional)
-    ```
-    
-    </div>
-
-    #### Spot instances
-
-    If `spot_policy` is set to `auto`, `dstack` gives priority to spot instances. If unavailable, it uses on-demand instances. 
-    To reduce costs, set `spot_policy` to `spot`. Keep in mind that spot instances are much cheaper but may be interrupted. 
-    Your code should handle interruptions and resume from saved checkpoints.
-
-    #### Default profile
-
-    By default, the `dstack run` command uses the default profile. You 
-    can override it by passing the `--profile` argument to the `dstack run` command.
-
-    For more details on the syntax of the `profiles.yml` file, refer to the [Reference](../reference/profiles.yml.md).
+For more details on the run command, refer to [`dstack run`](reference/cli/run.md).
diff --git a/docs/docs/guides/services.md b/docs/docs/guides/services.md
@@ -32,7 +32,7 @@ Before running a service, you need to configure a gateway address to run the ser
 
 ??? info "Gateway"
 
-    ### Configure a gateway address 
+    ### Configure a gateway 
 
     First, you have to create a gateway in one of the clouds of your choice.
     
@@ -148,7 +148,7 @@ You can install packages using `pip` and `conda` executables from `commands`.
     If there is no pre-built image, the `dstack run` command will build it and upload it to the storage. If the pre-built
     image is already available, the `dstack run` command will reuse it.
 
-The `.dstack.yml` has many other properties. To view them all, refer to the [Reference](../reference/dstack.yml/service.md).
+For more details on the file syntax, refer to [`.dstack.yml`](../reference/dstack.yml/service.md).
 
 ## Run the configuration
 
@@ -175,58 +175,18 @@ Serving HTTP on https://myservice.mydomain.com ...
 
 This command deploys the service, and forwards the traffic to the gateway address.
 
-### Configure resources, price, etc
+### Requesting resources
 
-For every run, you can specify hardware resources like memory and GPU, along with various run policies (e.g., maximum
-hourly price, use of spot instances, etc.).
+You can request resources using the [`--gpu`](../reference/cli/run.md#GPU) 
+and [`--memory`](../reference/cli/run.md#MEMORY) arguments with `dstack run`, 
+or through [`resources`](../reference/profiles.yml.md#RESOURCES) with `.dstack/profiles.yml`.
 
-| Example                     | Description                                |
-|-----------------------------|--------------------------------------------|
-| `dstack run . --gpu A10`    | Use an instance with `NVIDIA A10` GPU      |
-| `dstack run . --gpu A100:8` | Use an instance with 8 `NVIDIA A100` GPUs  |
-| `dstack run . --gpu 24GB`   | Use an instance with a GPU that has `24GB` |
+Both the [`dstack run`](../reference/cli/run.md) command and [`.dstack/profiles.yml`](../reference/profiles.yml.md)
+support various other options, including requesting spot instances, defining the maximum run duration or price, and
+more.
 
-The `dstack run` command has many options. To view them, refer to the [Reference](../reference/cli/run.md).
+!!! info "Automatic instance discovery"
+    `dstack` will automatically select the suitable instance type from a cloud provider and region with the best
+    price and availability.
 
-??? info "Profiles"
-    ### Configure profiles (optional) 
-
-    Instead of configuring resources, price, and policies through `dstack run`, you can use profiles. To set up a profile, 
-    create the `.dstack/profiles.yml` file in the root folder of the project. 
-
-    <div editor-title=".dstack/profiles.yml"> 
-
-    ```yaml
-    profiles:
-      - name: large
-
-        resources:
-          memory: 24GB  # (Optional) The minimum amount of RAM memory
-          gpu:
-            memory: 48GB  # (Optional) The minimum amount of GPU memory 
-            
-        max_price: 1.5 # (Optional) The maximim price per instance, in dollards.
-
-        max_duration: 1d # (Optional) The maximum duration of the run.
-
-        spot_policy: auto # (Optional) The spot policy. Supports `spot`, `on-demand, and `auto`.
-
-        backends: [azure, lambda]  # (Optional) Use only listed backends 
-
-        default: true # (Optional)
-    ```
-    
-    </div>
-
-    #### Spot instances
-
-    If `spot_policy` is set to `auto`, `dstack` gives priority to spot instances. If unavailable, it uses on-demand instances. 
-    To reduce costs, set `spot_policy` to `spot`. Keep in mind that spot instances are much cheaper but may be interrupted. 
-    Your code should handle interruptions and resume from saved checkpoints.
-
-    #### Default profile
-
-    By default, the `dstack run` command uses the default profile. You 
-    can override it by passing the `--profile` argument to the `dstack run` command.
-
-    For more details on the syntax of the `profiles.yml` file, refer to the [Reference](../reference/profiles.yml.md).
+For more details on the run command, refer to [`dstack run`](reference/cli/run.md).