Builds on #30782, which is merged; the branch now merges `main`. Adds `Coder.LatinAbbreviations`, a Vale rule that enforces [Latin abbreviations](https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#latin-abbreviations). - Suggests "for example", "that is", and "and so on" for `e.g.`, `i.e.`, and `etc.`, including `eg.`, `ie.`, and a missing final period (`e.g`). - Severity: `suggestion`. Scope: `docs/**` except `docs/.style/style-guide/**`, limited to paragraphs, lists, headings, and blockquotes. Table cells and code are skipped. - Baseline: 170 findings in 91 files. The brief estimated 148. - Cleanup: 153 findings fixed across 81 hand-written pages, 0 left in linted pages. The count is lower than the original 158 because other PRs on `main` already rewrote or removed some of the lines, and `parameters.md` was deleted on `main`. - `vs.` and `et al.` aren't flagged. Commits: 1. `docs(docs): use English forms of Latin abbreviations` 2. `feat(docs/.style): enable Coder.LatinAbbreviations Vale rule` Generated pages: `.vale.ini` skips `docs/reference/{api,cli}/*.md` and `docs/admin/setup/configuration-reference.md` for this rule, as it does for `Coder.UnitSpacing`. Their prose comes from CLI flag help text and Swagger comments in Go source, and `make gen` rewrites them, so a hand edit fails the `gen` check (an earlier revision of this PR edited `configuration-reference.md` and failed `gen` for that reason). Cleaning them means editing Go and regenerating the help golden files and API docs, which is left for a follow-up. Linear: DOCS-450 <details> <summary>Decision log</summary> - `extends: substitution`, so the message names the replacement: "Consider 'for example' instead of 'e.g.'". - `scope: [paragraph, list, heading, blockquote]`. The single scope `paragraph` skips list items, blockquotes, and headings, so all four are listed. Table cells have their own scope and stay excluded. - Explicit `[Ee]` and `[Ii]` classes with `ignorecase: false`, so sentence-initial `E.g.,` still matches but the browser name `IE.` doesn't. - `eg.` and `ie.` require the trailing period so ordinary words and file extensions stay quiet. - Cleanup rules, applied by script and then reviewed line by line: - `e.g.` and `i.e.` become "for example," and "that is," (capitalized at the start of a sentence), with a comma added when the original had none. - `etc.` becomes "and so on", with the sentence-ending period kept when `etc.` closed the sentence. - Lines inside table rows, fenced blocks, and code spans are untouched, so are the style guide and the generated pages. - Hard-wrapped lines keep their wrapping, and CRLF files keep CRLF. - The rest of the Vale output is unchanged: the per-rule counts for every other rule match the pre-cleanup run. Test cases (fixtures under `/tmp/latin-test/`, not committed), run with LF and CRLF line endings: - Flagged (15 each): `e.g.,` in a paragraph, `i.e.,`, `etc.` at the end of a sentence and before a comma, `eg.`, `ie.`, `e.g` and `i.e` without the final period, `E.g.,`, `I.e.,`, `Etc.`, a blockquote, a list item, a numbered item, and a heading. - Not flagged: a table row with `e.g.,`, `i.e.,`, and `etc.`, code spans, a fenced block, "for example", "that is", "and so on", `IE.`, `genre`, `series`, `egg`, `tie`, `etcetera`, `vs.`, `et al.`. - Known edge case: a path-like token such as `path/i.e/x` outside code matches. It doesn't occur in the corpus. Checks: - `vale --output=line docs/`: 0 `Coder.LatinAbbreviations` findings. - `go run ./scripts/styleclaims` passes. - The pre-commit-light hook passes on both commits. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.*
234 lines
8.8 KiB
Markdown
234 lines
8.8 KiB
Markdown
---
|
|
title: Persistent shared workspaces with service accounts
|
|
---
|
|
|
|
> [!NOTE]
|
|
> This guide requires a [Premium license](https://coder.com/pricing#compare-plans) because service accounts are a Premium feature.
|
|
> For more details, [contact your account team](https://coder.com/contact).
|
|
|
|
This guide walks through setting up a long-lived workspace that is owned by a service account and shared with a rotating set of users.
|
|
Because no single person owns the workspace, it persists across team changes and every user authenticates as themselves.
|
|
|
|
This pattern is useful for any scenario where a workspace outlives the people who use it:
|
|
|
|
- **On-call rotations**:
|
|
Engineers share a workspace pre-loaded with runbooks, dashboards, and monitoring tools.
|
|
Access rotates with the shift schedule.
|
|
- **Shared staging or QA**:
|
|
A team workspace hosts a persistent staging environment.
|
|
Testers and reviewers are added and removed as sprints change.
|
|
- **Pair programming**:
|
|
A service-account-owned workspace gives two or more developers a shared environment without either one owning (and accidentally deleting) it.
|
|
- **Contractor onboarding**:
|
|
An external team gets scoped access to a workspace for the duration of an engagement, then access is revoked.
|
|
|
|
The steps below use an **on-call SRE workspace** as a running example, but the same commands apply to any of the scenarios above.
|
|
Substitute the usernames, group names, and template to match your use case.
|
|
|
|
## Prerequisites
|
|
|
|
- A running Coder deployment (v2.32+) with workspace sharing enabled.
|
|
Sharing is on by default for OSS; Premium deployments may require [admin configuration](../user-guides/shared-workspaces.md#policies).
|
|
- The [Coder CLI](../install/index.md) installed and authenticated.
|
|
- An account with the `Owner` or `User Admin` role.
|
|
- [OIDC authentication](../admin/users/oidc-auth/index.md) configured so shared users log in with their corporate SSO identity.
|
|
Configure [refresh tokens](../admin/users/oidc-auth/refresh-tokens.md) to prevent session timeouts during long work sessions.
|
|
- A [wildcard access URL](../admin/networking/wildcard-access-url.md) configured (for example, `*.coder.example.com`) so that shared users can access workspace apps without a 404.
|
|
- (Recommended) [IdP Group Sync](../admin/users/idp-sync.md#group-sync) configured if your identity provider manages group membership for the teams that will share the workspace.
|
|
|
|
## 1. Create a service account
|
|
|
|
Create a dedicated service account that will own the shared workspace.
|
|
Service accounts are non-human accounts intended for automation and shared ownership.
|
|
Because no individual user owns the workspace, there are no personal credentials to expose and the shared environment is not affected when any user leaves the team or the organization.
|
|
|
|
```sh
|
|
# On-call example — substitute a name that fits your use case
|
|
coder users create \
|
|
--username oncall-sre \
|
|
--service-account
|
|
```
|
|
|
|
## 2. Generate an API token for the service account
|
|
|
|
Generate a long-lived API token so you can create and manage workspaces on behalf of the service account:
|
|
|
|
```sh
|
|
coder tokens create \
|
|
--user oncall-sre \
|
|
--name oncall-automation \
|
|
--lifetime 8760h
|
|
```
|
|
|
|
Store this token securely (for example, in a secrets manager like Vault or AWS Secrets Manager).
|
|
|
|
> [!IMPORTANT]
|
|
> Never distribute this token to end users.
|
|
> The token is for workspace administration only.
|
|
> Shared users authenticate as themselves and reach the workspace through sharing.
|
|
|
|
## 3. Create the workspace
|
|
|
|
Authenticate as the service account and create the workspace:
|
|
|
|
```sh
|
|
export CODER_SESSION_TOKEN="<token-from-step-2>"
|
|
|
|
coder create oncall-sre/oncall-workspace \
|
|
--template your-oncall-template \
|
|
--use-parameter-defaults \
|
|
--yes
|
|
```
|
|
|
|
> [!TIP]
|
|
> Design a dedicated template for the workspace with the tools your team needs pre-installed (for example, monitoring dashboards for on-call, test runners for QA).
|
|
> Set `subdomain = true` on workspace apps so that shared users can access web-based tools without a 404.
|
|
> See [Access workspace apps in shared workspaces](../user-guides/shared-workspaces.md#access-workspace-apps-in-shared-workspaces).
|
|
|
|
## 4. Share the workspace
|
|
|
|
Use `coder sharing share` to grant access to users who need the workspace:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --user alice
|
|
```
|
|
|
|
This gives `alice` the default `use` role, which allows connection via SSH and workspace apps, starting and stopping the workspace, and viewing logs and stats.
|
|
|
|
To grant `admin` permissions (which includes all `use` permissions as well as renaming, updating, and inviting others to join with the `use` role):
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --user alice:admin
|
|
```
|
|
|
|
To share with multiple users at once:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --user alice:admin,bob
|
|
```
|
|
|
|
To share with an entire Coder group:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --group sre-oncall
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Groups can be synced from your identity provider using [IdP Sync](../admin/users/idp-sync.md#group-sync).
|
|
> If your IdP already manages team membership, sharing with a group is the simplest approach.
|
|
|
|
## 5. Rotate access
|
|
|
|
When team membership changes, remove outgoing users and add incoming ones:
|
|
|
|
```sh
|
|
# Remove outgoing user
|
|
coder sharing remove oncall-sre/oncall-workspace --user alice
|
|
|
|
# Add incoming user
|
|
coder sharing share oncall-sre/oncall-workspace --user carol
|
|
```
|
|
|
|
> [!IMPORTANT]
|
|
> The workspace must be restarted for user removal to take effect.
|
|
|
|
Verify current sharing status at any time:
|
|
|
|
```sh
|
|
coder sharing status oncall-sre/oncall-workspace
|
|
```
|
|
|
|
For every subcommand and flag, see the [`coder sharing` reference](../reference/cli/sharing/index.md).
|
|
|
|
## 6. Automate access changes (optional)
|
|
|
|
For use cases with frequent rotation (such as on-call shifts), you can integrate the share/remove commands into external tooling like PagerDuty, Opsgenie, or a cron job.
|
|
|
|
### Rotation script
|
|
|
|
```sh
|
|
#!/bin/bash
|
|
# rotate-access.sh
|
|
# Usage: ./rotate-access.sh <outgoing-user> <incoming-user>
|
|
|
|
WORKSPACE="oncall-sre/oncall-workspace"
|
|
OUTGOING="$1"
|
|
INCOMING="$2"
|
|
|
|
if [ -n "$OUTGOING" ]; then
|
|
echo "Removing access for $OUTGOING..."
|
|
coder sharing remove "$WORKSPACE" --user "$OUTGOING"
|
|
fi
|
|
|
|
echo "Granting access to $INCOMING..."
|
|
coder sharing share "$WORKSPACE" --user "$INCOMING"
|
|
|
|
echo "Restarting workspace to apply changes..."
|
|
coder restart "$WORKSPACE" --yes
|
|
|
|
echo "Current sharing status:"
|
|
coder sharing status "$WORKSPACE"
|
|
```
|
|
|
|
### Group-based rotation with IdP Sync
|
|
|
|
If your identity provider manages group membership (for example, an `sre-oncall` group in Okta or Azure AD), you can skip manual share/remove commands entirely:
|
|
|
|
1. Configure [Group Sync](../admin/users/idp-sync.md#group-sync) to synchronize the group from your IdP to Coder.
|
|
|
|
1. Share the workspace with the group once:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --group sre-oncall
|
|
```
|
|
|
|
1. When your IdP rotates group membership, Coder group membership updates on next login.
|
|
All current members have access; removed members lose access after a workspace restart.
|
|
|
|
<a id="finding-shared-workspaces"></a>
|
|
|
|
## Find shared workspaces
|
|
|
|
Shared users can find workspaces shared with them:
|
|
|
|
```sh
|
|
# List all shared workspaces you can access, including your own
|
|
coder list --search shared:true
|
|
|
|
# List workspaces shared with you
|
|
coder list --search shared_with_user:me
|
|
|
|
# List workspaces shared with a specific user
|
|
coder list --search shared_with_user:alice
|
|
|
|
# List workspaces shared with a specific group
|
|
coder list --search shared_with_group:sre-oncall
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Shared user sees 404 on workspace apps
|
|
|
|
Workspace apps using path-based routing block non-owners by default.
|
|
Configure a [wildcard access URL](../admin/networking/wildcard-access-url.md) and set `subdomain = true` on the workspace app in your template.
|
|
|
|
### Removed user still has access
|
|
|
|
Access removal requires a workspace restart.
|
|
Run `coder restart <workspace>` after removing a user or group.
|
|
|
|
### Group sync not updating membership
|
|
|
|
Group membership changes in your IdP are not reflected until the user logs out and back in.
|
|
Group sync runs at login time, not on a polling schedule.
|
|
Check the logs from `coderd`, the process that runs the control plane, with `CODER_LOG_FILTER=".*userauth.*|.*groups returned.*"` for details.
|
|
See [Troubleshooting group sync](../admin/users/idp-sync.md#troubleshooting-grouproleorganization-sync) for more information.
|
|
|
|
## Next steps
|
|
|
|
- [Shared Workspaces](../user-guides/shared-workspaces.md): full reference for workspace sharing features and UI
|
|
- [IdP Sync](../admin/users/idp-sync.md): group, role, and organization sync configuration
|
|
- [Configuring Okta](./configuring-okta.md): Okta-specific OIDC setup with custom claims and scopes
|
|
- [Security Best Practices](./best-practices/security-best-practices.md): deployment-wide security hardening
|
|
- [Sessions and Tokens](../admin/users/sessions-tokens.md): API token management and scoping
|