synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-12 00:14:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: improve prebuilds docs (#17850)

Browse Source 
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>
This commit is contained in:
Danny Kopping
2025-05-16 19:25:09 +02:00
committed by GitHub
parent d564164eaf
commit 8914f7a95b
1 changed files with 16 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/admin/templates/extending-templates/prebuilt-workspaces.md
View File

@ -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