Skip to content

Commit a0249be

Browse files
ammarioammario
authored
docs: better explain persistent resources (#4703)
1 parent 54261b6 commit a0249be

File tree

6 files changed

+104
-9
lines changed

6 files changed

+104
-9
lines changed

‎docs/images/icons/infinity.svg

Lines changed: 1 addition & 0 deletions
Loading

‎docs/manifest.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,13 @@
100100
"path": "./templates.md",
101101
"icon_path": "./images/icons/picture.svg",
102102
"children": [
103+
{
104+
"title": "Resource Persistence",
105+
"description": "Learn how resource persistence works in Coder",
106+
"path": "./templates/resource-persistence.md",
107+
"icon_path": "./images/icons/infinity.svg",
108+
"last_updated": "2022-10-23"
109+
},
103110
{
104111
"title": "Provider Authentication",
105112
"description": "Learn how to authenticate the provisioner",

‎docs/templates.md

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -164,13 +164,10 @@ resource "docker_image" "workspace" {
164164
}
165165
```
166166

167-
### Persistent vs. ephemeral resources
168-
169-
You can use the workspace state to ensure some resources in Coder are
170-
persistent, while others are ephemeral.
171-
172167
#### Start/stop
173168

169+
[Learn about resource persistence in Coder](./templates/resource-persistence.md)
170+
174171
Coder workspaces can be started/stopped. This is often used to save on cloud costs or enforce
175172
ephemeral workflows. When a workspace is started or stopped, the Coder server
176173
runs an additional
@@ -180,7 +177,7 @@ Coder provider that the workspace has a new transition state.
180177
This template sample has one persistent resource (docker volume) and one ephemeral resource
181178
(docker image).
182179

183-
```sh
180+
```hcl
184181
data "coder_workspace" "me" {
185182
}
186183

‎docs/templates/resource-persistence.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Resource Persistence
2+
3+
Coder templates have full control over workspace ephemerality. In a
4+
completely ephemeral workspace, there are zero resources in the On state. In
5+
a completely persistent workspace, there is no difference between the Off and
6+
On states.
7+
8+
Most workspaces fall somewhere in the middle, persisting user data
9+
such as filesystem volumes, but deleting expensive, reproducible resources
10+
such as compute instances.
11+
12+
By default, all Coder resources are persistent, but
13+
production templates **must** employ the practices laid out in this document
14+
to prevent accidental deletion.
15+
16+
## Disabling Persistence
17+
18+
The [`coder_workspace` data source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace) exposes the `start_count = [0 | 1]` attribute that other
19+
resources reference to become ephemeral.
20+
21+
For example:
22+
23+
```hcl
24+
data "coder_workspace" "me" {
25+
}
26+
27+
resource "docker_container" "workspace" {
28+
# When `start_count` is 0, `count` is 0, so no `docker_container` is created.
29+
count = data.coder_workspace.me.start_count # 0 (stopped), 1 (started)
30+
# ... other config
31+
}
32+
```
33+
34+
## ⚠️ Persistence Pitfalls
35+
36+
Take this example resource:
37+
38+
```hcl
39+
data "coder_workspace" "me" {
40+
}
41+
42+
resource "docker_volume" "home_volume" {
43+
name = "coder-${data.coder_workspace.me.owner}-home"
44+
}
45+
```
46+
47+
Because we depend on `coder_workspace.me.owner`, if the owner changes their
48+
username, Terraform would recreate the volume (wiping its data!) the next
49+
time the workspace restarts.
50+
51+
Therefore, persistent resource names must only depend on immutable IDs such as:
52+
* `coder_workspace.me.owner_id`
53+
* `coder_workspace.me.id`
54+
55+
```hcl
56+
data "coder_workspace" "me" {
57+
}
58+
59+
resource "docker_volume" "home_volume" {
60+
# This volume will survive until the Workspace is deleted or the template
61+
# admin changes this resource block.
62+
name = "coder-${data.coder_workspace.id}-home"
63+
}
64+
```
65+
66+
## 🛡 Bulletproofing
67+
Even if our persistent resource depends exclusively on static IDs, a change to
68+
the `name` format or other attributes would cause Terraform to rebuild the resource.
69+
70+
Prevent Terraform from recreating the resource under any circumstance by setting the [`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
71+
72+
```hcl
73+
data "coder_workspace" "me" {
74+
}
75+
76+
resource "docker_volume" "home_volume" {
77+
# This resource will survive until either the entire block is deleted
78+
# or the workspace is.
79+
name = "coder-${data.coder_workspace.me.id}-home"
80+
lifecycle {
81+
ignore_changes = all
82+
}
83+
}
84+
```
85+
86+
## Up next
87+
88+
- [Templates](../templates.md)

‎docs/workspaces.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,8 @@ any activity or if there was a [template
2727
update](./templates.md#start/stop) available.
2828

2929
Resources are often destroyed and re-created when a workspace is restarted,
30-
though the exact behavior depends on the template's definitions. For more
31-
information, see [persistent vs. ephemeral
32-
resources](./templates.md#persistent-vs-ephemeral-resources).
30+
though the exact behavior depends on the template. For more
31+
information, see [Resource Persistence](./templates/resource-persistence.md).
3332

3433
> ⚠️ To avoid data loss, refer to your template documentation for information on
3534
> where to store files, install software, etc., so that they persist. Default

‎dogfood/main.tf

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,9 @@ resource "coder_app" "code-server" {
5454

5555
resource "docker_volume" "home_volume" {
5656
name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}-home"
57+
lifecycle {
58+
ignore_changes = all
59+
}
5760
}
5861

5962
resource "coder_metadata" "home_info" {

0 commit comments

Comments
 (0)