From 7820786f266f51bd0994d35ac220f8156ae3f629 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Mon, 1 Dec 2025 10:49:16 +0000 Subject: [PATCH 1/2] docs: add documentation for preset invalidation Adds a new section explaining how to invalidate presets when external dependencies change without a template version update. When presets are invalidated, the reconciliation loop automatically recycles their prebuilt workspaces. Updates #17917 --- .../prebuilt-workspaces.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 748fc40c98d9c..ffb9037b9ebee 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -229,6 +229,30 @@ 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 (such as AMI updates, base image changes, or configuration drift) 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 +- 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. + ## Administration and troubleshooting ### Managing resource quotas From 6cae77671e311c37b455c23b446f2d5d88868fc2 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 3 Dec 2025 10:37:49 +0000 Subject: [PATCH 2/2] docs: address code review feedback - Remove examples from first paragraph per review comment - Add monorepo use case to the list - Bold 'next reconciliation loop' for emphasis - Add note about invalidation not being instantaneous --- .../templates/extending-templates/prebuilt-workspaces.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index ffb9037b9ebee..669ce02307be4 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -231,12 +231,13 @@ The system always maintains the desired number of prebuilt workspaces for the ac ### Invalidating prebuilds -When external dependencies change (such as AMI updates, base image changes, or configuration drift) without a template version update, you can invalidate presets to force their prebuilt workspaces to be recreated. +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: @@ -246,12 +247,13 @@ To invalidate presets: 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. +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