Skip to content

docs: add how-to for rolling out a security update to every workspace - #31810

Closed
coder[bot] wants to merge 2 commits into
mainfrom
docs/roll-out-workspace-security-update
Closed

coder[bot] wants to merge 2 commits into
mainfrom
docs/roll-out-workspace-security-update

Conversation

@coder

@coder coder Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Adds an admin how-to that walks through getting a patched package (for example an updated ca-certificates after a certificate authority is compromised) into every new and existing workspace. Until now the steps were spread across image management, template versioning, update policies, automatic updates, and bulk operations.

The new page docs/templates/managing-templates/roll-out-security-updates.md covers:

  1. Rebuilding the image and pinning a new tag or digest, and why a re-pushed mutable tag can be skipped.
  2. Publishing and promoting a template version (dashboard and CLI).
  3. Making future starts use the active version: template update policy (Premium), automatic updates, and autostop requirement (Premium).
  4. Updating existing workspaces with bulk Update… or a coder list | coder update loop. It warns that bulk Start keeps the current version and that dormant workspaces are skipped.
  5. Confirming with the outdated:true filter and checking the package with coder ssh.
  6. Cases where a rebuilt image doesn't change files: dev containers, envbuilder caches, persistent home volumes, and persistent VM disks. It also covers prebuilt workspaces.

It also adds the page to the sidebar (docs/manifest/templates/managing-templates.yml, regenerated docs/manifest.json) and links to it from image-management.md and the Bulk operations section of workspace-management.md. The page links to existing pages instead of repeating them.

The CLI commands and their output were run against a local dev deployment: templates push, the coder list --search ... outdated:true table, the JSON/jq/xargs coder update -y loop, the empty result, and coder ssh ... -- dpkg-query. Dashboard steps are checked against the UI code only.

Verified against

  • site/src/pages/WorkspacesPage/WorkspacesPage.tsx, WorkspacesPageView.tsx, WorkspacesTable.tsx, BatchUpdateModalForm.tsx, batchActions.ts (Bulk actions labels, bulk Start uses the current version, bulk Update skips dormant and starts stopped workspaces, default user:me filter)
  • site/src/api/api.ts (updateWorkspace, changeWorkspaceVersion, startWorkspace)
  • site/src/pages/TemplatePage/TemplatePageHeader.tsx, TemplateLayout.tsx, TemplateVersionsPage/TemplateVersionsPage.tsx, VersionRow.tsx, TemplateVersionEditorPage/TemplateVersionEditor.tsx, PublishTemplateVersionDialog.tsx (Edit files, Build, Publish, Promote to active version, Promote…)
  • site/src/pages/TemplateSettingsPage/TemplateGeneralSettingsPage/TemplateSettingsForm.tsx, Sidebar.tsx (Operations section, require-active-version label, Premium badge, Save)
  • site/src/pages/WorkspaceSettingsPage/WorkspaceSettingsForm.tsx, Sidebar.tsx (Automatic Updates, Update Policy)
  • site/src/modules/workspaces/actions.ts, site/src/utils/workspace.tsx
  • coderd/database/dbauthz/dbauthz.go (InsertWorkspaceBuild require-active-version check, exemption for users who can update the template)
  • enterprise/coderd/coderd.go, enterprise/coderd/dbauthz/accesscontrol.go, codersdk/deployment.go (access_control Premium gating; bulk actions not license-gated)
  • coderd/autobuild/lifecycle_executor.go, coderd/workspaces.go (autostart uses the active version under the policy or always)
  • coderd/rbac/roles.go, docs/admin/users/groups-roles.md (Template Admin has workspace read only)
  • cli/templatepush.go (--activate default true), cli/templateedit.go, cli/update.go, cli/start.go (dormant activation, active-version selection), cli/list.go, cli/cliui/filter.go (--all ignores --search), cli/ssh.go
  • coderd/searchquery/search.go (outdated filter)
  • examples/templates/docker/main.tf, examples/templates/kubernetes/main.tf
  • docs/templates/extending-templates/prebuilt-workspaces.md, docs/admin/integrations/devcontainers/envbuilder/envbuilder-security-caching.md, docs/workspaces/devcontainers/working-with-dev-containers.md

Open questions for the reviewer

  • envbuilder caching: envbuilder isn't in this repo, so I couldn't confirm that changing the base image reference (for example to a new digest) always avoids a cached image. The page says to change the reference and links the upstream caching doc. An envbuilder expert should confirm.
  • Docker and Kubernetes pull behavior for re-pushed mutable tags is described from the vendors' documented defaults and the example templates. I didn't test it on a real cluster.
  • workspace-management.md Bulk operations still says "top-right Actions dropdown", but the UI label is Bulk actions. I left it alone to avoid conflicting with docs(docs/user-guides): clarify who confirms bulk workspace actions #31137, which edits the same section. Should it be fixed there or here?
  • The template update policy has several names: "Template update policies" in the docs, the UI checkbox "Require workspaces automatically update when started.", and --require-active-version. index.md still tells readers to enable "Template Update Policies", which doesn't match the UI. Not changed here.
  • Doc-check suggestion not applied: adding links to the new page from change-management.md and index.md#update-templates, which is outside this change's scope.
  • Dashboard steps were checked against the UI code, not run in a browser.

Generated by Coder Agents.

Closes DOCS-1354

@coder
coder Bot requested a review from nickvigilante November 5, 2026 20:37
@linear-code

linear-code Bot commented Nov 5, 2026

Copy link
Copy Markdown

DOCS-1354

@github-actions github-actions Bot added the community Pull Requests and issues created by the community. label Nov 5, 2026
@nickvigilante

Copy link
Copy Markdown
Collaborator

Closing and reopening under a human author, as required for this repository.

@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 10, 2026

This branch was previously deployed

1 inactive deployment
main — b728111b Deployed Nov 10, 2026 by nickvigilante via community-label #253444
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants