Skip to content

docs: add disaster recovery and emergency workspace access cutoff pages - #32356

Draft
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/docs-1214-disaster-recovery-docs
Draft

nickvigilante wants to merge 1 commit into
mainfrom
vigilante/docs-1214-disaster-recovery-docs

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Summary

Adds a disaster recovery page and a how-to for cutting off workspace access during a security incident.
Customers keep asking for more than the one-paragraph disaster recovery note in the validated architecture docs.

Changes

  • New docs/install/operate/disaster-recovery.md (explanation): database backups, restore testing, what HA does and doesn't cover, outage impact for direct and relayed connections, and orphaned resources after a restore.
  • New docs/admin/security/cut-off-workspace-access.md (how-to): common situations that need a cutoff and the best practice that prevents each, what each action blocks, ordered cutoff steps, then investigation and restoring access.
  • Sidebar entries for both pages, plus links from the sizing page's disaster recovery paragraph and the Operate landing page.

Notes for reviewers

  • The source draft says the workspace agent buffers activity while it's disconnected. The code only shows a reconnect loop (agent/agent.go runLoop), so the page says the agent keeps running and reconnects, and makes no buffering claim.
  • "Stopping the control plane doesn't end direct sessions" comes from tailnet/configmaps.go: when the coordinator connection drops, peers are marked lost and removed only after lostTimeout (15 minutes) with no WireGuard handshake. The page leaves the constant out.
  • "Suspension doesn't end open sessions" is source-verified only. putUserStatus and the API key and agent middleware reject new requests, and I found nothing that closes existing connections. I didn't run it.
  • coder list --all ignores --search (cli/cliui/filter.go), so the stop-all command uses --search "status:running" without --all.
  • The CLI pipeline isn't run against a live deployment. The jq expression was checked against the owner_name and name fields of codersdk.Workspace.
  • Bash and Zsh only. No PowerShell variant of the stop-all command.

Testing

  • make lint/emdash, make lint/docs-manifest, make lint/docs-html, and make lint/docs-redirects (offline) pass.
  • markdownlint and Vale on the new and edited pages: 0 findings.
  • Relative links and anchors on the new pages resolve.
Plan and decision log
  • Source: "Coder Disaster Recovery" PDF attached to DOCS-1214 (sections: backup, restore validation, HA, multi-region, workspace impact, orphaned workspaces after restore).
  • Added scope from Nick: failure scenarios where a deployment that drifted from best practices leads to a breach and the admin must cut off access to all workspaces right away.
  • Split into two pages because Diátaxis allows one mode per page: disaster recovery is an explanation, the cutoff is a how-to.
  • Placement: disaster recovery under Install > Operate (day-two operations, next to Upgrade). Cutoff under Admin > Security.
  • Verified against code: Terraform state in workspace_builds.provisioner_state; built-in PostgreSQL under the config root (cli/server.go); suspension rejects API keys and agent auth (coderd/httpmw/apikey.go, coderd/httpmw/workspaceagent.go); owners and self can't be suspended (coderd/users.go); coder tokens remove acts only on the caller's tokens (cli/tokens.go); expire endpoint PUT /api/v2/users/{user}/keys/{keyid}/expire; coder stop accepts owner/name (codersdk.ResolveWorkspace); dashboard page size 25.
  • Corrected from the PDF: removed the agent "buffers activity" claim; added that a restored DB still lists workspaces deleted after the backup, and documented coder delete --orphan for those.

This PR was generated by Coder Agents on behalf of @nickvigilante.

Customers ask for more than the one-paragraph disaster recovery note in
the validated architecture docs. Add a disaster recovery explanation
under Install > Operate and a how-to for cutting off workspace access
during a security incident under Admin > Security.

Refs DOCS-1214
@linear-code

linear-code Bot commented Nov 17, 2026

Copy link
Copy Markdown

DOCS-1214

This branch was successfully deployed

1 active deployment
main — d15168f9 Deployed Nov 17, 2026 by nickvigilante via cla #259026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant