Skip to content

docs: better explain persistent resources #4703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 24, 2022
Merged

docs: better explain persistent resources #4703

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2104052
docs: better explain persistent resources
ammario Oct 22, 2022
ea58254
fixup! docs: better explain persistent resources
ammario Oct 22, 2022
0ba49be
fixup! docs: better explain persistent resources
ammario Oct 23, 2022
1c8aeff
Merge remote-tracking branch 'origin/main' into docs-persistent
ammario Oct 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fixup! docs: better explain persistent resources
  • Loading branch information
@ammario
ammario committed Oct 23, 2022
commit 0ba49bef521e68261bdb6e1eddd6737d6c4bbfa9
3 changes: 2 additions & 1 deletion docs/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,8 @@
"title": "Resource Persistence",
"description": "Learn how resource persistence works in Coder",
"path": "./templates/resource-persistence.md",
"icon_path": "./images/icons/infinity.svg"
"icon_path": "./images/icons/infinity.svg",
"last_updated": "2022-10-23"
},
{
"title": "Provider Authentication",
Expand Down
30 changes: 14 additions & 16 deletions docs/templates/resource-persistence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Resource Persistence

Coder doesn't prescribe your workspace's level of ephemerality. In a
Coder templates have full control over workspace ephemerality. In a
completely ephemeral workspace, there are zero resources in the On state. In
a completely persistent workspace, there is no difference between the Off and
On states.
Expand All @@ -9,13 +9,14 @@ Most workspaces fall somewhere in the middle, persisting user data
such as filesystem volumes, but deleting expensive, reproducible resources
such as compute instances.

By default, all Coder resources are persistent, but there are practices all
production templates **must** employ to prevent accidental deletion.
By default, all Coder resources are persistent, but
production templates **must** employ the practices laid out in this document
to prevent accidental deletion.

## Disabling Persistence

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
resources use to become ephemeral.
resources reference to become ephemeral.

For example:

Expand All @@ -24,7 +25,7 @@ data "coder_workspace" "me" {
}

resource "docker_container" "workspace" {
# ephemeral resource (deleted when workspace is stopped, created when started)
# When `start_count` is 0, `count` is 0, so no `docker_container` is created.
count = data.coder_workspace.me.start_count # 0 (stopped), 1 (started)
# ... other config
}
Expand All @@ -39,16 +40,15 @@ data "coder_workspace" "me" {
}

resource "docker_volume" "home_volume" {
# Coder will recreate and wipe this volume if the owner changes their username.
name = "coder-${data.coder_workspace.me.owner}-home"
}
```

Because we depend on `coder_workspace.me.owner`, if the owner changed their
username, Terraform would recreate the volume (wiping the data) the next
time the workspace restarted.
Because we depend on `coder_workspace.me.owner`, if the owner changes their
username, Terraform would recreate the volume (wiping its data!) the next
time the workspace restarts.

Thus, persistent resource names must depend on immutable IDs such as:
Therefore, persistent resource names must only depend on immutable IDs such as:
* `coder_workspace.me.owner_id`
* `coder_workspace.me.id`

Expand All @@ -63,13 +63,11 @@ resource "docker_volume" "home_volume" {
}
```

## Bulletproofing
Even if we depend exclusively static IDs, a change to the `name` format or other
attributes would cause Terraform to rebuild the resource.

Bulletproof persistent resources by setting the [`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes). This
setting prevents Terraform from recreating the resource under any circumstance.
## 🛡 Bulletproofing
Even if our persistent resource depends exclusively on static IDs, a change to
the `name` format or other attributes would cause Terraform to rebuild the resource.

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).

```hcl
data "coder_workspace" "me" {
Expand Down