diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 8e61687ce0f01..e5e935b60a1ca 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -1,18 +1,11 @@ # Prebuilt workspaces -> [!WARNING] -> Prebuilds Compatibility Limitations: -> Prebuilt workspaces currently do not work reliably with [DevContainers feature](../managing-templates/devcontainers/index.md). -> If your project relies on DevContainer configuration, we recommend disabling prebuilds or carefully testing behavior before enabling them. -> -> We’re actively working to improve compatibility, but for now, please avoid using prebuilds with this feature to ensure stability and expected behavior. +Prebuilt workspaces (prebuilds) reduce workspace creation time with an automatically-maintained pool of +ready-to-use workspaces. -Prebuilt workspaces allow template administrators to improve the developer experience by reducing workspace -creation time with an automatically maintained pool of ready-to-use workspaces for specific parameter presets. - -The template administrator configures a template to provision prebuilt workspaces in the background, and then when a developer creates -a new workspace that matches the preset, Coder assigns them an existing prebuilt instance. -Prebuilt workspaces significantly reduce wait times, especially for templates with complex provisioning or lengthy startup procedures. +The template administrator defines the prebuilt workspace's parameters and number of instances to keep provisioned. +When a developer creates a new workspace that matches the definition, Coder assigns them an existing prebuilt workspace. +This significantly reduces wait times, especially for templates with complex provisioning or lengthy startup procedures. Prebuilt workspaces are: @@ -21,6 +14,9 @@ Prebuilt workspaces are: - Monitored and replaced automatically to maintain your desired pool size. - Automatically scaled based on time-based schedules to optimize resource usage. +Prebuilt workspaces are not fully compatible with +[workspace scheduling features](../../../user-guides/workspace-scheduling.md) like autostart and autostop. + ## Relationship to workspace presets Prebuilt workspaces are tightly integrated with [workspace presets](./parameters.md#workspace-presets): @@ -52,7 +48,7 @@ instances your Coder deployment should maintain, and optionally configure a `exp prebuilds { instances = 3 # Number of prebuilt workspaces to maintain expiration_policy { - ttl = 86400 # Time (in seconds) after which unclaimed prebuilds are expired (1 day) + ttl = 86400 # Time (in seconds) after which unclaimed prebuilds are expired (86400 = 1 day) } } } @@ -158,17 +154,17 @@ data "coder_workspace_preset" "goland" { **Scheduling configuration:** -- **`timezone`**: The timezone for all cron expressions (required). Only a single timezone is supported per scheduling configuration. -- **`schedule`**: One or more schedule blocks defining when to scale to specific instance counts. - - **`cron`**: Cron expression interpreted as continuous time ranges (required). - - **`instances`**: Number of prebuilt workspaces to maintain during this schedule (required). +- `timezone`: (Required) The timezone for all cron expressions. Only a single timezone is supported per scheduling configuration. +- `schedule`: One or more schedule blocks defining when to scale to specific instance counts. + - `cron`: (Required) Cron expression interpreted as continuous time ranges. + - `instances`: (Required) Number of prebuilt workspaces to maintain during this schedule. **How scheduling works:** 1. The reconciliation loop evaluates all active schedules every reconciliation interval (`CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL`). -2. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules. -3. If no schedules match the current time, the base `instances` count is used. -4. The reconciliation loop automatically creates or destroys prebuilt workspaces to match the target count. +1. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules. +1. If no schedules match the current time, the base `instances` count is used. +1. The reconciliation loop automatically creates or destroys prebuilt workspaces to match the target count. **Cron expression format:** @@ -226,7 +222,7 @@ When a template's active version is updated: 1. Prebuilt workspaces for old versions are automatically deleted. 1. New prebuilt workspaces are created for the active template version. 1. If dependencies change (e.g., an [AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) update) without a template version change: - - You may delete the existing prebuilt workspaces manually. + - You can delete the existing prebuilt workspaces manually. - Coder will automatically create new prebuilt workspaces with the updated dependencies. The system always maintains the desired number of prebuilt workspaces for the active template version. @@ -291,16 +287,6 @@ does not reconnect after a template update. This shortcoming is described in [th and will be addressed before the next release (v2.23). In the interim, a simple workaround is to restart the workspace when it is in this problematic state. -### Current limitations - -The prebuilt workspaces feature has these current limitations: - -- **Organizations** - - Prebuilt workspaces can only be used with the default organization. - - [View issue](https://github.com/coder/internal/issues/364) - ### Monitoring and observability #### Available metrics @@ -323,3 +309,19 @@ These logs provide information about: 1. Creation and deletion attempts for prebuilt workspaces. 1. Backoff events after failed builds. 1. Claiming operations. + +## Known Issues and Limitations + +Some known limitations of prebuilt workspaces include: + +- **Organizations** + + Prebuilt workspaces can only be used with the default organization. + + [View issue](https://github.com/coder/internal/issues/364) + +- **Dev containers** + + Prebuilt workspaces do not work reliably with the [dev containers integration](../extending-templates/devcontainers.md). + + If your project relies on a dev container configuration, you should disabling prebuilds or carefully test their behavior before enabling them.