docs: add dev containers and scheduling to prebuilt workspaces known issues #18816
Conversation
| @@ -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. | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
Is the numbering here correct?
There was a problem hiding this comment.
Yes, I believe it's correct! In Markdown, you can use 1. for all items and the renderers will automatically number them properly.
| @@ -301,6 +301,22 @@ The prebuilt workspaces feature has these current limitations: | |||
|
|
|||
| [View issue](https://github.com/coder/internal/issues/364) | |||
|
|
|||
| - **Dev containers** | |||
There was a problem hiding this comment.
There seems to be some duplication between this and the sections above. Is that intended?
| @@ -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. | |||
There was a problem hiding this comment.
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.
| @@ -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 | |||
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
Yes, I believe it's correct! In Markdown, you can use 1. for all items and the renderers will automatically number them properly.
|
|
||
| If your project relies on a dev container configuration, we recommend disabling prebuilds or carefully testing behavior before enabling them. | ||
|
|
||
| - **Workspace autostart/autostop** |
There was a problem hiding this comment.
We should delete this. This is not a limitation, workspace scheduling for prebuilds is handled by the reconciliation loop.
There was a problem hiding this comment.
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
WalkthroughThe documentation for prebuilt workspaces was updated to clarify compatibility limitations, particularly with DevContainers and workspace autostart/autostop features. The changes reorganize these warnings, improve explanations of scheduling and TTL configuration, and enhance the clarity and consistency of the documentation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~6 minutes Assessment against linked issues
Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
docs/admin/templates/extending-templates/prebuilt-workspaces.md (2)
304-309: Duplication with earlier noticeThis “Dev containers” limitation repeats the warning already given in lines 17-19. Consolidating the information in one place would keep the doc shorter and reduce maintenance overhead.
310-319: Still duplicated & previously flaggedThe autostart/autostop limitation is explained in both the introduction and here. Past reviews suggested dropping the duplicate; consider removing one to avoid drift.
🧹 Nitpick comments (1)
docs/admin/templates/extending-templates/prebuilt-workspaces.md (1)
17-19: Drop “Currently” & tighten wording to avoid implying future supportPast discussion concluded that prebuilds will likely never support autostart/autostop, so “Currently” is misleading here. A leaner sentence also scans better:
-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. +Prebuilt workspaces are not compatible with the +[dev containers integration](../extending-templates/devcontainers.md) or with [workspace scheduling features](../../../user-guides/workspace-scheduling.md) such as autostart and autostop.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/admin/templates/extending-templates/prebuilt-workspaces.md(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{go,sql,ts,tsx,js,jsx,md}
📄 CodeRabbit Inference Engine (CLAUDE.md)
Ensure files end with a newline to avoid missing newlines.
Files:
docs/admin/templates/extending-templates/prebuilt-workspaces.md
🔇 Additional comments (5)
docs/admin/templates/extending-templates/prebuilt-workspaces.md (5)
3-8: No actionable feedback for this introductory wording – reads clearly.
51-51: No issues – the inline clarification of86400is helpful.
122-125: Good call-out to prefer prebuild-specific schedulingThe important note cleanly steers admins away from regular workspace scheduling.
161-165: Nothing to flag – option list is concise and accurate.
168-172: Scheduling flow description looks correct and the numbering trick renders fine.
closes #18806
preview
Summary by CodeRabbit