Skip to content

Commit 4b101f3

Browse files
EdwardAngertEdwardAngert
committed
copy edit
1 parent 1ef926a commit 4b101f3

File tree

3 files changed

+44
-44
lines changed

3 files changed

+44
-44
lines changed

‎docs/admin/templates/extending-templates/prebuilt-workspaces.md

Lines changed: 44 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
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

6062
The 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
7575
needs to define all the required parameters needed to build a workspace. These parameters are necessary in order to
7676
build 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.
8686
New 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,
8989
which is necessary for running an up-to-date workspace. For example, if
9090
an [AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) which is referenced by your template is updated,
9191
you 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

9797
Prebuilt 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
9999
any group which this user appears in.
100100

101101
Once 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)
126127
datasources.
@@ -139,7 +140,7 @@ eliminating the value of the prior pre-provisioning.
139140
Should this occur when a prebuilt workspace is claimed, all Template Admins will receive a notification which will
140141
link 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

144145
To 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
159160
initial owner (i.e. `prebuilds`), and will never change - even when the values of `data.coder_workspace_owner.me.name`
160161
and `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

165165
Should certain mutable attributes be required to change, you can use a more targeted approach by providing a list of
166166
attributes 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.

‎docs/admin/templates/extending-templates/prebuilt-workspaces.png renamed to ‎docs/images/admin/templates/extend-templates/prebuilt/prebuilt-workspaces.png

File renamed without changes.

‎docs/admin/templates/extending-templates/replacement-notification.png renamed to ‎docs/images/admin/templates/extend-templates/prebuilt/replacement-notification.png

File renamed without changes.

0 commit comments

Comments
 (0)