Skip to content

Commit 65ef6df

Browse files
authored
docs: add documentation for preset invalidation (#21018)
Fixes #17917
1 parent f1b2715 commit 65ef6df

File tree

1 file changed

+26
-0
lines changed

1 file changed

+26
-0
lines changed

docs/admin/templates/extending-templates/prebuilt-workspaces.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,32 @@ When a template's active version is updated:
229229

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

232+
### Invalidating prebuilds
233+
234+
When external dependencies change without a template version update, you can invalidate presets to force their prebuilt workspaces to be recreated.
235+
236+
This is useful when:
237+
238+
- A base VM image or container image has been updated externally
239+
- Infrastructure configuration has drifted from the desired state
240+
- A monorepo cloned during the prebuild has fallen behind its origin
241+
- You want to ensure prebuilt workspaces use the latest dependencies without publishing a new template version
242+
243+
To invalidate presets:
244+
245+
1. Navigate to **Templates** and select your template.
246+
1. Go to the **Prebuilds** tab.
247+
1. Click **Invalidate Prebuilds**.
248+
1. Confirm the action in the dialog.
249+
250+
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.
251+
The process typically completes within a few reconciliation cycles (the interval is controlled by `CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL`, which defaults to 15 seconds).
252+
253+
> [!NOTE]
254+
> Preset invalidation only affects unclaimed prebuilt workspaces owned by the `prebuilds` system user.
255+
> Workspaces that have already been claimed by users are not affected.
256+
> The invalidation is not instantaneous and will take effect during the next reconciliation loop run.
257+
232258
## Administration and troubleshooting
233259

234260
### Managing resource quotas

0 commit comments

Comments
 (0)