[Docs] Clarified the behavior of idle duration: how run's idle_duration and fleet's idle_duration are applied (#3574)

Author: peterschmidt85

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

@@ -1,6 +1,10 @@
 ### Idle duration
 
-If a run provisions a new instance, the instance stays `idle` for 5 minutes by default and can be reused within that time.
-If the instance is not reused within this period, it is automatically terminated.
-To change the default idle duration, set
-[`idle_duration`](../reference/dstack.yml/fleet.md#idle_duration) in the run configuration (e.g., `0s`, `1m`, or `off` for unlimited).
+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.
+If the run reuses an existing fleet instance, only the fleet's
+[`idle_duration`](../reference/dstack.yml/fleet.md#idle_duration) applies.
+
+If an instance remains `idle`, it is automatically terminated after `idle_duration`.
+
+> Not applied for container-based backends (Kubernetes, Vast.ai, RunPod).

docs/docs/guides/protips.md

@@ -212,10 +212,13 @@ Or, set [`creation_policy`](../reference/dstack.yml/dev-environment.md#creation_
 
 ### Idle duration
 
-If a run provisions a new instance, the instance stays `idle` for 5 minutes by default and can be reused within that time.
-If the instance is not reused within this period, it is automatically terminated.
-To change the default idle duration, set
-[`idle_duration`](../reference/dstack.yml/fleet.md#idle_duration) in the run configuration (e.g., `0s`, `1m`, or `off` for unlimited).
+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.
+If the run reuses an existing fleet instance, only the fleet's
+[`idle_duration`](../reference/dstack.yml/fleet.md#idle_duration) applies.
+
+If an instance remains `idle`, it is automatically terminated after `idle_duration`.
+
+> Not applied for container-based backends (Kubernetes, Vast.ai, RunPod).
 
 ## Volumes
 

src/dstack/_internal/core/models/profiles.py

@@ -323,9 +323,11 @@ class ProfileParams(CoreModel):
         Field(
             description=(
                 "Time to wait before terminating idle instances."
-                " Instances are not terminated if the fleet is already at `nodes.min`."
+                " When the run reuses an existing fleet instance, the fleet's `idle_duration` applies."
+                " When the run provisions a new instance, the shorter of the fleet's and run's values is used."
                 " Defaults to `5m` for runs and `3d` for fleets."
-                " Use `off` for unlimited duration"
+                " Use `off` for unlimited duration."
+                " Only applied for VM-based backends"
             )
         ),
     ] = None