Skip to content

docs: fix prebuilt-workspaces example syntax and defaults #28088

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

Draft
nickvigilante wants to merge 1 commit into
base: main
Choose a base branch
from
+4 −4
Draft

docs: fix prebuilt-workspaces example syntax and defaults #28088

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
8 changes: 4 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 @@ -126,7 +126,7 @@
```tf
data "coder_workspace_preset" "goland" {
name = "GoLand: Large"
parameters {
parameters = {
jetbrains_ide = "GO"
cpus = 8
memory = 16
Expand Down 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 All @@ -248,7 +248,7 @@
1. Confirm the action in the dialog.

Once presets are invalidated, the **next reconciliation loop** run will delete the old prebuilt workspaces and create new ones to maintain the desired instance count.
The process typically completes within a few reconciliation cycles (the interval is controlled by `CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL`, which defaults to 15 seconds).
The process typically completes within a few reconciliation cycles (the interval is controlled by `CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL`, which defaults to 1 minute, or `1m0s`).

> [!NOTE]
> Preset invalidation only affects unclaimed prebuilt workspaces owned by the `prebuilds` system user.
Expand All @@ -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 @@ -277,7 +277,7 @@

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 @@ -326,7 +326,7 @@
To expedite fixing a broken template by ensuring maximum provisioner availability, cancel all pending prebuild jobs:

```sh
coder provisioner jobs list --status=pending --initiator=prebuilds | jq -r '.[].id' | xargs -n1 -P2 -I{} coder provisioner jobs cancel {}
coder provisioner jobs list --status=pending --initiator=prebuilds --output json | jq -r '.[].id' | xargs -n1 -P2 -I{} coder provisioner jobs cancel {}
```

This will clear the provisioner queue of all jobs that were not initiated by a human being, which increases the probability that a provisioner will be available when the next human operator needs it. It does not cancel running provisioner jobs, so there may still be some delay in processing new provisioner jobs until a provisioner completes its current job.
Expand All @@ -338,7 +338,7 @@
If you need to expedite the processing of human-related jobs at the cost of some infrastructure housekeeping, you can run:

```sh
coder provisioner jobs list --status=running --initiator=prebuilds | jq -r '.[].id' | xargs -n1 -P2 -I{} coder provisioner jobs cancel {}
coder provisioner jobs list --status=running --initiator=prebuilds --output json | jq -r '.[].id' | xargs -n1 -P2 -I{} coder provisioner jobs cancel {}
```

This should be done as a last resort. It will cancel running prebuild jobs (orphaning any resources that have already been deployed) and immediately make room for human-initiated jobs. Orphaned infrastructure will need to be manually cleaned up by a human operator. The process to identify and clear these orphaned resources will likely require administrative access to the infrastructure that hosts Coder workspaces. Furthermore, the ability to identify such orphaned resources will depend on metadata that should be included in the workspace template.
Expand All @@ -355,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 @@ -394,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