mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: add dev containers and scheduling to prebuilt workspaces known issues (#18816)
closes #18806 - [x] scheduling limitation - [x] dev containers limitation - [x] edit intro [preview](https://coder.com/docs/@18806-prebuilds-known-limits/admin/templates/extending-templates/prebuilt-workspaces) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Clarified the introduction and administrator responsibilities for prebuilt workspaces. * Integrated compatibility information about DevContainers and workspace scheduling more contextually. * Added explicit notes on limitations with dev containers integration and workspace autostart/autostop features. * Improved configuration examples and clarified scheduling instructions. * Enhanced explanations of scheduling behavior and lifecycle steps for better understanding. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Sas Swart <sas.swart.cdk@gmail.com> Co-authored-by: Susana Ferreira <susana@coder.com>
This commit is contained in:
Edward Angert
co-authored by
EdwardAngert
Sas Swart
Susana Ferreira
EdwardAngert
Sas Swart
Susana Ferreira
parent
5e49d8c569
commit
49f32d14eb
@@ -1,18 +1,12 @@
|
||||
# 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 for specific parameter presets.
|
||||
|
||||
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.
|
||||
The desired number of workspaces are then provisioned transparently.
|
||||
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 +15,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 a special type of workspace that don't follow the
|
||||
[regular workspace scheduling features](../../../user-guides/workspace-scheduling.md) like autostart and autostop. Instead, they have their own reconciliation loop that handles prebuild-specific scheduling features such as TTL and prebuild scheduling.
|
||||
|
||||
## Relationship to workspace presets
|
||||
|
||||
Prebuilt workspaces are tightly integrated with [workspace presets](./parameters.md#workspace-presets):
|
||||
@@ -53,7 +50,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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -159,17 +156,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:**
|
||||
|
||||
@@ -227,7 +224,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.
|
||||
@@ -285,13 +282,6 @@ For example, the [`ami`](https://registry.terraform.io/providers/hashicorp/aws/l
|
||||
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._
|
||||
|
||||
#### Updating claimed prebuilt workspace templates
|
||||
|
||||
Once a prebuilt workspace has been claimed, and if its template uses `ignore_changes`, users may run into an issue where the agent
|
||||
does not reconnect after a template update. This shortcoming is described in [this issue](https://github.com/coder/coder/issues/17840)
|
||||
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.
|
||||
|
||||
### Monitoring and observability
|
||||
|
||||
#### Available metrics
|
||||
|
||||
Reference in New Issue
Block a user