You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Prebuilt workspaces allow template administrators to improve the developer experience by reducing workspace
4
+
creation time with an automatically maintained pool of ready-to-use workspaces for specific parameter presets.
4
5
5
-
Prebuilt workspaces let you pre-provision and maintain a pool of ready-to-use workspaces.
6
-
Instead of creating a new workspace when a developer requests one, if a workspace matches a preset defined in the
7
-
template parameters, Coder assigns an existing instance, reducing setup time significantly.
6
+
The template administrator configures a template to provision prebuilt workspaces in the background, and then when a developer creates
7
+
a new workspace that matches the preset, Coder assigns them an existing prebuilt instance.
8
+
Prebuilt workspaces significantly reduce wait times, especially for templates with complex provisioning or lengthy startup procedures.
9
+
10
+
Prebuilt workspaces are:
11
+
12
+
- Created and maintained automatically by Coder to match your specified preset configurations.
13
+
- Claimed transparently when developers create workspaces.
14
+
- Monitored and replaced automatically to maintain your desired pool size.
8
15
9
16
## Prerequisites
10
17
11
-
- Premium license
12
-
- Use `coder/coder` Terraform provider `>= 2.3.0-pre2` in your template (**TODO: update with latest version**)
13
-
- Enable the `workspace-prebuilds`[experiment](../../../reference/cli/server.md#--experiments)
18
+
-[**Premium license**](../../licensing/index.md)
19
+
-**Compatible Terraform provider**: Use `coder/coder` Terraform provider `>= 2.3.0-pre2`. (**TODO: update with latest version**)
20
+
-**Feature flag**: Enable the `workspace-prebuilds`[experiment](../../../reference/cli/server.md#--experiments).
14
21
15
-
## Configuration
22
+
## Enable prebuilt workspaces for template presets
16
23
17
-
1. In your Terraform template, add a `prebuilds` block within a `coder_workspace_preset` block:
24
+
In your template, add a `prebuilds` block within a `coder_workspace_preset` block to identify how many prebuilt
25
+
instances your Coder deployment should maintain:
18
26
19
27
```hcl
20
28
data "coder_workspace_preset" "goland" {
@@ -25,120 +33,113 @@ template parameters, Coder assigns an existing instance, reducing setup time sig
25
33
memory = 16
26
34
}
27
35
prebuilds {
28
-
instances = 3
36
+
instances = 3 # Number of prebuilt workspaces to maintain
29
37
}
30
38
}
31
39
```
32
40
33
-
1. Publish and import the template.
34
-
1. Coder automatically provisions another prebuilt workspace through an internal reconciliation loop
35
-
(similar to Kubernetes) to maintain the number of specified `instances`.
41
+
After you create or update the template, Coder automatically provisions and maintains prebuilt workspaces through an
42
+
internal reconciliation loop (similar to Kubernetes) to maintain the number of specified `instances`.
36
43
37
-
## Workspace ownership
44
+
Prebuilt workspaces are displayed in the list of workspaces on the Coder dashboard with the owner set to `prebuilds`.
38
45
39
-
After a prebuilt workspace is created, it is owned by the unprivileged pseudo-user `prebuilds`, which belongs to the
40
-
`Everyone` group.
41
-
Coder uses the `prebuilds` user to identify unclaimed prebuilt workspaces.
42
-
You can add the `prebuilds` user to additional groups if you need to.
46
+
## Prebuilt workspace lifecycle
43
47
44
-
## View prebuilt workspaces
48
+
Prebuilt workspaces follow a specific lifecycle from creation through eligibility to claiming.
45
49
46
-
You can view prebuilt workspaces in the **Workspaces** view in the Coder dashboard:
50
+
Expand each item in this list for more information about the stage:
47
51
48
-
52
+
1. <details><summary>After you configure a preset with a prebuilt workspace and publish the template, Coder provisions
53
+
the prebuilt workspace(s).</summary>
49
54
50
-
## Claiming
55
+
1. Coder automatically creates prebuilt workspaces up to the specified `instances` count.
56
+
1. Each new prebuild is initially owned by an unprivileged system pseudo-user named `prebuilds`.
57
+
- The `prebuilds` user belongs to the `Everyone` group (you can add it to additional groups if needed).
58
+
1. Each prebuilt workspace receives a randomly generated name for identification.
59
+
1. The workspace is provisioned like a regular workspace.
51
60
52
-
A prebuilt workspace is automatically and transparently assigned to a user when a:
61
+
</details>
53
62
54
-
- User creates a new workspace via the API or the Coder web UI.
55
-
- User selected a preset which has been configured for prebuilds.
56
-
- Prebuilt workspace is in an eligible state.
63
+
1. <details><summary>Coder prepares the prebuilt workspace to be claimed by a developer.</summary>
57
64
58
-
The ownership of the prebuilt workspace will change to the requesting user, and this is referred to as a "claim".
65
+
Before a prebuilt workspace is available to users:
59
66
60
-
## Eligibility
67
+
1. The workspace reaches `running` state.
68
+
1. The agent connects to coderd.
69
+
1. The agent starts its bootstrap procedures and startup scripts complete successfully.
70
+
1. The agent reports `ready` status.
61
71
62
-
When a prebuilt workspace is running, and its agent has completed all of its bootstrap procedures and executed its
63
-
startup scripts, the workspace will be marked eligible to be claimed.
72
+
Prebuilt workspaces that fail during provisioning are retried with an exponential backoff to prevent transient failures.
64
73
65
-
## Relationship to workspace presets
74
+
</details>
66
75
67
-
[Workspace presets](./parameters.md#workspace-presets-beta) allow you to configure commonly used combinations of
68
-
parameters into a single option, which makes it easier for developers to pick one that fits their needs.
76
+
1. <details><summary>When a developer selects requests a new workspace, the claiming process occurs:</summary>
69
77
70
-
Prebuilt workspaces need to have a preset defined to match the base configuration of a workspace, i.e. the preset
71
-
needs to define all the required parameters needed to build a workspace. These parameters are necessary in order to
72
-
build workspaces in the background.
78
+
1. Developer selects a template and preset that has prebuilt workspaces configured.
79
+
1. If an eligible prebuilt workspace exists, it's automatically assigned to the user.
80
+
1. Ownership transfers from the `prebuilds` user to the requesting user.
81
+
1. The workspace name changes to the user's requested name.
82
+
1. The process is transparent to the developer - they simply see a workspace ready faster than normal.
73
83
74
-
Parameters which are not required or not part of a preset can still be used with prebuilt workspaces.
75
-
The preset defines the minimum required set of parameters, and these are immutable.
84
+
This ownership transfer happens automatically without any special action required by the user.
76
85
77
-
## Update a prebuilt workspace
86
+
</details>
78
87
79
-
Prebuilt workspaces are not automatically updated after they are created.
88
+
You can view available prebuilt workspaces in the **Workspaces** view in the Coder dashboard:
80
89
81
-
When a template version changes, all prebuilt workspaces relating to an inactive template version are destroyed.
82
-
New prebuilt workspaces will be provisioned for the active template version.
83
-
84
-
You may want to invalidate a prebuilt workspace when your template version does not change but a referenced dependency does,
85
-
which is necessary for running an up-to-date workspace. For example, if
86
-
an [AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) which is referenced by your template is updated,
87
-
you can simply delete the prebuilt workspaces, and they will be recreated with the latest AMI.
90
+
88
91
89
-
_In future releases, we will allow operators to invalidate their prebuilt workspaces programmatically._
92
+
### Template updates and the prebuilt workspace lifecycle
90
93
91
-
## Quotas
94
+
Prebuilt workspaces have specific behavior when templates are updated:
92
95
93
-
Prebuilt workspaces can be used in conjunction with [Resource Quotas](../../users/quotas.md). Given
94
-
that all unclaimed prebuilt workspaces are [owned](#workspace-ownership) by the `prebuilds` user, you may configure a quota for
95
-
any group which this user appears in.
96
+
1. When a template version changes, prebuilt workspaces for old versions are automatically deleted.
97
+
1. New prebuilt workspaces are created for the active template version.
98
+
1. Prebuilt workspaces aren't automatically updated after creation.
99
+
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 can:
100
+
- Delete the existing prebuilt workspaces manually.
101
+
- Coder will automatically create new prebuilt workspaces with the updated dependencies.
96
102
97
-
Once the quota is exceeded, prebuilt workspaces will fail provisioning like regular workspaces would.
103
+
The system always maintains the desired number of prebuilt workspaces for the active template version.
98
104
99
-
##Current Limitations
105
+
### Relationship to workspace presets
100
106
101
-
- Organizations
107
+
Prebuilt workspaces are tightly integrated with [workspace presets](./parameters.md#workspace-presets-beta):
102
108
103
-
Prebuilt workspaces can only be utilized by the default organization.
109
+
1. Each prebuilt workspace is associated with a specific template preset.
110
+
1. The preset must define all required parameters needed to build the workspace.
111
+
1. The preset parameters define the base configuration and are immutable after they're claimed.
112
+
1. Parameters that are not defined in the preset can still be customized by users when they claim a workspace.
In the above example, the `docker_container` would be created with a `name` attribute which includes references to the
156
-
initial owner (i.e. `prebuilds`), and will never change - even when the values of `data.coder_workspace_owner.me.name`
157
-
and `data.coder_workspace.me.name` change in the above example. `name` is immutable like `user_data` above.
158
-
159
-
You can read more about `ignore_changes`in the [Terraform documentation](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
160
-
161
-
Should certain mutable attributes be required to change, you can use a more targeted approach by providing a list of
162
-
attributes to `ignore_changes`:
156
+
For more targeted control, specify which attributes to ignore:
Learn more about `ignore_changes` in the [Terraform documentation](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
171
+
172
+
### Current limitations
173
+
174
+
The prebuilt workspaces feature has these current limitations:
175
+
176
+
-**Organizations**
177
+
178
+
Prebuilt workspaces can only be used with the default organization.
0 commit comments