docs: add documentation for template update policies

coder · sreya · Nov 20, 2023 · Nov 20, 2023 · Nov 20, 2023 · Nov 20, 2023
commit dc756d7dcb0783426ff98822a86e0988c46b7351
diff --git a/docs/images/templates/create-template-permissions.png b/docs/images/templates/create-template-permissions.png
diff --git a/docs/images/templates/general-settings.png b/docs/images/templates/general-settings.png
diff --git a/docs/images/templates/permissions.png b/docs/images/templates/permissions.png
diff --git a/docs/images/workspace-automatic-updates.png b/docs/images/workspace-automatic-updates.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -210,6 +210,23 @@
             }
           ]
         },
+        {
+          "title": "Administering templates",
+          "description": "Configuration settings for template admins",
+          "path": "./templates/configuration.md",
+          "children": [
+            {
+              "title": "General settings",
+              "description": "Configure name, display info, and update polices",
+              "path": "./templates/general-settings.md"
+            },
+            {
+              "title": "Permissions",
+              "description": "Configure who can access a template",
+              "path": "./templates/permissions.md"
+            }
+          ]
+        },
         {
           "title": "Open in Coder",
           "description": "Add an \"Open in Coder\" button to your repos",

diff --git a/docs/templates/configuration.md b/docs/templates/configuration.md
@@ -0,0 +1,6 @@
+# Administering Templates
+
+Templates offer a variety of configuration options to template admins.
+
+<children>
+</children>
diff --git a/docs/templates/general-settings.md b/docs/templates/general-settings.md
@@ -0,0 +1,33 @@
+# General Settings
+
+![General Settings](../images/templates/general-settings.png)
+
+## Display Info
+
+Display Info allows admins to modify how templates are displayed to users. This
+can be useful for showing a more user-friendly name in the UI along with a
+relevant icon and description.
+
+## Operations
+
+### Cancel in-progress jobs
+
+Canceling in-progress jobs allows users to cancel ongoing workspace builds.
+While this can be helpful for cases where a build is unlikely to finish, it also
+carries the risk of potentially corrupting your workspace. The setting is
+disabled by default.
+
+### Require automatic updates
+
+Admins can require all workspaces update to the latest active template version
+when they're started. This can be used to enforce security patches or other
+important changes are quickly applied to all workspaces. This setting is not
+mandatory for template admins to ensure template iteration is still possible.
+
+While this setting applies to both manual starts and
+[autostarts](../workspaces.md), promoting a template version that requires
+manual intervention by the user (such as mandatory new template paremeters) will
+result in autostart being disabled for all incompatible workspaces until a
+manual update is performed by the user.
+
+This setting is an enterprise-only feature.
diff --git a/docs/templates/permissions.md b/docs/templates/permissions.md
@@ -0,0 +1,19 @@
+# Permissions
+
+![Template Permissions](../images/templates/permissions.png)
+
+Permissions allow you to control who can use and modify the template. Both
+individual user and groups can be added to the access list for a template.
+Members can be assigned either a `Use` role, granting use of the template to
+create workspaces, or `Admin`, allowing a user or members of a group to control
+all aspects of the template. This offers a way to elevate the privileges of
+ordinary users for specific templates without granting them the site-wide role
+of `Template Admin`.
+
+By default the `Everyone` group is assigned to each template meaning any Coder
+user can use the template to create a workspace. To prevent this, disable the
+`Allow everyone to use the template` setting when creating a template.
+
+![Create Template Permissions](../images/templates/create-template-permissions.png)
+
+Permissions is an enterprise-only feature.
diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -81,6 +81,18 @@ workspace will run before Coder automatically stops it, regardless of any active
 connections. Use this setting to ensure that workspaces do not run in perpetuity
 when connections are left open inadvertently.
 
+### Automatic Updates
+
+It can be tedious to manually update a workspace everytime an update is pushed
+to a template. Users can choose to opt-in to automatic updates to update to the
+active template version whenever the workspace is started.
+
+Note: If a template is updated such that new parameter inputs are required from
+the user, autostart will be disabled for the workspace until the user has
+manually updated the workspace.
+
+![Automatic Updates](./images/workspace-automatic-updates.png)
+
 ## Updating workspaces
 
 After updating the default version of the template that a workspace was created