Skip to content

docs: add dev containers and scheduling to prebuilt workspaces known issues #18816

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+36 −20
Open

docs: add dev containers and scheduling to prebuilt workspaces known issues #18816

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8fb0295
notes about dev containers and scheduling
EdwardAngert Jul 9, 2025
1b0f88c
edit intro
EdwardAngert Jul 9, 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
56 changes: 36 additions & 20 deletions docs/admin/templates/extending-templates/prebuilt-workspaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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.

Currently, Prebuilt workspaces are not fully compatible with the
[dev containers integration](../extending-templates/devcontainers.md) or with [workspace scheduling features](../../../user-guides/workspace-scheduling.md) like autostart and autostop.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently here makes sense for devcontainers as that will change, but I don't believe we'll ever support autostart or autostop and this implies that we will.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it was decided that autostart and autostop won’t ever be supported for prebuilds, since they would conflict with the prebuilds’ own reconciliation loop. I think we can safely remove this mention.


## Relationship to workspace presets

Prebuilt workspaces are tightly integrated with [workspace presets](./parameters.md#workspace-presets):
Expand Down Expand Up @@ -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)
}
}
}
Expand Down Expand Up @@ -123,6 +119,10 @@ New prebuilt workspaces are only created to maintain the desired count if needed
Prebuilt workspaces support time-based scheduling to scale the number of instances up or down.
This allows you to reduce resource costs during off-hours while maintaining availability during peak usage times.

> [!IMPORTANT]
> Use scheduling for prebuilt workspaces instead of
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we need this important notice 🤔
We’ve essentially split the workspace scheduling features: they now apply only to regular workspaces. Prebuilt workspaces have their own reconciliation loop that handles scheduling independently.
What might be worth highlighting instead is that only once a prebuilt workspace is claimed will it follow the regular workspace scheduling behavior.

> [workspace scheduling features](../../../user-guides/workspace-scheduling.md).

Configure scheduling by adding a `scheduling` block within your `prebuilds` configuration:

```tf
Expand Down Expand Up @@ -158,17 +158,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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the numbering here correct?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I believe it's correct! In Markdown, you can use 1. for all items and the renderers will automatically number them properly.

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:**

Expand Down Expand Up @@ -301,6 +301,22 @@ The prebuilt workspaces feature has these current limitations:

[View issue](https://github.com/coder/internal/issues/364)

- **Dev containers**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There seems to be some duplication between this and the sections above. Is that intended?


Prebuilt workspaces do not work reliably with the [dev containers integration](../extending-templates/devcontainers.md).

If your project relies on a dev container configuration, we recommend disabling prebuilds or carefully testing behavior before enabling them.

- **Workspace autostart/autostop**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should delete this. This is not a limitation, workspace scheduling for prebuilds is handled by the reconciliation loop.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I lifted this pretty much directly from @bartekgatzcoder 's comment #18806 (comment)

we can talk about the reconciliation loop better, but it seemed like the "known issue" was a main part of the issue

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, but we already addressed the workspace schedule issue with prebuilds in #18740, and the fix was released in v2.24.2.

The warning that was present earlier has also been removed in #18762, so this should no longer be an issue 🙂


Disable any form of [workspace scheduling features](../../../user-guides/workspace-scheduling.md)
like autostart and autostop for prebuilt workspaces.

Instead, use the [prebuilt-specific TTL and scheduling features](#scheduling).

Prebuilt workspaces with an active autostop configuration can lead to "zombie" workspaces that the Coder server
will not automatically reconcile.

### Monitoring and observability

#### Available metrics
Expand Down
Loading