started 'extending templates' rearranged resource persistence

coder · matifali · May 22, 2024 · May 23, 2024 · May 23, 2024 · May 23, 2024
commit bc7db22c47afc02f7276e2ea62919e82ac374a3c
diff --git a/docs/admin/templates/concepts.md b/docs/admin/templates/concepts.md
@@ -0,0 +1,35 @@
+# Extending templates
+
+There are a variety of Coder-native features to extend the configuration of your development environments.
+
+<!-- TODO: May divide into sub-pages later. -->
+
+## Workspace agents
+
+## Resource persistence
+
+The resources you define in a template may be _ephemeral_ or _persistent_. Persistent resources stay provisioned when workspaces are stopped, where as ephemeral resources are destroyed and recreated on restart. All resources are destroyed when a workspace is deleted.
+
+> You can read more about how resource behavior and workspace state in the  [workspace lifecycle documentation](../workspaces/lifecycle.md).
+
+Template resources follow the [behavior of Terraform resources](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration) and can be further configured  using the [lifecycle argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle).
+
+### Example usage
+
+A common configuration is a template whose only persistent resource is the home directory. This allows the developer to retain their work while ensuring the rest of their environment is consistently up-to-date on each workspace restart.
+
+
+## Template variables
+
+## Parameters
+
+## Coder apps
+
+### App ordering
+
+## Agent metadata
+
+
+<children>
+
+</children>
diff --git a/docs/admin/templates/managing-templates.md b/docs/admin/templates/managing-templates.md
@@ -58,6 +58,12 @@ infrastructure, software, or security patches. Learn more about
 
 ![Updating a template](../../images/templates/update.png)
 
+### Template update policies (enterprise)
+
+Enterprise template admins may want workspaces to always remain on the latest version of their parent template. To do so, enable **Template Update Policies** in the template's general settings. All non-admin users of the template will be forced to update their workspaces before starting them once the setting is applied. Workspaces which leverage autostart or start-on-connect will be automatically updated on the next startup.
+
+![Template update policies](../../images/templates/update-policies.png)
+
 ## Delete templates
 
 You can delete a template using both the coder CLI and UI. Only

diff --git a/docs/admin/workspaces/lifecycle.md b/docs/admin/workspaces/lifecycle.md
@@ -7,15 +7,9 @@ This page covers how workspaces move through this lifecycle. To learn about auto
 
 ## Workspace ephemerality
 
-In Coder, your workspaces are composed of resources which may be _ephemeral_ or _persistent_. Persistent resources stay provisioned when the workspace is stopped, where as ephemeral resources are destroyed and recreated on restart. All resources are destroyed when a workspace is deleted.
+Workspaces are composed of resources which may be _ephemeral_ or _persistent_. Persistent resources stay provisioned when the workspace is stopped, where as ephemeral resources are destroyed and recreated on restart. All resources are destroyed when a workspace is deleted.
 
-A common example of their usage is to have a workspace whose only persistent resource is the home directory. This allows the developer to retain their work while ensuring the rest of their environment is consistently up-to-date on each workspace restart.
-
-The persistence of resources in your workspace is determined by Terraform in your template. Read more from the official documentation on [Terraform resource behavior](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration) and how to configure it using the [lifecycle argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle).
-
-<!-- TODO: Template resource persistence link
-https://coder.com/docs/templates/resource-persistence
- -->
+> Template administrators can learn more about resource configuration in the [extending templates docs](../templates/concepts.md).
 
 ## Workspace States
 
@@ -73,7 +67,7 @@ Typically, when a workspace is deleted, all of the workspace's resources are del
 
 During a workspace start or stop build, one of two errors may lead to a broken state. If the call to `terraform apply` fails to correctly provision resources, a workspace build has **failed**. If the computational resources fail to connect the agent, a workspace becomes **unhealthy**.
 
-A failed workspace is most often caused by misalignment from the definition in your template's Terraform file and the target resources on your infrastructure. Unhealthy workspaces are usually caused by a misconfiguration in the agent or startup scripts it runs.
+A failed workspace is most often caused by misalignment from the definition in your template's Terraform file and the target resources on your infrastructure. Unhealthy workspaces are usually caused by a misconfiguration in the agent or workspace startup scripts.
 
 <!-- TODO: Needs review/addition -->
 

diff --git a/docs/admin/workspaces/schedule.md b/docs/admin/workspaces/schedule.md
diff --git a/docs/images/templates/update-policies.png b/docs/images/templates/update-policies.png