docs: better explain persistent resources (#4703)

docs/images/icons/infinity.svg

@@ -0,0 +1 @@
+<svg width="24px" height="24px" viewBox="0 0 24 24" version="1.2" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg"><path d="M16.433 8.596c-1.153 0-2.237.449-3.036 1.246l-1.396 1.34-1.375-1.32c-.815-.817-1.901-1.266-3.055-1.266-1.154 0-2.239.451-3.053 1.266-.817.816-1.267 1.9-1.267 3.055 0 1.152.449 2.238 1.266 3.053.814.816 1.899 1.266 3.054 1.266 1.153 0 2.239-.449 3.036-1.248l1.395-1.338 1.376 1.32c.815.816 1.901 1.266 3.055 1.266s2.238-.449 3.053-1.266c.817-.814 1.267-1.9 1.267-3.055s-.449-2.238-1.266-3.055c-.817-.815-1.901-1.264-3.054-1.264zm-7.576 5.605c-.687.688-1.884.688-2.572 0-.344-.344-.533-.801-.533-1.285 0-.486.189-.941.535-1.287.342-.344.799-.533 1.284-.533s.942.189 1.305.551l1.321 1.27-1.34 1.284zm8.861 0c-.687.689-1.866.705-2.59-.018l-1.321-1.27 1.339-1.285c.688-.688 1.886-.688 2.573-.002.344.346.533.801.533 1.287s-.19.944-.534 1.288z"/></svg>

docs/manifest.json

@@ -100,6 +100,13 @@
       "path": "./templates.md",
       "icon_path": "./images/icons/picture.svg",
       "children": [
+        {
+          "title": "Resource Persistence",
+          "description": "Learn how resource persistence works in Coder",
+          "path": "./templates/resource-persistence.md",
+          "icon_path": "./images/icons/infinity.svg",
+          "last_updated": "2022-10-23"
+        },
         {
           "title": "Provider Authentication",
           "description": "Learn how to authenticate the provisioner",

docs/templates.md

@@ -164,13 +164,10 @@ resource "docker_image" "workspace" {
 }
 ```
 
-### Persistent vs. ephemeral resources
-
-You can use the workspace state to ensure some resources in Coder are
-persistent, while others are ephemeral.
-
 #### Start/stop
 
+[Learn about resource persistence in Coder](./templates/resource-persistence.md)
+
 Coder workspaces can be started/stopped. This is often used to save on cloud costs or enforce
 ephemeral workflows. When a workspace is started or stopped, the Coder server
 runs an additional
@@ -180,7 +177,7 @@ Coder provider that the workspace has a new transition state.
 This template sample has one persistent resource (docker volume) and one ephemeral resource
 (docker image).
 
-```sh
+```hcl
 data "coder_workspace" "me" {
 }
 

docs/templates/resource-persistence.md

@@ -0,0 +1,88 @@
+# Resource Persistence
+
+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.
+
+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
+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 reference to become ephemeral.
+
+For example:
+
+```hcl
+data "coder_workspace" "me" {
+}
+
+resource "docker_container" "workspace" {
+  # 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
+}
+```
+
+## ⚠️ Persistence Pitfalls
+
+Take this example resource:
+
+```hcl
+data "coder_workspace" "me" {
+}
+
+resource "docker_volume" "home_volume" {
+  name = "coder-${data.coder_workspace.me.owner}-home"
+}
+```
+
+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. 
+
+Therefore, persistent resource names must only depend on immutable IDs such as:
+* `coder_workspace.me.owner_id`
+* `coder_workspace.me.id`
+
+```hcl
+data "coder_workspace" "me" {
+}
+
+resource "docker_volume" "home_volume" {
+  # This volume will survive until the Workspace is deleted or the template
+  # admin changes this resource block.
+  name = "coder-${data.coder_workspace.id}-home"
+}
+```
+
+## 🛡 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" {
+}
+
+resource "docker_volume" "home_volume" {
+  # This resource will survive until either the entire block is deleted
+  # or the workspace is.
+  name = "coder-${data.coder_workspace.me.id}-home"
+  lifecycle {
+    ignore_changes = all
+  }
+}
+```
+
+## Up next
+
+- [Templates](../templates.md)

docs/workspaces.md

@@ -27,9 +27,8 @@ any activity or if there was a [template
 update](./templates.md#start/stop) available.
 
 Resources are often destroyed and re-created when a workspace is restarted,
-though the exact behavior depends on the template's definitions. For more
-information, see [persistent vs. ephemeral
-resources](./templates.md#persistent-vs-ephemeral-resources).
+though the exact behavior depends on the template. For more
+information, see [Resource Persistence](./templates/resource-persistence.md).
 
 > ⚠️ To avoid data loss, refer to your template documentation for information on
 > where to store files, install software, etc., so that they persist. Default

dogfood/main.tf

@@ -54,6 +54,9 @@ resource "coder_app" "code-server" {
 
 resource "docker_volume" "home_volume" {
   name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}-home"
+  lifecycle {
+    ignore_changes = all
+  }
 }
 
 resource "coder_metadata" "home_info" {