Skip to content

chore: improve prebuilds docs #17850

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 16, 2025
Merged

chore: improve prebuilds docs #17850

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b0a86ff
chore: documenting workspace update issue
dannykopping May 15, 2025
e88569f
chore: document stopped behaviour
dannykopping May 15, 2025
2dc3af8
chore: move back to "transparent" phrasing
dannykopping May 15, 2025
f1cffaa
chore: removing coder/internal reference
dannykopping May 15, 2025
e8634fa
chore: update provider version
dannykopping May 15, 2025
253ce23
chore: apply suggestions from code review
dannykopping May 16, 2025
c38e356
chore: clarify
dannykopping May 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 16 additions & 5 deletions docs/admin/templates/extending-templates/prebuilt-workspaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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`._

Prebuilt workspaces may be operated on like any other workspace. However, if a prebuilt workspace is stopped, the
reconciliation loop will not destroy it. The intention behind this design is to give operators 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.
Expand Down Expand Up @@ -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 workspaces' 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:
Expand All @@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it looks nicer in the GitHub link format - it's descriptive and familiar

like this - I'll paste this link below as https://github.com/coder/internal/issues/364 and GitHub does the reformatting thing:

coder/internal#364

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was some hesitation in the bug bash call around showing coder/internal links because folks might think they're not accessible.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh interesting

works for me either way


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

Expand Down
Loading