chore: add workspace cleanup docs

coder · sreya · Jan 16, 2024 · Jun 12, 2023 · Oct 11, 2023 · Oct 11, 2023
commit bf605fc5b3ae3c907f468494d80a600b2c47ef67
diff --git a/docs/images/template-scheduling.png b/docs/images/template-scheduling.png
diff --git a/docs/templates/schedule.md b/docs/templates/schedule.md
@@ -0,0 +1,37 @@
+# Workspace Scheduling
+
+Templates can configure various aspects of how its workspaces are started and
+stopped, as well as manage the lifecycle of failed or inactive workspaces.
+
+![Schedule screen](../images/template-scheduling.png)
+
+## Schedule
+
+Template admins may define the default values for how long a workspace is
+permitted to run without user activity before it is automatically stopped
+as well as the maximum duration it may remain in a started state before
+it is forcibly stopped.
+
+### User scheduling
+
+For templates where a uniform autostop duration is not appropriate, admins
+may allow users to define their own autostart and autostop schedules.
+
+## Failure Cleanup (alpha)
+
+Failure cleanup defines how long a workspace is permitted to remain in the
+failed state prior to being automatically stopped. 
+
+## Dormancy Threshold (alpha)
+
+Dormancy Threshold defines how long a workspace is allowed to remain inactive
+before being moved into a dormant state. A workspace's inactivity is determined
+by the time elapsed since a user last accessed the workspace. A workspace in 
+the dormant state is not eligible for autostart and must be manually activated
+by the user before being accessible. Inactive workspaces are stopped
+during their transition to the dormant state if they are detected to be running.
+
+## Dormancy Auto-Deletion (alpha)
+
+Dormancy Auto-Deletion allows a template admin to dictate how long a
+workspace is permitted to remain dormant before it is automatically deleted.
diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -90,6 +90,24 @@ state is out of sync with the template.
 coder update <your workspace name> --always-prompt
 ```
 
+## Locking workspaces
+
+Prior to deletion, workspaces are moved into a "locked" state. A workspace can
+become locked in a couple of different ways: 
+
+- The workspace has been inactive for longer than the template's inactivity
+  threshold see [template workspace scheduling](./templates/schedule.md).
+- An admin manually locks the workspace.
+
+When a workspace is locked, the workspace is automatically stopped and unable
+to be accessed by the user (unless the user is themself an admin). A locked
+workspace is retained by default for seven days before it is permanently
+deleted. The duration a workspace remains in the locked state prior to deletion
+can be configured to an arbitrary value for enterprise deployments.
+
+In order to unlock a workspace, a user must contact the template admin or a site
+admin to unlock the workspace.
+
 ## Logging
 
 Coder stores macOS and Linux logs at the following locations: