docs: add dev containers and scheduling to prebuilt workspaces known issues #18816
Conversation
EdwardAngert
requested review from
matifali,
the-dietcoke-ofevil,
stirby and
bartekgatzcoder
| @@ -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.
| @@ -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?
There was a problem hiding this comment.
I think it's good to duplicate info if it's in a separate "known issues" or "faq" section - that way people can find the info even if they got here without seeing the rest of the doc
| @@ -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.
docs/admin/templates/extending-templates/prebuilt-workspaces.md
Outdated
Show resolved
Hide resolved
docs/admin/templates/extending-templates/prebuilt-workspaces.md
Outdated
Show resolved
Hide resolved
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 (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
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.
| Prebuilt workspaces are not fully compatible with | ||
| [workspace scheduling features](../../../user-guides/workspace-scheduling.md) like autostart and autostop. |
There was a problem hiding this comment.
Prebuilds are not considered part of the regular workspace scheduling system.
I think it might be clearer if we explicitly mention that prebuilds have their own scheduling behavior, separate from regular workspaces. Maybe something like this:
| Prebuilt workspaces are not fully compatible with | |
| [workspace scheduling features](../../../user-guides/workspace-scheduling.md) like autostart and autostop. | |
| 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. |
| Prebuilt workspaces (prebuilds) reduce workspace creation time with an automatically-maintained pool of | ||
| ready-to-use workspaces. |
There was a problem hiding this comment.
I think it still makes sense to mention the presets: 🤔
| Prebuilt workspaces (prebuilds) reduce workspace creation time with an automatically-maintained pool of | |
| ready-to-use workspaces. | |
| Prebuilt workspaces (prebuilds) reduce 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. |
There was a problem hiding this comment.
We could also mention that prebuilds are created in the background once the template is published, this happens transparently to the user. It might help clarify how we bridge the gap between when an admin publishes a template and when a developer creates a matching workspace that can reuse an existing prebuilt instance.
|
|
||
| Prebuilt workspaces can only be used with the default organization. | ||
|
|
||
| [View issue](https://github.com/coder/internal/issues/364) |
There was a problem hiding this comment.
I think this is no longer the case. AFAIK prebuilds are now supported across all organizations (related issue: coder/internal#527)
@SasSwart might be able to confirm
closes #18806
preview
Summary by CodeRabbit