Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: document prebuilds quota group behavior #28015

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
johnstcn merged 3 commits into from
Aug 11, 2026
Merged

docs: document prebuilds quota group behavior #28015

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
589719f
docs(prebuilt-workspaces): document prebuilds quota group behavior
johnstcn Aug 11, 2026
936ba9e
docs(prebuilt-workspaces): document prebuilds quota group behavior
johnstcn Aug 11, 2026
18858d9
Merge branch 'main' into docs/prebuilds-quota-group
johnstcn Aug 11, 2026
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
12 changes: 8 additions & 4 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 @@ -229,7 +229,7 @@

The system always maintains the desired number of prebuilt workspaces for the active template version.

### Invalidating prebuilds

Check warning on line 232 in docs/admin/templates/extending-templates/prebuilt-workspaces.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.GerundHeading 

Heading starts with an -ing word ('Invalidating'); prefer the imperative ('Install') or the noun ('Installation'). See capitalization-and-punctuation.md#no-gerund-leading-headings.

When external dependencies change without a template version update, you can invalidate presets to force their prebuilt workspaces to be recreated.

Expand Down Expand Up @@ -257,7 +257,7 @@

## Administration and troubleshooting

### Managing resource quotas

Check warning on line 260 in docs/admin/templates/extending-templates/prebuilt-workspaces.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.GerundHeading 

Heading starts with an -ing word ('Managing'); prefer the imperative ('Install') or the noun ('Installation'). See capitalization-and-punctuation.md#no-gerund-leading-headings.

To help prevent unexpected infrastructure costs, prebuilt workspaces can be used in conjunction with [resource quotas](../../users/quotas.md).
Because unclaimed prebuilt workspaces are owned by the `prebuilds` user, you can:
Expand All @@ -265,15 +265,19 @@
1. Configure quotas for any group that includes this user.
1. Set appropriate limits to balance prebuilt workspace availability with resource constraints.

When prebuilt workspaces are configured for an organization, Coder creates a "prebuilds" group in that organization and adds the prebuilds user to it. This group has a default quota allowance of 0, which you should adjust based on your needs:
When prebuilt workspaces are configured for an organization, Coder creates a group named `coderprebuiltworkspaces` (the **Prebuilt Workspaces** group) in that organization and adds the `prebuilds` user to it.
This group has a default quota allowance of 0, which you should adjust based on your needs:

- **Set a quota allowance** on the "prebuilds" group to control how many prebuilt workspaces can be provisioned
- **Monitor usage** to ensure the quota is appropriate for your desired number of prebuilt instances
- **Adjust as needed** based on your template costs and desired prebuilt workspace pool size
- **Set a Quota Allowance** on the `coderprebuiltworkspaces` group to control how many prebuilt workspaces can be provisioned.
- **Monitor usage** to ensure the quota is appropriate for your desired number of prebuilt instances.
- **Adjust as needed** based on your template costs and desired prebuilt workspace pool size.

> [!NOTE]
> The `prebuilds` user is a system user, so it does not appear in the group's member list in the Coder dashboard or API, even though it is a member.

If a quota is exceeded, the prebuilt workspace will fail provisioning the same way other workspaces do.

### Managing prebuild provisioning queues

Check warning on line 280 in docs/admin/templates/extending-templates/prebuilt-workspaces.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.GerundHeading 

Heading starts with an -ing word ('Managing'); prefer the imperative ('Install') or the noun ('Installation'). See capitalization-and-punctuation.md#no-gerund-leading-headings.

Prebuilt workspaces can overwhelm a Coder deployment, causing significant delays when users and template administrators create new workspaces or manage their templates. Fundamentally, this happens when provisioners are not able to meet the demand for provisioner jobs. Prebuilds contribute to provisioner demand by scheduling many jobs in bursts whenever templates are updated. The solution is to either increase the number of provisioners or decrease the number of requested prebuilt workspaces across the entire system.

Expand Down Expand Up @@ -351,7 +355,7 @@

### Template configuration best practices

#### Preventing resource replacement

Check warning on line 358 in docs/admin/templates/extending-templates/prebuilt-workspaces.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.GerundHeading 

Heading starts with an -ing word ('Preventing'); prefer the imperative ('Install') or the noun ('Installation'). See capitalization-and-punctuation.md#no-gerund-leading-headings.

When a prebuilt workspace is claimed, another `terraform apply` run occurs with new values for the workspace owner and name.

Expand Down Expand Up @@ -390,7 +394,7 @@
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._

### Preventing prebuild queue contention (recommended)

Check warning on line 397 in docs/admin/templates/extending-templates/prebuilt-workspaces.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.GerundHeading 

Heading starts with an -ing word ('Preventing'); prefer the imperative ('Install') or the noun ('Installation'). See capitalization-and-punctuation.md#no-gerund-leading-headings.

The section [Managing prebuild provisioning queues](#managing-prebuild-provisioning-queues) covers how to recover when prebuilds have already overwhelmed the provisioner queue.
This section outlines a **best-practice configuration** to prevent that situation by isolating prebuild jobs to a dedicated provisioner pool.
Expand Down
Loading