chore: improve prebuilds docs (#17850)

dannykopping · EdwardAngert · web-flow · commit 8914f7a95b01 · 2025-05-16T19:25:09.000+02:00
These items came up in an internal "bug bash" session yesterday. @EdwardAngert note: I've reverted to the "transparent" phrasing; the current docs confused a couple folks yesterday, and I feel that "transparent" is clearly understood in this context. --------- Signed-off-by: Danny Kopping <dannykopping@gmail.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md
@@ -25,7 +25,7 @@ Prebuilt workspaces are tightly integrated with [workspace presets](./parameters
 ## Prerequisites
 
 - [**Premium license**](../../licensing/index.md)
-- **Compatible Terraform provider**: Use `coder/coder` Terraform provider `>= 2.4.0`.
+- **Compatible Terraform provider**: Use `coder/coder` Terraform provider `>= 2.4.1`.
 - **Feature flag**: Enable the `workspace-prebuilds` [experiment](../../../reference/cli/server.md#--experiments).
 
 ## Enable prebuilt workspaces for template presets
@@ -75,7 +75,7 @@ Prebuilt workspaces follow a specific lifecycle from creation through eligibilit
 
    Prebuilt workspaces that fail during provisioning are retried with a backoff to prevent transient failures.
 
-1. When a developer requests a new workspace, the claiming process occurs:
+1. When a developer creates a new workspace, the claiming process occurs:
 
    1. Developer selects a template and preset that has prebuilt workspaces configured.
    1. If an eligible prebuilt workspace exists, ownership transfers from the `prebuilds` user to the requesting user.
@@ -84,13 +84,17 @@ Prebuilt workspaces follow a specific lifecycle from creation through eligibilit
       [`coder_workspace_owner`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace_owner)
       datasources (see [Preventing resource replacement](#preventing-resource-replacement) for further considerations).
 
-   The developer doesn't see the claiming process — the workspace will just be ready faster than usual.
+   The claiming process is transparent to the developer — the workspace will just be ready faster than usual.
 
 You can view available prebuilt workspaces in the **Workspaces** view in the Coder dashboard:
 
 ![A prebuilt workspace in the dashboard](../../../images/admin/templates/extend-templates/prebuilt/prebuilt-workspaces.png)
 _Note the search term `owner:prebuilds`._
 
+Unclaimed prebuilt workspaces can be interacted with in the same way as any other workspace.
+However, if a Prebuilt workspace is stopped, the reconciliation loop will not destroy it.
+This gives template admins the ability to park problematic prebuilt workspaces in a stopped state for further investigation.
+
 ### Template updates and the prebuilt workspace lifecycle
 
 Prebuilt workspaces are not updated after they are provisioned.
@@ -169,6 +173,13 @@ For example, the [`ami`](https://registry.terraform.io/providers/hashicorp/aws/l
 has [`ForceNew`](https://github.com/hashicorp/terraform-provider-aws/blob/main/internal/service/ec2/ec2_instance.go#L75-L81) set,
 since the AMI cannot be changed in-place._
 
+#### Updating claimed prebuilt workspace templates
+
+Once a prebuilt workspace has been claimed, and if its template uses `ignore_changes`, users may run into an issue where the agent
+does not reconnect after a template update. This shortcoming is described in [this issue](https://github.com/coder/coder/issues/17840)
+and will be addressed before the next release (v2.23). In the interim, a simple workaround is to restart the workspace
+when it is in this problematic state.
+
 ### Current limitations
 
 The prebuilt workspaces feature has these current limitations:
@@ -177,13 +188,13 @@ The prebuilt workspaces feature has these current limitations:
 
   Prebuilt workspaces can only be used with the default organization.
 
-  [coder/internal#364](https://github.com/coder/internal/issues/364)
+  [View issue](https://github.com/coder/internal/issues/364)
 
 - **Autoscaling**
 
   Prebuilt workspaces remain running until claimed. There's no automated mechanism to reduce instances during off-hours.
 
-  [coder/internal#312](https://github.com/coder/internal/issues/312)
+  [View issue](https://github.com/coder/internal/issues/312)
 
 ### Monitoring and observability
 
