Document the instances run configuration property

mkdocs/docs/concepts/snippets/manage-fleets.ext

@@ -1,3 +1,34 @@
+### Instances
+
+Use `instances` to restrict a run to particular existing fleet instances. You can specify
+instance names, hostnames or IP addresses, or a fleet name with an instance number.
+For the `fleet` form, use `<project>/<fleet>` when the fleet belongs to another project:
+
+<div editor-title=".dstack.yml">
+
+```yaml
+instances:
+  - name: my-fleet-3
+  - hostname: 203.0.113.10
+  - fleet: my-fleet
+    instance: 3
+```
+
+</div>
+
+??? info "Short syntax"
+
+    To match by instance name, you can use the string shorthand:
+
+    ```yaml
+    instances:
+      - my-fleet-3
+    ```
+
+When `instances` is set, the run is only placed on a matching existing instance and `dstack`
+never provisions new instances. If no matching instance is available, the run fails with a
+no-capacity error (use `retry` to wait for a targeted instance to free up).
+
 ### Idle duration
 
 If the run is submitted to a fleet with `nodes` set to a range and a new instance is provisioned,

mkdocs/docs/guides/protips.md

@@ -208,6 +208,42 @@ $ dstack apply -R -f examples/.dstack.yml
 
 Or, set [`creation_policy`](../reference/dstack.yml/dev-environment.md#creation_policy) to `reuse` in the run configuration.
 
+### Instances
+
+Use `instances` to restrict a run to particular existing fleet instances. You can specify
+instance names, hostnames or IP addresses, or a fleet name with an instance number.
+For the `fleet` form, use `<project>/<fleet>` when the fleet belongs to another project:
+
+<div editor-title=".dstack.yml">
+
+```yaml
+type: dev-environment
+name: vscode
+ide: vscode
+
+instances:
+  - name: my-fleet-3
+  - hostname: 203.0.113.10
+  - fleet: my-fleet
+    instance: 3
+```
+
+</div>
+
+??? info "Short syntax"
+
+    To match by instance name, you can use the string shorthand:
+
+    ```yaml
+    instances:
+      - my-fleet-3
+    ```
+
+When `instances` is set, the run is only placed on a matching existing instance and
+`dstack` never provisions new instances. If no matching instance is available, the run
+fails with a no-capacity error (use [`retry`](../reference/dstack.yml/dev-environment.md#retry)
+to wait for a targeted instance to free up).
+
 ### Idle duration
 
 If the run is submitted to a fleet with `nodes` set to a range and a new instance is provisioned, the shorter of the fleet's and run's `idle_duration` is used.