22
33## Overview
44
5- Prebuilt workspaces let you pre-provision and maintain a pool of ready-to-claim workspaces.
6- When a developer requests a workspace matching a preset, Coder assigns an existing instance instead of creating a new
7- one , reducing setup time significantly.
5+ Prebuilt workspaces let you pre-provision and maintain a pool of ready-to-deploy 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.
88
99## Prerequisites
1010
@@ -30,32 +30,34 @@ one, reducing setup time significantly.
3030 }
3131```
3232
33- 2 . Publish and import the template
34- 3 . An internal reconciliation loop maintains exactly the specified ` instances ` of prebuilt workspaces.
33+ Do not define values for ` coder_workspace ` or ` coder_workspace_owner ` .
34+ These values are [ replaced] ( #resource-replacement ) when the workspace is deployed, and if Coder detects an existing
35+ value, it will destroy the prebuilt workspace and create a new one.
3536
36- _ This model of declarative configuration plus a reconciliation loop is similar to Kubernetes._
37+ 1 . Publish and import the template.
38+ 1 . Coder automatically provisions another prebuilt workspace through an internal reconciliation loop
39+ (similar to Kubernetes) to maintain the number of specified ` instances ` .
3740
38- ## Ownership
41+ ## Workspace ownership
3942
40- When prebuilt workspaces are created, they are owned by the pseudo-user ` prebuilds ` . This user has no permissions, and
41- is simply a mechanism to identify unclaimed prebuilt workspaces.
43+ After a prebuilt workspace is created, it is owned by the unprivileged pseudo-user ` prebuilds ` , which belongs to the
44+ ` Everyone ` group.
45+ Coder uses the ` prebuilds ` user to identify unclaimed prebuilt workspaces.
46+ You can add the ` prebuilds ` user to additional groups if you need to.
4247
43- The ` prebuilds ` user is as a member of the ` Everyone ` group, and can be added to other groups.
48+ ## View prebuilt workspaces
4449
45- ## Viewing prebuilt workspaces
50+ You can view prebuilt workspaces in the ** Workspaces ** view in the Coder dashboard:
4651
47- Given that prebuilt workspaces are just regular workspaces, you can view them in the ** Workspaces** view in the
48- frontend:
49-
50- ![ prebuilt-workspaces.png] ( prebuilt-workspaces.png )
52+ ![ A prebuilt workspace on the dashboard] ( ../../../images/admin/templates/extend-templates/prebuilt/prebuilt-workspaces.png )
5153
5254## Claiming
5355
54- A prebuilt workspace is automatically and transparently assigned to a user when the following occurs :
56+ A prebuilt workspace is automatically and transparently assigned to a user when a :
5557
56- 1 . The user creates a new workspace via the API or the Coder web UI
57- 2 . The user selected a preset in # 1 which has been configured for prebuilds
58- 3 . A prebuilt workspace is in eligible state
58+ - User creates a new workspace via the API or the Coder web UI.
59+ - User selected a preset which has been configured for prebuilds.
60+ - Prebuilt workspace is in eligible state.
5961
6062The ownership of the prebuilt workspace will change to the requesting user, and this is referred to as a "claim".
6163
@@ -66,26 +68,24 @@ startup scripts, the workspace will be marked eligible to be claimed.
6668
6769## Relationship to workspace presets
6870
69- [ Workspace presets] ( ./parameters.md#workspace-presets-beta ) allow
70- you to configure commonly used combinations of parameters into a single option, which makes it easier for developers to
71- pick one that fits
72- their needs.
71+ [ Workspace presets] ( ./parameters.md#workspace-presets-beta ) allow you to configure commonly used combinations of
72+ parameters into a single option, which makes it easier for developers to pick one that fits their needs.
7373
74- Prebuilt workspaces need to have a preset defined to match the _ base configuration _ of a workspace, i.e. the preset
74+ Prebuilt workspaces need to have a preset defined to match the base configuration of a workspace, i.e. the preset
7575needs to define all the required parameters needed to build a workspace. These parameters are necessary in order to
7676build workspaces in the background.
7777
78- Parameters which are not required or not part of a preset can still be used with prebuilt workspaces. The preset defines
79- the minimum required set of parameters, and these are immutable.
78+ Parameters which are not required or not part of a preset can still be used with prebuilt workspaces.
79+ The preset defines the minimum required set of parameters, and these are immutable.
8080
81- ## Invalidation
81+ ## Update a prebuilt workspace
8282
83- Prebuilt workspaces are _ never _ updated after they are created.
83+ Prebuilt workspaces are not automatically updated after they are created.
8484
85- Whenever a template version changes, all prebuilt workspaces relating to an inactive template version will be destroyed.
85+ When a template version changes, all prebuilt workspaces relating to an inactive template version are destroyed.
8686New prebuilt workspaces will be provisioned for the active template version.
8787
88- Invalidating prebuilt workspaces is useful when your template version does not change but a referenced dependency does,
88+ You can invalidate a prebuilt workspace your template version does not change but a referenced dependency does,
8989which is necessary for running an up-to-date workspace. For example, if
9090an [ AMI] ( https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html ) which is referenced by your template is updated,
9191you can simply delete the prebuilt workspaces, and they will be recreated with the latest AMI.
@@ -95,32 +95,33 @@ _In future releases, we will allow operators to invalidate their prebuilt worksp
9595## Quotas
9696
9797Prebuilt workspaces can be used in conjunction with [ Resource Quotas] ( ../../users/quotas.md ) . Given
98- that all unclaimed prebuilt workspaces are [ owned] ( #ownership ) by the ` prebuilds ` user, you may configure a quota for
98+ that all unclaimed prebuilt workspaces are [ owned] ( #workspace- ownership ) by the ` prebuilds ` user, you may configure a quota for
9999any group which this user appears in.
100100
101101Once the quota is exceeded, prebuilt workspaces will fail provisioning like regular workspaces would.
102102
103103## Current Limitations
104104
105- ### Organizations
105+ - Organizations
106106
107- Prebuilt workspaces can only be utilized by the default organization.
107+ Prebuilt workspaces can only be utilized by the default organization.
108108
109- https://github.com/coder/internal/issues/364 is open to track this feature, and will be implemented in a future release.
109+ [ coder/internal # 364 ] ( https://github.com/coder/internal/issues/364 )
110110
111- ### Autoscaling
111+ - Autoscaling
112112
113- Prebuilt workspaces will remain running indefinitely until they are claimed. We do not at present have an autoscaling
114- mechanism to reduce the number of instances after working hours.
113+ Prebuilt workspaces remain running until they are claimed.
114+ We do not currently have an autoscaling mechanism to reduce the number of instances after working hours.
115115
116- https://github.com/coder/internal/issues/312 is open to track this feature, and will be implemented in a future release.
116+ [ coder/internal # 312 ] ( https://github.com/coder/internal/issues/312 )
117117
118118## Gotchas
119119
120120### Resource Replacement
121121
122- When a prebuilt workspace is created, it is initially [ owned] ( #ownership ) by the ` prebuilds ` user and a random name
123- is generated for it. When ` terraform apply ` runs, it will provide these values during provisioning in the
122+ When a prebuilt workspace is created, it is initially [ owned] ( #workspace-ownership ) by the ` prebuilds ` user and a random name
123+ is generated for it.
124+ When ` terraform apply ` runs, it will provide these values during provisioning in the
124125[ ` coder_workspace ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace ) and
125126[ ` coder_workspace_owner ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace_owner )
126127datasources.
@@ -139,7 +140,7 @@ eliminating the value of the prior pre-provisioning.
139140Should this occur when a prebuilt workspace is claimed, all Template Admins will receive a notification which will
140141link them to the build logs to investigate which resource was being replaced.
141142
142- ![ replacement- notification.png] ( replacement-notification.png )
143+ ![ Workspace replaced notification.png] ( ../../../images/admin/templates/extend-templates/prebuilt/ replacement-notification.png)
143144
144145To avoid this problem, you will need to add a ` lifecycle ` block to your resource:
145146
@@ -159,8 +160,7 @@ In the above example, the `docker_container` would be created with a `name` attr
159160initial owner (i.e. ` prebuilds ` ), and will never change - even when the values of ` data.coder_workspace_owner.me.name `
160161and ` data.coder_workspace.me.name ` change in the above example. ` name ` is immutable like ` user_data ` above.
161162
162- You can read more about ` ignore_changes `
163- here: https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes
163+ You can read more about ` ignore_changes ` in the [ Terraform documentation] ( https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes ) .
164164
165165Should certain mutable attributes be required to change, you can use a more targeted approach by providing a list of
166166attributes to ` ignore_changes ` :
@@ -196,4 +196,4 @@ resource "docker_container" "workspace" {
196196
197197### Logs
198198
199- Search for ` coderd.prebuilds: ` to gain insight into the behaviour of the reconciliation loop
199+ Search for ` coderd.prebuilds: ` to gain insight into the behavior of the reconciliation loop.
0 commit comments