## Description
Adds a brief section to the API & Session Tokens documentation
explaining API key scopes.
## Changes
- Added "API Key Scopes" section to
`docs/admin/users/sessions-tokens.md`
- Includes overview of scope functionality and security benefits
- Documents scope format (`resource:action`) and wildcard usage
- Provides CLI examples for creating scoped tokens
- Lists common scope examples with descriptions
## Motivation
Users need documentation on how to create and use scoped API tokens for
improved security by limiting token permissions to only necessary
operations.
## Testing
- Reviewed documentation formatting
- Verified markdown structure
- Confirmed examples are accurate
For experimental and dogfood purposes, this adds the ability to opt in a single template.
Leaving the rest of the templates as is.
For GA, this setting might be removed or changed.
Propose Microsoft Entra ID OIDC Directions for Admin Documentation based
on my personal experience / setup.
Propose information on changing access URL in Tutorials -> FAQs
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: DevCats <chris@dualriver.com>
Co-authored-by: DevelopmentCats <christofer@coder.com>
## Add Dynamic Parameters test procedure to 10k users validated architecture
This PR adds a new test procedure for Dynamic Parameters to the 10k users validated architecture documentation. No changes to the recommended hardware specs as this test case succeeded with no issues.
Adds a new document for our ongoing efforts achieving 10k user scale. The content is caveated as work in progress, but represents what we have tested so far.
closes: https://github.com/coder/internal/issues/1025
## Description
Add missing provisionerd metrics to Prometheus documentation:
* `coderd_provisionerd_num_daemons`: The number of provisioner daemons.
* `coderd_provisionerd_workspace_build_timings_seconds`: The time taken
for a workspace to build.
Related to internal thread:
https://codercom.slack.com/archives/C07GRNNRW03/p1760642020583019
## Description
Follow-up from: https://github.com/coder/coder/pull/20305 to include a
note about `coder_workspace_tags` being cumulative and a new step to
validate the status of the prebuild provisioners.
Fix steps formatting.
## Description
Update the Prebuilds troubleshooting page to include a new section,
“Preventing prebuild queue contention (recommended)”, outlining a
best-practice configuration to prevent prebuild jobs from overwhelming
the provisioner queue.
This setup introduces a dedicated prebuild provisioner pool and has been
successfully tested internally in dogfood:
https://github.com/coder/dogfood/pull/201
Closes: https://github.com/coder/coder/issues/20241
This PR adds troubleshooting steps to guide Coder operators when they
suspect that prebuilds might have overwhelmed their deployments.
Closes https://github.com/coder/coder/issues/19490
---------
Co-authored-by: Susana Ferreira <susana@coder.com>
Audit Log entries can be deleted safely (with appropriate caveats), but
we don't specifically call this out in the docs.
---------
Signed-off-by: Danny Kopping <danny@coder.com>
Solves #15575
Adds OAuth access token revocation when unlinking external auth
provider. Due to revocation not being consistently implemented by
providers this is only best effort attempt. Unsuccessful revocation
won't influence link removal.
Dynamic parameters are now GA as of v2.25.0, so this PR updates the
troubleshooting section to remove outdated beta references and clarify
current support.
**Changes:**
- Updated "Template variables not showing up" section to remove beta
references
- Clarified that template variables are fully supported in GA version
- Simplified troubleshooting guidance
Fixes the outdated documentation mentioned in the Slack thread.
---------
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
Co-authored-by: bpmct <22407953+bpmct@users.noreply.github.com>
Co-authored-by: david-fraley <67079030+david-fraley@users.noreply.github.com>
## Description
Adds support for sending an ad‑hoc custom notification to the
authenticated user via API and CLI. This is useful for surfacing the
result of scripts or long‑running tasks. Notifications are delivered
through the configured method and the dashboard Inbox, respecting
existing preferences and delivery settings.
## Changes
* New notification template: “Custom Notification” with a label for a
custom title and a custom message.
* New API endpoint: `POST /api/v2/notifications/custom` to send a custom
notification to the requesting user.
* New API endpoint: `GET /notifications/templates/custom` to get custom
notification template.
* New CLI subcommand: `coder notifications custom <title> <message>` to
send a custom notification to the requesting user.
* Documentation updates: Add a “Custom notifications” section under
Administration > Monitoring > Notifications, including instructions on
sending custom notifications and examples of when to use them.
Closes: https://github.com/coder/coder/issues/19611
I noticed that our docs mention the possibility of using the
Tailscale-managed DERP server fleet.
https://github.com/coder/coder/pull/15901 changed the phrasing from
> However, Tailscale has graciously allowed us to use
to
> However, our Wireguard integration through Tailscale has graciously
allowed us to use
This change alters the original meaning of the sentence. AFAIK, the
original meant that we contacted Tailscale directly and asked if it
would be ok for our customers to use the Tailscale-managed DERP server
fleet, and Tailscale graciously agreed. The new phrasing conveys
something different. This PR reverts the phrasing to the original.
---------
Co-authored-by: david-fraley <67079030+david-fraley@users.noreply.github.com>
## Description
This PR introduces one counter and two histograms related to workspace
creation and claiming. The goal is to provide clearer observability into
how workspaces are created (regular vs prebuild) and the time cost of
those operations.
### `coderd_workspace_creation_total`
* Metric type: Counter
* Name: `coderd_workspace_creation_total`
* Labels: `organization_name`, `template_name`, `preset_name`
This counter tracks whether a regular workspace (not created from a
prebuild pool) was created using a preset or not.
Currently, we already expose `coderd_prebuilt_workspaces_claimed_total`
for claimed prebuilt workspaces, but we lack a comparable metric for
regular workspace creations. This metric fills that gap, making it
possible to compare regular creations against claims.
Implementation notes:
* Exposed as a `coderd_` metric, consistent with other workspace-related
metrics (e.g. `coderd_api_workspace_latest_build`:
https://github.com/coder/coder/blob/main/coderd/prometheusmetrics/prometheusmetrics.go#L149).
* Every `defaultRefreshRate` (1 minute ), DB query
`GetRegularWorkspaceCreateMetrics` is executed to fetch all regular
workspaces (not created from a prebuild pool).
* The counter is updated with the total from all time (not just since
metric introduction). This differs from the histograms below, which only
accumulate from their introduction forward.
### `coderd_workspace_creation_duration_seconds` &
`coderd_prebuilt_workspace_claim_duration_seconds`
* Metric types: Histogram
* Names:
* `coderd_workspace_creation_duration_seconds`
* Labels: `organization_name`, `template_name`, `preset_name`, `type`
(`regular`, `prebuild`)
* `coderd_prebuilt_workspace_claim_duration_seconds`
* Labels: `organization_name`, `template_name`, `preset_name`
We already have `coderd_provisionerd_workspace_build_timings_seconds`,
which tracks build run times for all workspace builds handled by the
provisioner daemon.
However, in the context of this issue, we are only interested in
creation and claim build times, not all transitions; additionally, this
metric does not include `preset_name`, and adding it there would
significantly increase cardinality. Therefore, separate more focused
metrics are introduced here:
* `coderd_workspace_creation_duration_seconds`: Build time to create a
workspace (either a regular workspace or the build into a prebuild pool,
for prebuild initial provisioning build).
* `coderd_prebuilt_workspace_claim_duration_seconds`: Time to claim a
prebuilt workspace from the pool.
The reason for two separate histograms is that:
* Creation (regular or prebuild): provisioning builds with similar time
magnitude, generally expected to take longer than a claim operation.
* Claim: expected to be a much faster provisioning build.
#### Native histogram usage
Provisioning times vary widely between projects. Using static buckets
risks unbalanced or poorly informative histograms.
To address this, these metrics use [Prometheus native
histograms](https://prometheus.io/docs/specs/native_histograms/):
* First introduced in Prometheus v2.40.0
* Recommended stable usage from v2.45+
* Requires Go client `prometheus/client_golang` v1.15.0+
* Experimental and must be explicitly enabled on the server
(`--enable-feature=native-histograms`)
For compatibility, we also retain a classic bucket definition (aligned
with the existing provisioner metric:
https://github.com/coder/coder/blob/main/provisionerd/provisionerd.go#L182-L189).
* If native histograms are enabled, Prometheus ingests the
high-resolution histogram.
* If not, it falls back to the predefined buckets.
Implementation notes:
* Unlike the counter, these histograms are updated in real-time at
workspace build job completion.
* They reflect data only from the point of introduction forward (no
historical backfill).
## Relates to
Closes: https://github.com/coder/coder/issues/19528
Native histograms tested in observability stack:
https://github.com/coder/observability/pull/50
We've successfully migrated the latest iteration of our scaletest
infrastructure (`scaletest/terraform/action`) to
https://github.com/coder/scaletest (private repo). This PR removes the
older iterations, and the scriptsfor spinning up & running the load
generators against that infrastructure (`scaletest.sh`). The tooling for
generating load against a Coder deployment remains untouched, as does
the public documentation for that tooling (i.e. `coder exp scaletest`).
If we ever need that old scaletest Terraform code, it's always in the
git history!
closes https://github.com/coder/coder/issues/18274
This pull request makes system users visible in various group related
queries so that they can be added to and removed from groups. This
allows system user quotas to be configured. System users are still
ignored in certain queries, such as when license seat consumption is
determined.
This pull request further ensures the existence of a
"coder_prebuilt_workspaces" group in any organization that needs
prebuilt workspaces
---------
Co-authored-by: Susana Ferreira <susana@coder.com>
closes#18806
- [x] scheduling limitation
- [x] dev containers limitation
- [x] edit intro
[preview](https://coder.com/docs/@18806-prebuilds-known-limits/admin/templates/extending-templates/prebuilt-workspaces)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified the introduction and administrator responsibilities for
prebuilt workspaces.
* Integrated compatibility information about DevContainers and workspace
scheduling more contextually.
* Added explicit notes on limitations with dev containers integration
and workspace autostart/autostop features.
* Improved configuration examples and clarified scheduling instructions.
* Enhanced explanations of scheduling behavior and lifecycle steps for
better understanding.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Sas Swart <sas.swart.cdk@gmail.com>
Co-authored-by: Susana Ferreira <susana@coder.com>
Closes https://github.com/coder/coder/issues/18356.
This change finds and selects a matching preset if one was not chosen
during workspace creation. This solidifies the relationship between
presets and parameters.
When a workspace is created without in explicitly chosen preset, it will
now still be eligible to claim a prebuilt workspace if one is available.
This pull request introduces support for external workspace management, allowing users to register and manage workspaces that are provisioned and managed outside of the Coder.
* Added has_external_agent field to workspace builds and template versions
## Summary
- Add a provider-specific guide for configuring Google as an OIDC
provider
- Document refresh token setup via CODER_OIDC_AUTH_URL_PARAMS
- Add page to docs navigation under Users → OIDC Authentication
## Test plan
- Docs site builds: `docs/admin/users/oidc-auth/google.md` renders
- Nav shows 'Google' under OIDC Authentication
- Links to OIDC overview and refresh tokens work
Fixes#13508
---------
Co-authored-by: Atif Ali <atif@coder.com>
closes https://github.com/coder/coder/issues/18274
This pull request makes system users visible in various group related
queries so that they can be added to and removed from groups. This
allows system user quotas to be configured. System users are still
ignored in certain queries, such as when license seat consumption is
determined.
This pull request further ensures the existence of a
"coder_prebuilt_workspaces" group in any organization that needs
prebuilt workspaces
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Organization and group member listings now include system users.
* **Bug Fixes**
* Updated tests to reflect the inclusion of system users in member and
group queries.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Current example fails since kubectl version 1.31:
```sh
$ kubectl exec -it deployment/coder /bin/bash -n coder
error: exec [POD] [COMMAND] is not supported anymore. Use exec [POD] -- [COMMAND] instead
```
The legacy syntax was removed in:
https://github.com/kubernetes/kubernetes/pull/125437
# Add OAuth2 Provider Documentation
This PR adds comprehensive documentation for the experimental OAuth2
Provider feature, which allows Coder to function as an OAuth2
authorization server. The documentation covers:
- Feature overview and experimental status warning
- Setup requirements and enabling the feature
- Methods for creating OAuth2 applications (UI and API)
- Integration patterns including standard OAuth2 and PKCE flows
- Discovery endpoints and token management
- Testing and development guidance
- Troubleshooting common issues
- Security considerations and current limitations
The documentation is marked as experimental and includes appropriate
warnings about production usage.
Signed-off-by: Thomas Kosiewski <tk@coder.com>
## Summary
- Updated documentation references to use the correct registry path
structure
- Changed URLs from incorrect paths to the correct format:
- Modules main page: registry.coder.com/modules
- Specific modules: registry.coder.com/modules/coder/{module-name}
## Test plan
- Verify that all documentation links to modules point to the correct
URL structure
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
Solves https://github.com/coder/coder/issues/15096
This is a slight rework/refactor of the earlier PRs from @dannykopping
and @Emyrk:
- https://github.com/coder/coder/pull/15669
- https://github.com/coder/coder/pull/15684
- https://github.com/coder/coder/pull/17596
Rather than having a per-app CORS behaviour setting and additionally a
template level setting for ports, this PR adds a single template level
CORS behaviour setting that is then used by all apps/ports for
workspaces created from that template.
The main changes are in `proxy.go` and `request.go` to:
a) get the CORS behaviour setting from the template
b) have `HandleSubdomain` bypass the CORS middleware handler if the
selected behaviour is `passthru`
c) in `proxyWorkspaceApp`, do not modify the response if the selected
behaviour is `passthru`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added support for configuring CORS behavior ("simple" or "passthru")
at the template level for all shared ports.
* Introduced a new "CORS Behavior" setting in the template creation and
settings forms.
* API endpoints and responses now include the optional `cors_behavior`
property for templates.
* Workspace apps and proxy now honor the specified CORS behavior,
enabling conditional CORS middleware application.
* Enhanced workspace app tests with comprehensive scenarios covering
CORS behaviors and authentication states.
* **Bug Fixes**
* None.
* **Documentation**
* Updated API and admin documentation to describe the new
`cors_behavior` property and its usage.
* Added examples and schema references for CORS behavior in relevant API
docs.
* **Tests**
* Extended automated tests to cover different CORS behavior scenarios
for templates and workspace apps.
* **Chores**
* Updated audit logging to track changes to the `cors_behavior` field on
templates.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Signed-off-by: Callum Styan <callumstyan@gmail.com>
closes#18833
replace suggestions to use the now-deprecated `CODER_VERBOSE` with more
specific `CODER_LOG_FILTER`
thanks @UnicornyRainbow!
---------
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Cian Johnston