Skip to content

docs: add documentation for preset invalidation #21018

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
mtojek merged 2 commits into from
Dec 3, 2025
Merged

docs: add documentation for preset invalidation #21018

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7820786
docs: add documentation for preset invalidation
mtojek Dec 1, 2025
6cae776
docs: address code review feedback
mtojek Dec 3, 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
26 changes: 26 additions & 0 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,6 +229,32 @@ When a template's active version is updated:

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

### Invalidating prebuilds

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

This is useful when:

- A base VM image or container image has been updated externally
- Infrastructure configuration has drifted from the desired state
- A monorepo cloned during the prebuild has fallen behind its origin
- You want to ensure prebuilt workspaces use the latest dependencies without publishing a new template version

To invalidate presets:

1. Navigate to **Templates** and select your template.
1. Go to the **Prebuilds** tab.
1. Click **Invalidate Prebuilds**.
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).

> [!NOTE]
> Preset invalidation only affects unclaimed prebuilt workspaces owned by the `prebuilds` system user.
> Workspaces that have already been claimed by users are not affected.
> The invalidation is not instantaneous and will take effect during the next reconciliation loop run.

## Administration and troubleshooting

### Managing resource quotas
Expand Down
Loading