synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-12 00:14:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2023-08-23 12:27:57 +03:00
committed by GitHub
parent ed2b1236c0
commit d37f6d80f7
96 changed files with 2838 additions and 1457 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/admin/app-logs.md
View File

@ -1,21 +1,28 @@
# Application Logs
In Coderd, application logs refer to the records of events, messages, and activities generated by the application during its execution.
These logs provide valuable information about the application's behavior, performance, and any issues that may have occurred.
In Coderd, application logs refer to the records of events, messages, and
activities generated by the application during its execution. These logs provide
valuable information about the application's behavior, performance, and any
issues that may have occurred.
Application logs include entries that capture events on different levels of severity:
Application logs include entries that capture events on different levels of
severity:
- Informational messages
- Warnings
- Errors
- Debugging information
By analyzing application logs, system administrators can gain insights into the application's behavior, identify and diagnose problems, track performance metrics, and make informed decisions to improve the application's stability and efficiency.
By analyzing application logs, system administrators can gain insights into the
application's behavior, identify and diagnose problems, track performance
metrics, and make informed decisions to improve the application's stability and
efficiency.
## Error logs
To ensure effective monitoring and timely response to critical events in the Coder application, it is recommended to configure log alerts
that specifically watch for the following log entries:
To ensure effective monitoring and timely response to critical events in the
Coder application, it is recommended to configure log alerts that specifically
watch for the following log entries:
| Log Level | Module | Log message | Potential issues |
| --------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |

12
docs/admin/appearance.md
View File

@ -2,12 +2,15 @@
## Support Links
Support links let admins adjust the user dropdown menu to include links referring to internal company resources. The menu section replaces the original menu positions: documentation, report a bug to GitHub, or join the Discord server.
Support links let admins adjust the user dropdown menu to include links
referring to internal company resources. The menu section replaces the original
menu positions: documentation, report a bug to GitHub, or join the Discord
server.
![support links](../images/admin/support-links.png)
Custom links can be set in the deployment configuration using the `-c <yamlFile>`
flag to `coder server`.
Custom links can be set in the deployment configuration using the
`-c <yamlFile>` flag to `coder server`.
```yaml
supportLinks:
@ -27,7 +30,8 @@ The link icons are optional, and limited to: `bug`, `chat`, and `docs`.
## Service Banners (enterprise)
Service Banners let admins post important messages to all site users. Only Site Owners may set the service banner.
Service Banners let admins post important messages to all site users. Only Site
Owners may set the service banner.
![service banners](../images/admin/service-banners.png)

40
docs/admin/audit-logs.md
View File

@ -1,7 +1,6 @@
# Audit Logs
Audit Logs allows **Auditors** to monitor user operations in
their deployment.
Audit Logs allows **Auditors** to monitor user operations in their deployment.
## Tracked Events
@ -27,34 +26,48 @@ We track the following resources:
## Filtering logs
In the Coder UI you can filter your audit logs using the pre-defined filter or by using the Coder's filter query like the examples below:
In the Coder UI you can filter your audit logs using the pre-defined filter or
by using the Coder's filter query like the examples below:
- `resource_type:workspace action:delete` to find deleted workspaces
- `resource_type:template action:create` to find created templates
The supported filters are:
- `resource_type` - The type of the resource. It can be a workspace, template, user, etc. You can [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ResourceType) all the resource types that are supported.
- `resource_type` - The type of the resource. It can be a workspace, template,
user, etc. You can
[find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ResourceType)
all the resource types that are supported.
- `resource_id` - The ID of the resource.
- `resource_target` - The name of the resource. Can be used instead of `resource_id`.
- `action`- The action applied to a resource. You can [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#AuditAction) all the actions that are supported.
- `username` - The username of the user who triggered the action. You can also use `me` as a convenient alias for the logged-in user.
- `resource_target` - The name of the resource. Can be used instead of
`resource_id`.
- `action`- The action applied to a resource. You can
[find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#AuditAction)
all the actions that are supported.
- `username` - The username of the user who triggered the action. You can also
use `me` as a convenient alias for the logged-in user.
- `email` - The email of the user who triggered the action.
- `date_from` - The inclusive start date with format `YYYY-MM-DD`.
- `date_to` - The inclusive end date with format `YYYY-MM-DD`.
- `build_reason` - To be used with `resource_type:workspace_build`, the [initiator](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#BuildReason) behind the build start or stop.
- `build_reason` - To be used with `resource_type:workspace_build`, the
[initiator](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#BuildReason)
behind the build start or stop.
## Capturing/Exporting Audit Logs
In addition to the user interface, there are multiple ways to consume or query audit trails.
In addition to the user interface, there are multiple ways to consume or query
audit trails.
## REST API
Audit logs can be accessed through our REST API. You can find detailed information about this in our [endpoint documentation](../api/audit.md#get-audit-logs).
Audit logs can be accessed through our REST API. You can find detailed
information about this in our
[endpoint documentation](../api/audit.md#get-audit-logs).
## Service Logs
Audit trails are also dispatched as service logs and can be captured and categorized using any log management tool such as [Splunk](https://splunk.com).
Audit trails are also dispatched as service logs and can be captured and
categorized using any log management tool such as [Splunk](https://splunk.com).
Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
@ -93,10 +106,11 @@ Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
Example of a [human readable](../cli/server.md#--log-human) audit log entry:
```sh
```console
2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip=<nil> UserAgent=<nil> ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon=""
```
## Enabling this feature
This feature is only available with an enterprise license. [Learn more](../enterprise.md)
This feature is only available with an enterprise license.
[Learn more](../enterprise.md)

239
docs/admin/auth.md
View File

@ -14,12 +14,19 @@ The following steps explain how to set up GitHub OAuth or OpenID Connect.
### Step 1: Configure the OAuth application in GitHub
First, [register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). GitHub will ask you for the following Coder parameters:
First,
[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
GitHub will ask you for the following Coder parameters:
- **Homepage URL**: Set to your Coder deployments [`CODER_ACCESS_URL`](https://coder.com/docs/v2/latest/cli/server#--access-url) (e.g. `https://coder.domain.com`)
- **Homepage URL**: Set to your Coder deployments
[`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g.
`https://coder.domain.com`)
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
> Note: If you want to allow multiple coder deployments hosted on subdomains e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the same GitHub OAuth app, then you can set **User Authorization Callback URL** to the `https://domain.com`
> Note: If you want to allow multiple coder deployments hosted on subdomains
> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
> the `https://domain.com`
Note the Client ID and Client Secret generated by GitHub. You will use these
values in the next step.
@ -29,17 +36,18 @@ values in the next step.
Navigate to your Coder host and run the following command to start up the Coder
server:
```console
```shell
coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
```
> For GitHub Enterprise support, specify the `--oauth2-github-enterprise-base-url` flag.
> For GitHub Enterprise support, specify the
> `--oauth2-github-enterprise-base-url` flag.
Alternatively, if you are running Coder as a system service, you can achieve the
same result as the command above by adding the following environment variables
to the `/etc/coder.d/coder.env` file:
```console
```env
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
@ -48,7 +56,7 @@ CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
**Note:** To allow everyone to signup using GitHub, set:
```console
```env
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
```
@ -76,7 +84,7 @@ coder:
To upgrade Coder, run:
```console
```shell
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
```
@ -86,7 +94,8 @@ helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
## OpenID Connect
The following steps through how to integrate any OpenID Connect provider (Okta, Active Directory, etc.) to Coder.
The following steps through how to integrate any OpenID Connect provider (Okta,
Active Directory, etc.) to Coder.
### Step 1: Set Redirect URI with your OIDC provider
@ -99,15 +108,15 @@ Your OIDC provider will ask you for the following parameter:
Navigate to your Coder host and run the following command to start up the Coder
server:
```console
```shell
coder server --oidc-issuer-url="https://issuer.corp.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
```
If you are running Coder as a system service, you can achieve the
same result as the command above by adding the following environment variables
to the `/etc/coder.d/coder.env` file:
If you are running Coder as a system service, you can achieve the same result as
the command above by adding the following environment variables to the
`/etc/coder.d/coder.env` file:
```console
```env
CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
CODER_OIDC_CLIENT_ID="533...des"
@ -134,46 +143,46 @@ coder:
To upgrade Coder, run:
```console
```shell
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
```
## OIDC Claims
When a user logs in for the first time via OIDC, Coder will merge both
the claims from the ID token and the claims obtained from hitting the
upstream provider's `userinfo` endpoint, and use the resulting data
as a basis for creating a new user or looking up an existing user.
When a user logs in for the first time via OIDC, Coder will merge both the
claims from the ID token and the claims obtained from hitting the upstream
provider's `userinfo` endpoint, and use the resulting data as a basis for
creating a new user or looking up an existing user.
To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs
while signing in via OIDC as a new user. Coder will log the claim fields
returned by the upstream identity provider in a message containing the
string `got oidc claims`, as well as the user info returned.
To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs while
signing in via OIDC as a new user. Coder will log the claim fields returned by
the upstream identity provider in a message containing the string
`got oidc claims`, as well as the user info returned.
> **Note:** If you need to ensure that Coder only uses information from
> the ID token and does not hit the UserInfo endpoint, you can set the
> configuration option `CODER_OIDC_IGNORE_USERINFO=true`.
> **Note:** If you need to ensure that Coder only uses information from the ID
> token and does not hit the UserInfo endpoint, you can set the configuration
> option `CODER_OIDC_IGNORE_USERINFO=true`.
### Email Addresses
By default, Coder will look for the OIDC claim named `email` and use that
value for the newly created user's email address.
By default, Coder will look for the OIDC claim named `email` and use that value
for the newly created user's email address.
If your upstream identity provider users a different claim, you can set
`CODER_OIDC_EMAIL_FIELD` to the desired claim.
> **Note:** If this field is not present, Coder will attempt to use the
> claim field configured for `username` as an email address. If this field
> is not a valid email address, OIDC logins will fail.
> **Note** If this field is not present, Coder will attempt to use the claim
> field configured for `username` as an email address. If this field is not a
> valid email address, OIDC logins will fail.
### Email Address Verification
Coder requires all OIDC email addresses to be verified by default. If
the `email_verified` claim is present in the token response from the identity
Coder requires all OIDC email addresses to be verified by default. If the
`email_verified` claim is present in the token response from the identity
provider, Coder will validate that its value is `true`. If needed, you can
disable this behavior with the following setting:
```console
```env
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
```
@ -182,14 +191,14 @@ CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
### Usernames
When a new user logs in via OIDC, Coder will by default use the value
of the claim field named `preferred_username` as the the username.
When a new user logs in via OIDC, Coder will by default use the value of the
claim field named `preferred_username` as the the username.
If your upstream identity provider uses a different claim, you can
set `CODER_OIDC_USERNAME_FIELD` to the desired claim.
If your upstream identity provider uses a different claim, you can set
`CODER_OIDC_USERNAME_FIELD` to the desired claim.
> **Note:** If this claim is empty, the email address will be stripped of
> the domain, and become the username (e.g. `example@coder.com` becomes `example`).
> **Note:** If this claim is empty, the email address will be stripped of the
> domain, and become the username (e.g. `example@coder.com` becomes `example`).
> To avoid conflicts, Coder may also append a random word to the resulting
> username.
@ -198,36 +207,38 @@ set `CODER_OIDC_USERNAME_FIELD` to the desired claim.
If you'd like to change the OpenID Connect button text and/or icon, you can
configure them like so:
```console
```env
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
```
## Disable Built-in Authentication
To remove email and password login, set the following environment variable on your
Coder deployment:
To remove email and password login, set the following environment variable on
your Coder deployment:
```console
```env
CODER_DISABLE_PASSWORD_AUTH=true
```
## SCIM (enterprise)
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
authentication. Upon deactivation, users are [suspended](./users.md#suspend-a-user)
and are not deleted. [Configure](./configure.md) your SCIM application with an
auth key and supply it the Coder server.
authentication. Upon deactivation, users are
[suspended](./users.md#suspend-a-user) and are not deleted.
[Configure](./configure.md) your SCIM application with an auth key and supply it
the Coder server.
```console
```env
CODER_SCIM_API_KEY="your-api-key"
```
## TLS
If your OpenID Connect provider requires client TLS certificates for authentication, you can configure them like so:
If your OpenID Connect provider requires client TLS certificates for
authentication, you can configure them like so:
```console
```env
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
```
@ -237,22 +248,31 @@ CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
If your OpenID Connect provider supports group claims, you can configure Coder
to synchronize groups in your auth provider to groups within Coder.
To enable group sync, ensure that the `groups` claim is set by adding the correct scope to request. If group sync is
enabled, the user's groups will be controlled by the OIDC provider. This means
manual group additions/removals will be overwritten on the next login.
To enable group sync, ensure that the `groups` claim is set by adding the
correct scope to request. If group sync is enabled, the user's groups will be
controlled by the OIDC provider. This means manual group additions/removals will
be overwritten on the next login.
```console
```env
# as an environment variable
CODER_OIDC_SCOPES=openid,profile,email,groups
```
```shell
# as a flag
--oidc-scopes openid,profile,email,groups
```
With the `groups` scope requested, we also need to map the `groups` claim name. Coder recommends using `groups` for the claim name. This step is necessary if your **scope's name** is something other than `groups`.
With the `groups` scope requested, we also need to map the `groups` claim name.
Coder recommends using `groups` for the claim name. This step is necessary if
your **scope's name** is something other than `groups`.
```console
```env
# as an environment variable
CODER_OIDC_GROUP_FIELD=groups
```
```shell
# as a flag
--oidc-group-field groups
```
@ -264,9 +284,12 @@ For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
or you want to have different group names in Coder than in your OIDC provider,
you can configure mapping between the two.
```console
```env
# as an environment variable
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
```
```shell
# as a flag
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
```
@ -286,7 +309,8 @@ OIDC provider will be added to the `myCoderGroupName` group in Coder.
> **Note:** Groups are only updated on login.
[azure-gids]: https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
[azure-gids]:
https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
### Troubleshooting
@ -294,22 +318,34 @@ Some common issues when enabling group sync.
#### User not being assigned / Group does not exist
If you want Coder to create groups that do not exist, you can set the following environment variable. If you enable this, your OIDC provider might be sending over many unnecessary groups. Use filtering options on the OIDC provider to limit the groups sent over to prevent creating excess groups.
If you want Coder to create groups that do not exist, you can set the following
environment variable. If you enable this, your OIDC provider might be sending
over many unnecessary groups. Use filtering options on the OIDC provider to
limit the groups sent over to prevent creating excess groups.
```console
```env
# as an environment variable
CODER_OIDC_GROUP_AUTO_CREATE=true
```
```shell
# as a flag
--oidc-group-auto-create=true
```
A basic regex filtering option on the Coder side is available. This is applied **after** the group mapping (`CODER_OIDC_GROUP_MAPPING`), meaning if the group is remapped, the remapped value is tested in the regex. This is useful if you want to filter out groups that do not match a certain pattern. For example, if you want to only allow groups that start with `my-group-` to be created, you can set the following environment variable.
A basic regex filtering option on the Coder side is available. This is applied
**after** the group mapping (`CODER_OIDC_GROUP_MAPPING`), meaning if the group
is remapped, the remapped value is tested in the regex. This is useful if you
want to filter out groups that do not match a certain pattern. For example, if
you want to only allow groups that start with `my-group-` to be created, you can
set the following environment variable.
```console
```env
# as an environment variable
CODER_OIDC_GROUP_REGEX_FILTER="^my-group-.*$"
```
```shell
# as a flag
--oidc-group-regex-filter="^my-group-.*$"
```
@ -322,28 +358,39 @@ If you see an error like the following, you may have an invalid scope.
The application '<oidc_application>' asked for scope 'groups' that doesn't exist on the resource...
```
This can happen because the identity provider has a different name for the scope. For example, Azure AD uses `GroupMember.Read.All` instead of `groups`. You can find the correct scope name in the IDP's documentation. Some IDP's allow configuring the name of this scope.
This can happen because the identity provider has a different name for the
scope. For example, Azure AD uses `GroupMember.Read.All` instead of `groups`.
You can find the correct scope name in the IDP's documentation. Some IDP's allow
configuring the name of this scope.
The solution is to update the value of `CODER_OIDC_SCOPES` to the correct value for the identity provider.
The solution is to update the value of `CODER_OIDC_SCOPES` to the correct value
for the identity provider.
#### No `group` claim in the `got oidc claims` log
Steps to troubleshoot.
1. Ensure the user is a part of a group in the IDP. If the user has 0 groups, no `groups` claim will be sent.
2. Check if another claim appears to be the correct claim with a different name. A common name is `memberOf` instead of `groups`. If this is present, update `CODER_OIDC_GROUP_FIELD=memberOf`.
3. Make sure the number of groups being sent is under the limit of the IDP. Some IDPs will return an error, while others will just omit the `groups` claim. A common solution is to create a filter on the identity provider that returns less than the limit for your IDP.
1. Ensure the user is a part of a group in the IDP. If the user has 0 groups, no
`groups` claim will be sent.
2. Check if another claim appears to be the correct claim with a different name.
A common name is `memberOf` instead of `groups`. If this is present, update
`CODER_OIDC_GROUP_FIELD=memberOf`.
3. Make sure the number of groups being sent is under the limit of the IDP. Some
IDPs will return an error, while others will just omit the `groups` claim. A
common solution is to create a filter on the identity provider that returns
less than the limit for your IDP.
- [Azure AD limit is 200, and omits groups if exceeded.](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#options-for-applications-to-consume-group-information)
- [Okta limit is 100, and returns an error if exceeded.](https://developer.okta.com/docs/reference/api/oidc/#scope-dependent-claims-not-always-returned)
## Role sync (enterprise)
If your OpenID Connect provider supports roles claims, you can configure Coder
to synchronize roles in your auth provider to deployment-wide roles within Coder.
to synchronize roles in your auth provider to deployment-wide roles within
Coder.
Set the following in your Coder server [configuration](./configure.md).
```console
```env
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
CODER_OIDC_SCOPES=openid,profile,email,roles
@ -352,7 +399,8 @@ CODER_OIDC_USER_ROLE_FIELD=roles
CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
```
> One role from your identity provider can be mapped to many roles in Coder (e.g. the example above maps to 2 roles in Coder.)
> One role from your identity provider can be mapped to many roles in Coder
> (e.g. the example above maps to 2 roles in Coder.)
## Provider-Specific Guides
@ -362,17 +410,20 @@ Below are some details specific to individual OIDC providers.
> **Note:** Tested on ADFS 4.0, Windows Server 2019
1. In your Federation Server, create a new application group for Coder. Follow the
steps as described [here.](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/development/msal/adfs-msal-web-app-web-api#app-registration-in-ad-fs)
1. In your Federation Server, create a new application group for Coder. Follow
the steps as described
[here.](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/development/msal/adfs-msal-web-app-web-api#app-registration-in-ad-fs)
- **Server Application**: Note the Client ID.
- **Configure Application Credentials**: Note the Client Secret.
- **Configure Web API**: Set the Client ID as the relying party identifier.
- **Application Permissions**: Allow access to the claims `openid`, `email`, `profile`, and `allatclaims`.
1. Visit your ADFS server's `/.well-known/openid-configuration` URL and note
the value for `issuer`.
> **Note:** This is usually of the form `https://adfs.corp/adfs/.well-known/openid-configuration`
1. In Coder's configuration file (or Helm values as appropriate), set the following
environment variables or their corresponding CLI arguments:
- **Application Permissions**: Allow access to the claims `openid`, `email`,
`profile`, and `allatclaims`.
1. Visit your ADFS server's `/.well-known/openid-configuration` URL and note the
value for `issuer`.
> **Note:** This is usually of the form
> `https://adfs.corp/adfs/.well-known/openid-configuration`
1. In Coder's configuration file (or Helm values as appropriate), set the
following environment variables or their corresponding CLI arguments:
- `CODER_OIDC_ISSUER_URL`: the `issuer` value from the previous step.
- `CODER_OIDC_CLIENT_ID`: the Client ID from step 1.
@ -383,28 +434,44 @@ Below are some details specific to individual OIDC providers.
{"resource":"$CLIENT_ID"}
```
where `$CLIENT_ID` is the Client ID from step 1 ([see here](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional)).
This is required for the upstream OIDC provider to return the requested claims.
where `$CLIENT_ID` is the Client ID from step 1
([see here](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional)).
This is required for the upstream OIDC provider to return the requested
claims.
- `CODER_OIDC_IGNORE_USERINFO`: Set to `true`.
1. Configure [Issuance Transform Rules](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims)
1. Configure
[Issuance Transform Rules](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims)
on your federation server to send the following claims:
- `preferred_username`: You can use e.g. "Display Name" as required.
- `email`: You can use e.g. the LDAP attribute "E-Mail-Addresses" as required.
- `email`: You can use e.g. the LDAP attribute "E-Mail-Addresses" as
required.
- `email_verified`: Create a custom claim rule:
```console
=> issue(Type = "email_verified", Value = "true")
```
- (Optional) If using Group Sync, send the required groups in the configured groups claim field. See [here](https://stackoverflow.com/a/55570286) for an example.
- (Optional) If using Group Sync, send the required groups in the configured
groups claim field. See [here](https://stackoverflow.com/a/55570286) for an
example.
### Keycloak
The access_type parameter has two possible values: "online" and "offline." By default, the value is set to "offline". This means that when a user authenticates using OIDC, the application requests offline access to the user's resources, including the ability to refresh access tokens without requiring the user to reauthenticate.
The access_type parameter has two possible values: "online" and "offline." By
default, the value is set to "offline". This means that when a user
authenticates using OIDC, the application requests offline access to the user's
resources, including the ability to refresh access tokens without requiring the
user to reauthenticate.
To enable the `offline_access` scope, which allows for the refresh token functionality, you need to add it to the list of requested scopes during the authentication flow. Including the `offline_access` scope in the requested scopes ensures that the user is granted the necessary permissions to obtain refresh tokens.
To enable the `offline_access` scope, which allows for the refresh token
functionality, you need to add it to the list of requested scopes during the
authentication flow. Including the `offline_access` scope in the requested
scopes ensures that the user is granted the necessary permissions to obtain
refresh tokens.
By combining the `{"access_type":"offline"}` parameter in the OIDC Auth URL with the `offline_access` scope, you can achieve the desired behavior of obtaining refresh tokens for offline access to the user's resources.
By combining the `{"access_type":"offline"}` parameter in the OIDC Auth URL with
the `offline_access` scope, you can achieve the desired behavior of obtaining
refresh tokens for offline access to the user's resources.

37
docs/admin/automation.md
View File

@ -1,6 +1,8 @@
# Automation
All actions possible through the Coder dashboard can also be automated as it utilizes the same public REST API. There are several ways to extend/automate Coder:
All actions possible through the Coder dashboard can also be automated as it
utilizes the same public REST API. There are several ways to extend/automate
Coder:
- [CLI](../cli.md)
- [REST API](../api/)
@ -10,13 +12,13 @@ All actions possible through the Coder dashboard can also be automated as it uti
Generate a token on your Coder deployment by visiting:
```sh
```shell
https://coder.example.com/settings/tokens
```
List your workspaces
```sh
```shell
# CLI
coder ls \
--url https://coder.example.com \
@ -30,23 +32,34 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \
## Documentation
We publish an [API reference](../api/index.md) in our documentation. You can also enable a [Swagger endpoint](../cli/server.md#--swagger-enable) on your Coder deployment.
We publish an [API reference](../api/index.md) in our documentation. You can
also enable a [Swagger endpoint](../cli/server.md#--swagger-enable) on your
Coder deployment.
## Use cases
We strive to keep the following use cases up to date, but please note that changes to API queries and routes can occur. For the most recent queries and payloads, we recommend checking the CLI and API documentation.
We strive to keep the following use cases up to date, but please note that
changes to API queries and routes can occur. For the most recent queries and
payloads, we recommend checking the CLI and API documentation.
### Templates
- [Update templates in CI](../templates/change-management.md): Store all templates and git and update templates in CI/CD pipelines.
- [Update templates in CI](../templates/change-management.md): Store all
templates and git and update templates in CI/CD pipelines.
### Workspace agents
Workspace agents have a special token that can send logs, metrics, and workspace activity.
Workspace agents have a special token that can send logs, metrics, and workspace
activity.
- [Custom workspace logs](../api/agents.md#patch-workspace-agent-logs): Expose messages prior to the Coder init script running (e.g. pulling image, VM starting, restoring snapshot). [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses this to show Kubernetes events, such as image pulls or ResourceQuota restrictions.
- [Custom workspace logs](../api/agents.md#patch-workspace-agent-logs): Expose
messages prior to the Coder init script running (e.g. pulling image, VM
starting, restoring snapshot).
[coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses
this to show Kubernetes events, such as image pulls or ResourceQuota
restrictions.
```sh
```shell
curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/logs \
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
-d "{
@ -60,9 +73,11 @@ Workspace agents have a special token that can send logs, metrics, and workspace
}"
```
- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats): Keep a workspace "active," even if there is not an open connection (e.g. for a long-running machine learning job).
- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats):
Keep a workspace "active," even if there is not an open connection (e.g. for a
long-running machine learning job).
```sh
```shell
#!/bin/bash
# Send workspace activity as long as the job is still running

91
docs/admin/configure.md
View File

@ -1,23 +1,26 @@
Coder server's primary configuration is done via environment variables. For a full list of the options, run `coder server --help` or see our [CLI documentation](../cli/server.md).
Coder server's primary configuration is done via environment variables. For a
full list of the options, run `coder server --help` or see our
[CLI documentation](../cli/server.md).
## Access URL
`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the external URL
that users and workspaces use to connect to Coder (e.g. <https://coder.example.com>). This
should not be localhost.
`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the
external URL that users and workspaces use to connect to Coder (e.g.
<https://coder.example.com>). This should not be localhost.
> Access URL should be a external IP address or domain with DNS records pointing to Coder.
> Access URL should be a external IP address or domain with DNS records pointing
> to Coder.
### Tunnel
If an access URL is not specified, Coder will create
a publicly accessible URL to reverse proxy your deployment for simple setup.
If an access URL is not specified, Coder will create a publicly accessible URL
to reverse proxy your deployment for simple setup.
## Address
You can change which port(s) Coder listens on.
```sh
```shell
# Listen on port 80
export CODER_HTTP_ADDRESS=0.0.0.0:80
@ -34,22 +37,27 @@ coder server
## Wildcard access URL
`CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](../networking/port-forwarding.md#dashboard)
via the dashboard or running [coder_apps](../templates/index.md#coder-apps) on an absolute path. Set this to a wildcard
subdomain that resolves to Coder (e.g. `*.coder.example.com`).
`CODER_WILDCARD_ACCESS_URL` is necessary for
[port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard
or running [coder_apps](../templates/index.md#coder-apps) on an absolute path.
Set this to a wildcard subdomain that resolves to Coder (e.g.
`*.coder.example.com`).
If you are providing TLS certificates directly to the Coder server, either
1. Use a single certificate and key for both the root and wildcard domains.
2. Configure multiple certificates and keys via
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml) in the Helm Chart, or
[`--tls-cert-file`](../cli/server.md#--tls-cert-file) and [`--tls-key-file`](../cli/server.md#--tls-key-file) command
line options (these both take a comma separated list of files; list certificates and their respective keys in the
same order).
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
in the Helm Chart, or [`--tls-cert-file`](../cli/server.md#--tls-cert-file)
and [`--tls-key-file`](../cli/server.md#--tls-key-file) command line options
(these both take a comma separated list of files; list certificates and their
respective keys in the same order).
## TLS & Reverse Proxy
The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and accompanying configuration flags. However, Coder can also run behind a reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
accompanying configuration flags. However, Coder can also run behind a
reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
- [Apache](https://github.com/coder/coder/tree/main/examples/web-server/apache)
- [Caddy](https://github.com/coder/coder/tree/main/examples/web-server/caddy)
@ -57,17 +65,19 @@ The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and a
### Kubernetes TLS configuration
Below are the steps to configure Coder to terminate TLS when running on Kubernetes.
You must have the certificate `.key` and `.crt` files in your working directory prior to step 1.
Below are the steps to configure Coder to terminate TLS when running on
Kubernetes. You must have the certificate `.key` and `.crt` files in your
working directory prior to step 1.
1. Create the TLS secret in your Kubernetes cluster
```console
```shell
kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
```
> You can use a single certificate for the both the access URL and wildcard access URL.
> The certificate CN must match the wildcard domain, such as `*.example.coder.com`.
> You can use a single certificate for the both the access URL and wildcard
> access URL. The certificate CN must match the wildcard domain, such as
> `*.example.coder.com`.
1. Reference the TLS secret in your Coder Helm chart values
@ -87,14 +97,16 @@ coder:
## PostgreSQL Database
Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information.
Use `CODER_PG_CONNECTION_URL` to set the database that Coder connects to. If unset, PostgreSQL binaries will be
downloaded from Maven (<https://repo1.maven.org/maven2>) and store all data in the config root.
Coder uses a PostgreSQL database to store users, workspace metadata, and other
deployment information. Use `CODER_PG_CONNECTION_URL` to set the database that
Coder connects to. If unset, PostgreSQL binaries will be downloaded from Maven
(<https://repo1.maven.org/maven2>) and store all data in the config root.
> Postgres 13 is the minimum supported version.
If you are using the built-in PostgreSQL deployment and need to use `psql` (aka
the PostgreSQL interactive terminal), output the connection URL with the following command:
the PostgreSQL interactive terminal), output the connection URL with the
following command:
```console
coder server postgres-builtin-url
@ -103,21 +115,26 @@ psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
### Migrating from the built-in database to an external database
To migrate from the built-in database to an external database, follow these steps:
To migrate from the built-in database to an external database, follow these
steps:
1. Stop your Coder deployment.
2. Run `coder server postgres-builtin-serve` in a background terminal.
3. Run `coder server postgres-builtin-url` and copy its output command.
4. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal database to a file.
5. Restore that content to an external database with `psql <external-connection-string> < coder.sql`.
6. Start your Coder deployment with `CODER_PG_CONNECTION_URL=<external-connection-string>`.
4. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
database to a file.
5. Restore that content to an external database with
`psql <external-connection-string> < coder.sql`.
6. Start your Coder deployment with
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
## System packages
If you've installed Coder via a [system package](../install/packages.md) Coder, you can
configure the server by setting the following variables in `/etc/coder.d/coder.env`:
If you've installed Coder via a [system package](../install/packages.md) Coder,
you can configure the server by setting the following variables in
`/etc/coder.d/coder.env`:
```console
```env
# String. Specifies the external URL (HTTP/S) to access Coder.
CODER_ACCESS_URL=https://coder.example.com
@ -145,7 +162,7 @@ CODER_TLS_KEY_FILE=
To run Coder as a system service on the host:
```console
```shell
# Use systemd to start Coder now and on reboot
sudo systemctl enable --now coder
@ -155,15 +172,15 @@ journalctl -u coder.service -b
To restart Coder after applying system changes:
```console
```shell
sudo systemctl restart coder
```
## Configuring Coder behind a proxy
To configure Coder behind a corporate proxy, set the environment variables `HTTP_PROXY` and
`HTTPS_PROXY`. Be sure to restart the server. Lowercase values (e.g. `http_proxy`) are also
respected in this case.
To configure Coder behind a corporate proxy, set the environment variables
`HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
(e.g. `http_proxy`) are also respected in this case.
## Up Next

65
docs/admin/git-providers.md
View File

@ -1,10 +1,13 @@
# Git Providers
Coder integrates with git providers to automate away the need for developers to authenticate with repositories within their workspace.
Coder integrates with git providers to automate away the need for developers to
authenticate with repositories within their workspace.
## How it works
When developers use `git` inside their workspace, they are prompted to authenticate. After that, Coder will store and refresh tokens for future operations.
When developers use `git` inside their workspace, they are prompted to
authenticate. After that, Coder will store and refresh tokens for future
operations.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/site/static/gitauth.mp4?raw=true" type="video/mp4">
@ -13,18 +16,22 @@ Your browser does not support the video tag.
## Configuration
To add a git provider, you'll need to create an OAuth application. The following providers are supported:
To add a git provider, you'll need to create an OAuth application. The following
providers are supported:
- [GitHub](#github-app)
- [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html)
- [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
Example callback URL: `https://coder.example.com/gitauth/primary-github/callback`. Use an arbitrary ID for your provider (e.g. `primary-github`).
Example callback URL:
`https://coder.example.com/gitauth/primary-github/callback`. Use an arbitrary ID
for your provider (e.g. `primary-github`).
Set the following environment variables to [configure the Coder server](./configure.md):
Set the following environment variables to
[configure the Coder server](./configure.md):
```console
```env
CODER_GITAUTH_0_ID="primary-github"
CODER_GITAUTH_0_TYPE=github|gitlab|azure-devops|bitbucket
CODER_GITAUTH_0_CLIENT_ID=xxxxxx
@ -33,11 +40,15 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
### GitHub
1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) to enable fine-grained access to specific repositories, or a subset of permissions for security.
1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
to enable fine-grained access to specific repositories, or a subset of
permissions for security.
![Register GitHub App](../images/admin/github-app-register.png)
2. Adjust the GitHub App permissions. You can use more or less permissions than are listed here, this is merely a suggestion that allows users to clone repositories:
2. Adjust the GitHub App permissions. You can use more or less permissions than
are listed here, this is merely a suggestion that allows users to clone
repositories:
![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
@ -48,7 +59,8 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
| Workflows | Read & Write | Grants access to update files in `.github/workflows/`. |
| Metadata | Read-only | Grants access to metadata written by GitHub Apps. |
3. Install the App for your organization. You may select a subset of repositories to grant access to.
3. Install the App for your organization. You may select a subset of
repositories to grant access to.
![Install GitHub App](../images/admin/github-app-install.png)
@ -56,7 +68,7 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
GitHub Enterprise requires the following authentication and token URLs:
```console
```env
CODER_GITAUTH_0_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info"
CODER_GITAUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
@ -66,7 +78,7 @@ CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
Azure DevOps requires the following environment variables:
```console
```env
CODER_GITAUTH_0_ID="primary-azure-devops"
CODER_GITAUTH_0_TYPE=azure-devops
CODER_GITAUTH_0_CLIENT_ID=xxxxxx
@ -78,10 +90,10 @@ CODER_GITAUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
### Self-managed git providers
Custom authentication and token URLs should be
used for self-managed Git provider deployments.
Custom authentication and token URLs should be used for self-managed Git
provider deployments.
```console
```env
CODER_GITAUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
@ -91,7 +103,7 @@ CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
Optionally, you can request custom scopes:
```console
```env
CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key"
```
@ -99,9 +111,10 @@ CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key"
Multiple providers are an Enterprise feature. [Learn more](../enterprise.md).
A custom regex can be used to match a specific repository or organization to limit auth scope. Here's a sample config:
A custom regex can be used to match a specific repository or organization to
limit auth scope. Here's a sample config:
```console
```env
# Provider 1) github.com
CODER_GITAUTH_0_ID=primary-github
CODER_GITAUTH_0_TYPE=github
@ -120,20 +133,24 @@ CODER_GITAUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token"
CODER_GITAUTH_1_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info"
```
To support regex matching for paths (e.g. github.com/orgname), you'll need to add this to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
To support regex matching for paths (e.g. github.com/orgname), you'll need to
add this to the
[Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
```console
```shell
git config --global credential.useHttpPath true
```
## Require git authentication in templates
If your template requires git authentication (e.g. running `git clone` in the [startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)), you can require users authenticate via git prior to creating a workspace:
If your template requires git authentication (e.g. running `git clone` in the
[startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)),
you can require users authenticate via git prior to creating a workspace:
![Git authentication in template](../images/admin/git-auth-template.png)
The following example will require users authenticate via GitHub and auto-clone a repo
into the `~/coder` directory.
The following example will require users authenticate via GitHub and auto-clone
a repo into the `~/coder` directory.
```hcl
data "coder_git_auth" "github" {
@ -156,4 +173,6 @@ EOF
}
```
See the [Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/git_auth) for all available options.
See the
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/git_auth)
for all available options.

7
docs/admin/groups.md
View File

@ -1,9 +1,12 @@
# Groups
Groups can be used with [template RBAC](./rbac.md) to give groups of users access to specific templates. They can be defined in Coder or [synced from your identity provider](./auth.md#group-sync-enterprise).
Groups can be used with [template RBAC](./rbac.md) to give groups of users
access to specific templates. They can be defined in Coder or
[synced from your identity provider](./auth.md#group-sync-enterprise).
![Groups](../images/groups.png)
## Enabling this feature
This feature is only available with an enterprise license. [Learn more](../enterprise.md)
This feature is only available with an enterprise license.
[Learn more](../enterprise.md)

46
docs/admin/high-availability.md
View File

@ -1,35 +1,41 @@
# High Availability
High Availability (HA) mode solves for horizontal scalability and automatic failover
within a single region. When in HA mode, Coder continues using a single Postgres
endpoint. [GCP](https://cloud.google.com/sql/docs/postgres/high-availability), [AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-managed-postgresql/availability.html),
High Availability (HA) mode solves for horizontal scalability and automatic
failover within a single region. When in HA mode, Coder continues using a single
Postgres endpoint.
[GCP](https://cloud.google.com/sql/docs/postgres/high-availability),
[AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-managed-postgresql/availability.html),
and other cloud vendors offer fully-managed HA Postgres services that pair
nicely with Coder.
For Coder to operate correctly, Coderd instances should have low-latency connections
to each other so that they can effectively relay traffic between users and workspaces no
matter which Coderd instance users or workspaces connect to. We make a best-effort attempt
to warn the user when inter-Coderd latency is too high, but if requests start dropping, this
is one metric to investigate.
For Coder to operate correctly, Coderd instances should have low-latency
connections to each other so that they can effectively relay traffic between
users and workspaces no matter which Coderd instance users or workspaces connect
to. We make a best-effort attempt to warn the user when inter-Coderd latency is
too high, but if requests start dropping, this is one metric to investigate.
We also recommend that you deploy all Coderd instances such that they have low-latency
connections to Postgres. Coderd often makes several database round-trips while processing
a single API request, so prioritizing low-latency between Coderd and Postgres is more important
than low-latency between users and Coderd.
We also recommend that you deploy all Coderd instances such that they have
low-latency connections to Postgres. Coderd often makes several database
round-trips while processing a single API request, so prioritizing low-latency
between Coderd and Postgres is more important than low-latency between users and
Coderd.
Note that this latency requirement applies _only_ to Coder services. Coder will
operate correctly even with few seconds of latency on workspace <-> Coder and user <-> Coder
connections.
operate correctly even with few seconds of latency on workspace <-> Coder and
user <-> Coder connections.
## Setup
Coder automatically enters HA mode when multiple instances simultaneously connect
to the same Postgres endpoint.
Coder automatically enters HA mode when multiple instances simultaneously
connect to the same Postgres endpoint.
HA brings one configuration variable to set in each Coderd
node: `CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate
with each other. Inter-node communication is only required while using the
embedded relay (default). If you're using [custom relays](../networking/index.md#custom-relays), Coder ignores `CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the Coder nodes.
HA brings one configuration variable to set in each Coderd node:
`CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate with
each other. Inter-node communication is only required while using the embedded
relay (default). If you're using
[custom relays](../networking/index.md#custom-relays), Coder ignores
`CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the
Coder nodes.
`CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL` because
`CODER_ACCESS_URL` is a load balancer to all Coder nodes.

32
docs/admin/prometheus.md
View File

@ -1,16 +1,25 @@
# Prometheus
Coder exposes many metrics which can be consumed by a Prometheus server, and give insight into the current state of a live Coder deployment.
Coder exposes many metrics which can be consumed by a Prometheus server, and
give insight into the current state of a live Coder deployment.
If you don't have an Prometheus server installed, you can follow the Prometheus [Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/) guide.
If you don't have an Prometheus server installed, you can follow the Prometheus
[Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/)
guide.
## Enable Prometheus metrics
Coder server exports metrics via the HTTP endpoint, which can be enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the flag `--prometheus-enable`.
Coder server exports metrics via the HTTP endpoint, which can be enabled using
either the environment variable `CODER_PROMETHEUS_ENABLE` or the flag
`--prometheus-enable`.
The Prometheus endpoint address is `http://localhost:2112/` by default. You can use either the environment variable `CODER_PROMETHEUS_ADDRESS` or the flag ` --prometheus-address <network-interface>:<port>` to select a different listen address.
The Prometheus endpoint address is `http://localhost:2112/` by default. You can
use either the environment variable `CODER_PROMETHEUS_ADDRESS` or the flag
`--prometheus-address <network-interface>:<port>` to select a different listen
address.
If `coder server --prometheus-enable` is started locally, you can preview the metrics endpoint in your browser or by using curl: <!-- markdown-link-check-disable -->http://localhost:2112/<!-- markdown-link-check-enable -->.
If `coder server --prometheus-enable` is started locally, you can preview the
metrics endpoint in your browser or by using curl:
```console
$ curl http://localhost:2112/
@ -22,14 +31,17 @@ coderd_api_active_users_duration_hour 0
### Kubernetes deployment
The Prometheus endpoint can be enabled in the [Helm chart's](https://github.com/coder/coder/tree/main/helm) `values.yml` by setting the environment variable `CODER_PROMETHEUS_ADDRESS` to `0.0.0.0:2112`.
The environment variable `CODER_PROMETHEUS_ENABLE` will be enabled automatically.
The Prometheus endpoint can be enabled in the
[Helm chart's](https://github.com/coder/coder/tree/main/helm) `values.yml` by
setting the environment variable `CODER_PROMETHEUS_ADDRESS` to `0.0.0.0:2112`.
The environment variable `CODER_PROMETHEUS_ENABLE` will be enabled
automatically.
### Prometheus configuration
To allow Prometheus to scrape the Coder metrics, you will need to create a `scape_config`
in your `prometheus.yml` file, or in the Prometheus Helm chart values. Below is an
example `scrape_config`:
To allow Prometheus to scrape the Coder metrics, you will need to create a
`scape_config` in your `prometheus.yml` file, or in the Prometheus Helm chart
values. Below is an example `scrape_config`:
```yaml
scrape_configs:

104
docs/admin/provisioners.md
View File

@ -1,42 +1,63 @@
# Provisioners
By default, the Coder server runs [built-in provisioner daemons](../cli/server.md#provisioner-daemons), which execute `terraform` during workspace and template builds. However, there are sometimes benefits to running external provisioner daemons:
By default, the Coder server runs
[built-in provisioner daemons](../cli/server.md#provisioner-daemons), which
execute `terraform` during workspace and template builds. However, there are
sometimes benefits to running external provisioner daemons:
- **Secure build environments:** Run build jobs in isolated containers, preventing malicious templates from gaining shell access to the Coder host.
- **Secure build environments:** Run build jobs in isolated containers,
preventing malicious templates from gaining shell access to the Coder host.
- **Isolate APIs:** Deploy provisioners in isolated environments (on-prem, AWS, Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coder server. See [Provider Authentication](../templates/authentication.md) for more details.
- **Isolate APIs:** Deploy provisioners in isolated environments (on-prem, AWS,
Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coder
server. See [Provider Authentication](../templates/authentication.md) for more
details.
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate secrets on provisoner servers.
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate
secrets on provisoner servers.
- **Reduce server load**: External provisioners reduce load and build queue times from the Coder server. See [Scaling Coder](./scale.md#concurrent-workspace-builds) for more details.
- **Reduce server load**: External provisioners reduce load and build queue
times from the Coder server. See
[Scaling Coder](./scale.md#concurrent-workspace-builds) for more details.
Each provisioner can run a single [concurrent workspace build](./scale.md#concurrent-workspace-builds). For example, running 30 provisioner containers will allow 30 users to start workspaces at the same time.
Each provisioner can run a single
[concurrent workspace build](./scale.md#concurrent-workspace-builds). For
example, running 30 provisioner containers will allow 30 users to start
workspaces at the same time.
Provisioners are started with the [coder provisionerd start](../cli/provisionerd_start.md) command.
Provisioners are started with the
[coder provisionerd start](../cli/provisionerd_start.md) command.
## Authentication
The provisioner daemon must authenticate with your Coder deployment.
Set a [provisioner daemon pre-shared key (PSK)](../cli/server.md#--provisioner-daemon-psk) on the Coder server and start the provisioner with
`coder provisionerd start --psk <your-psk>`. If you are [installing with Helm](../install/kubernetes#install-coder-with-helm),
see the [Helm example](#example-running-an-external-provisioner-with-helm) below.
Set a
[provisioner daemon pre-shared key (PSK)](../cli/server.md#--provisioner-daemon-psk)
on the Coder server and start the provisioner with
`coder provisionerd start --psk <your-psk>`. If you are
[installing with Helm](../install/kubernetes.md#install-coder-with-helm), see
the [Helm example](#example-running-an-external-provisioner-with-helm) below.
> Coder still supports authenticating the provisioner daemon with a [token](../cli.md#--token) from a user with the
> Template Admin or Owner role. This method is deprecated in favor of the PSK, which only has permission to access
> provisioner daemon APIs. We recommend migrating to the PSK as soon as practical.
> Coder still supports authenticating the provisioner daemon with a
> [token](../cli.md#--token) from a user with the Template Admin or Owner role.
> This method is deprecated in favor of the PSK, which only has permission to
> access provisioner daemon APIs. We recommend migrating to the PSK as soon as
> practical.
## Types of provisioners
- **Generic provisioners** can pick up any build job from templates without provisioner tags.
- **Generic provisioners** can pick up any build job from templates without
provisioner tags.
```sh
```shell
coder provisionerd start
```
- **Tagged provisioners** can be used to pick up build jobs from templates (and corresponding workspaces) with matching tags.
- **Tagged provisioners** can be used to pick up build jobs from templates (and
corresponding workspaces) with matching tags.
```sh
```shell
coder provisionerd start \
--tag environment=on_prem \
--tag data_center=chicago
@ -52,11 +73,16 @@ see the [Helm example](#example-running-an-external-provisioner-with-helm) below
--provisioner-tag data_center=chicago
```
> At this time, tagged provisioners can also pick jobs from untagged templates. This behavior is [subject to change](https://github.com/coder/coder/issues/6442).
> At this time, tagged provisioners can also pick jobs from untagged
> templates. This behavior is
> [subject to change](https://github.com/coder/coder/issues/6442).
- **User provisioners** can only pick up jobs from user-tagged templates. Unlike the other provisioner types, any Coder can run user provisioners, but they have no impact unless there is at least one template with the `scope=user` provisioner tag.
- **User provisioners** can only pick up jobs from user-tagged templates. Unlike
the other provisioner types, any Coder can run user provisioners, but they
have no impact unless there is at least one template with the `scope=user`
provisioner tag.
```sh
```shell
coder provisionerd start \
--tag scope=user
@ -68,10 +94,11 @@ see the [Helm example](#example-running-an-external-provisioner-with-helm) below
## Example: Running an external provisioner with Helm
Coder provides a Helm chart for running external provisioner daemons, which you will use in concert with the Helm chart
for deploying the Coder server.
Coder provides a Helm chart for running external provisioner daemons, which you
will use in concert with the Helm chart for deploying the Coder server.
1. Create a long, random pre-shared key (PSK) and store it in a Kubernetes secret
1. Create a long, random pre-shared key (PSK) and store it in a Kubernetes
secret
```shell
kubectl create secret generic coder-provisioner-psk --from-literal=psk=`head /dev/urandom | tr -dc A-Za-z0-9 | head -c 26`
@ -84,8 +111,8 @@ for deploying the Coder server.
pskSecretName: "coder-provisioner-psk"
```
1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit `--version <your version>` to also upgrade
Coder to the latest version.
1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit
`--version <your version>` to also upgrade Coder to the latest version.
```shell
helm upgrade coder coder-v2/coder \
@ -94,7 +121,8 @@ for deploying the Coder server.
--values values.yaml
```
1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm chart. For example
1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm
chart. For example
```yaml
coder:
@ -109,11 +137,14 @@ for deploying the Coder server.
kind: k8s
```
This example creates a deployment of 10 provisioner daemons (for 10 concurrent builds) with the listed tags. For
generic provisioners, remove the tags.
This example creates a deployment of 10 provisioner daemons (for 10
concurrent builds) with the listed tags. For generic provisioners, remove the
tags.
> Refer to the [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml) file for the
> coder-provisioner chart for information on what values can be specified.
> Refer to the
> [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml)
> file for the coder-provisioner chart for information on what values can be
> specified.
1. Install the provisioner daemon chart
@ -124,12 +155,13 @@ for deploying the Coder server.
--values provisioner-values.yaml
```
You can verify that your provisioner daemons have successfully connected to Coderd by looking for a debug log message that says
You can verify that your provisioner daemons have successfully connected to
Coderd by looking for a debug log message that says
`provisionerd: successfully connected to coderd` from each Pod.
## Example: Running an external provisioner on a VM
```sh
```shell
curl -L https://coder.com/install.sh | sh
export CODER_URL=https://coder.example.com
export CODER_SESSION_TOKEN=your_token
@ -138,7 +170,7 @@ coder provisionerd start
## Example: Running an external provisioner via Docker
```sh
```shell
docker run --rm -it \
-e CODER_URL=https://coder.example.com/ \
-e CODER_SESSION_TOKEN=your_token \
@ -149,8 +181,10 @@ docker run --rm -it \
## Disable built-in provisioners
As mentioned above, the Coder server will run built-in provisioners by default. This can be disabled with a server-wide [flag or environment variable](../cli/server.md#provisioner-daemons).
As mentioned above, the Coder server will run built-in provisioners by default.
This can be disabled with a server-wide
[flag or environment variable](../cli/server.md#provisioner-daemons).
```sh
```shell
coder server --provisioner-daemons=0
```

37
docs/admin/quotas.md
View File

@ -2,19 +2,19 @@
Quotas are a mechanism for controlling spend by associating costs with workspace
templates and assigning budgets to users. Users that exceed their budget will be
blocked from launching more workspaces until they either delete their other workspaces
or get their budget extended.
blocked from launching more workspaces until they either delete their other
workspaces or get their budget extended.
For example: A template is configured with a cost of 5 credits per day,
and the user is granted 15 credits, which can be consumed by both started and
stopped workspaces. This budget limits the user to 3 concurrent workspaces.
For example: A template is configured with a cost of 5 credits per day, and the
user is granted 15 credits, which can be consumed by both started and stopped
workspaces. This budget limits the user to 3 concurrent workspaces.
Quotas are licensed with [Groups](./groups.md).
## Definitions
- **Credits** is the fundamental unit representing cost in the quota system. This integer
can be arbitrary, or it can map to your preferred currency.
- **Credits** is the fundamental unit representing cost in the quota system.
This integer can be arbitrary, or it can map to your preferred currency.
- **Budget** is the per-user, enforced, upper limit to credit spend.
- **Allowance** is a grant of credits to the budget.
@ -22,10 +22,11 @@ Quotas are licensed with [Groups](./groups.md).
Templates describe their cost through the `daily_cost` attribute in
[`resource_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata).
Since costs are associated with resources, an offline workspace may consume
less quota than an online workspace.
Since costs are associated with resources, an offline workspace may consume less
quota than an online workspace.
A common use case is separating costs for a persistent volume and ephemeral compute:
A common use case is separating costs for a persistent volume and ephemeral
compute:
```hcl
resource "docker_volume" "home_volume" {
@ -56,11 +57,11 @@ resource "coder_metadata" "workspace" {
```
When the workspace above is shut down, the `docker_container` and
`coder_metadata` both get deleted. This reduces the cost from 30 credits to
10 credits.
`coder_metadata` both get deleted. This reduces the cost from 30 credits to 10
credits.
Resources without a `daily_cost` value are considered to cost 0. If the cost
was removed on the `docker_volume` above, the template would consume 0 credits when
Resources without a `daily_cost` value are considered to cost 0. If the cost was
removed on the `docker_volume` above, the template would consume 0 credits when
it's offline. This technique is good for incentivizing users to shut down their
unused workspaces and freeing up compute in the cluster.
@ -92,10 +93,10 @@ By default, groups are assumed to have a default allowance of 0.
## Quota Enforcement
Coder enforces Quota on workspace start and stop operations. The workspace
build process dynamically calculates costs, so quota violation fails builds
as opposed to failing the build-triggering operation. For example, the Workspace
Create Form will never get held up by quota enforcement.
Coder enforces Quota on workspace start and stop operations. The workspace build
process dynamically calculates costs, so quota violation fails builds as opposed
to failing the build-triggering operation. For example, the Workspace Create
Form will never get held up by quota enforcement.
![build-log](../images/admin/quota-buildlog.png)

10
docs/admin/rbac.md
View File

@ -1,10 +1,13 @@
# Role Based Access Control (RBAC)
Use RBAC to define which users and [groups](./groups.md) can use specific templates in Coder. These can be defined in Coder or [synced from your identity provider](./auth.md)
Use RBAC to define which users and [groups](./groups.md) can use specific
templates in Coder. These can be defined in Coder or
[synced from your identity provider](./auth.md)
![rbac](../images/template-rbac.png)
The "Everyone" group makes a template accessible to all users. This can be removed to make a template private.
The "Everyone" group makes a template accessible to all users. This can be
removed to make a template private.
## Permissions
@ -15,4 +18,5 @@ You can set the following permissions:
## Enabling this feature
This feature is only available with an enterprise license. [Learn more](../enterprise.md)
This feature is only available with an enterprise license.
[Learn more](../enterprise.md)

191
docs/admin/scale.md
View File

@ -1,14 +1,22 @@
We scale-test Coder with [a built-in utility](#scaletest-utility) that can be used in your environment for insights into how Coder scales with your infrastructure.
We scale-test Coder with [a built-in utility](#scaletest-utility) that can be
used in your environment for insights into how Coder scales with your
infrastructure.
## General concepts
Coder runs workspace operations in a queue. The number of concurrent builds will be limited to the number of provisioner daemons across all coderd replicas.
Coder runs workspace operations in a queue. The number of concurrent builds will
be limited to the number of provisioner daemons across all coderd replicas.
- **coderd**: Coder’s primary service. Learn more about [Coder’s architecture](../about/architecture.md)
- **coderd replicas**: Replicas (often via Kubernetes) for high availability, this is an [enterprise feature](../enterprise.md)
- **concurrent workspace builds**: Workspace operations (e.g. create/stop/delete/apply) across all users
- **concurrent connections**: Any connection to a workspace (e.g. SSH, web terminal, `coder_app`)
- **provisioner daemons**: Coder runs one workspace build per provisioner daemon. One coderd replica can host many daemons
- **coderd**: Coder’s primary service. Learn more about
[Coder’s architecture](../about/architecture.md)
- **coderd replicas**: Replicas (often via Kubernetes) for high availability,
this is an [enterprise feature](../enterprise.md)
- **concurrent workspace builds**: Workspace operations (e.g.
create/stop/delete/apply) across all users
- **concurrent connections**: Any connection to a workspace (e.g. SSH, web
terminal, `coder_app`)
- **provisioner daemons**: Coder runs one workspace build per provisioner
daemon. One coderd replica can host many daemons
- **scaletest**: Our scale-testing utility, built into the `coder` command line.
```text
@ -17,49 +25,86 @@ Coder runs workspace operations in a queue. The number of concurrent builds will
## Infrastructure recommendations
> Note: The below are guidelines for planning your infrastructure. Your mileage may vary depending on your templates, workflows, and users.
> Note: The below are guidelines for planning your infrastructure. Your mileage
> may vary depending on your templates, workflows, and users.
When planning your infrastructure, we recommend you consider the following:
1. CPU and memory requirements for `coderd`. We recommend allocating 1 CPU core and 2 GB RAM per `coderd` replica at minimum. See [Concurrent users](#concurrent-users) for more details.
1. CPU and memory requirements for [external provisioners](../admin/provisioners.md#running-external-provisioners), if required. We recommend allocating 1 CPU core and 1 GB RAM per 5 concurrent workspace builds to external provisioners. Note that this may vary depending on the template used. See [Concurrent workspace builds](#concurrent-workspace-builds) for more details. By default, `coderd` runs 3 integrated provisioners.
1. CPU and memory requirements for the database used by `coderd`. We recommend allocating an additional 1 CPU core to the database used by Coder for every 1000 active users.
1. CPU and memory requirements for workspaces created by Coder. This will vary depending on users' needs. However, the Coder agent itself requires at minimum 0.1 CPU cores and 256 MB to run inside a workspace.
1. CPU and memory requirements for `coderd`. We recommend allocating 1 CPU core
and 2 GB RAM per `coderd` replica at minimum. See
[Concurrent users](#concurrent-users) for more details.
1. CPU and memory requirements for
[external provisioners](../admin/provisioners.md#running-external-provisioners),
if required. We recommend allocating 1 CPU core and 1 GB RAM per 5 concurrent
workspace builds to external provisioners. Note that this may vary depending
on the template used. See
[Concurrent workspace builds](#concurrent-workspace-builds) for more details.
By default, `coderd` runs 3 integrated provisioners.
1. CPU and memory requirements for the database used by `coderd`. We recommend
allocating an additional 1 CPU core to the database used by Coder for every
1000 active users.
1. CPU and memory requirements for workspaces created by Coder. This will vary
depending on users' needs. However, the Coder agent itself requires at
minimum 0.1 CPU cores and 256 MB to run inside a workspace.
### Concurrent users
We recommend allocating 2 CPU cores and 4 GB RAM per `coderd` replica per 1000 active users.
We also recommend allocating an additional 1 CPU core to the database used by Coder for every 1000 active users.
Inactive users do not consume Coder resources, although workspaces configured to auto-start will consume resources when they are built.
We recommend allocating 2 CPU cores and 4 GB RAM per `coderd` replica per 1000
active users. We also recommend allocating an additional 1 CPU core to the
database used by Coder for every 1000 active users. Inactive users do not
consume Coder resources, although workspaces configured to auto-start will
consume resources when they are built.
Users' primary mode of accessing Coder will also affect resource requirements.
If users will be accessing workspaces primarily via Coder's HTTP interface, we recommend doubling the number of cores and RAM allocated per user.
For example, if you expect 1000 users accessing workspaces via the web, we recommend allocating 4 CPU cores and 8 GB RAM.
If users will be accessing workspaces primarily via Coder's HTTP interface, we
recommend doubling the number of cores and RAM allocated per user. For example,
if you expect 1000 users accessing workspaces via the web, we recommend
allocating 4 CPU cores and 8 GB RAM.
Users accessing workspaces via SSH will consume fewer resources, as SSH connections are not proxied through Coder.
Users accessing workspaces via SSH will consume fewer resources, as SSH
connections are not proxied through Coder.
### Concurrent workspace builds
Workspace builds are CPU-intensive, as it relies on Terraform. Various [Terraform providers](https://registry.terraform.io/browse/providers) have different resource requirements.
When tested with our [kubernetes](https://github.com/coder/coder/tree/main/examples/templates/kubernetes) template, `coderd` will consume roughly 0.25 cores per concurrent workspace build.
For effective provisioning, our helm chart prefers to schedule [one coderd replica per-node](https://github.com/coder/coder/blob/main/helm/coder/values.yaml#L188-L202).
Workspace builds are CPU-intensive, as it relies on Terraform. Various
[Terraform providers](https://registry.terraform.io/browse/providers) have
different resource requirements. When tested with our
[kubernetes](https://github.com/coder/coder/tree/main/examples/templates/kubernetes)
template, `coderd` will consume roughly 0.25 cores per concurrent workspace
build. For effective provisioning, our helm chart prefers to schedule
[one coderd replica per-node](https://github.com/coder/coder/blob/main/helm/coder/values.yaml#L188-L202).
We recommend:
- Running `coderd` on a dedicated set of nodes. This will prevent other workloads from interfering with workspace builds. You can use [node selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector), or [taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) to achieve this.
- Disabling autoscaling for `coderd` nodes. Autoscaling can cause interruptions for users, see [Autoscaling](#autoscaling) for more details.
- (Enterprise-only) Running external provisioners instead of Coder's built-in provisioners (`CODER_PROVISIONER_DAEMONS=0`) will separate the load caused by workspace provisioning on the `coderd` nodes. For more details, see [External provisioners](../admin/provisioners.md#running-external-provisioners).
- Alternatively, if increasing the number of integrated provisioner daemons in `coderd` (`CODER_PROVISIONER_DAEMONS>3`), allocate additional resources to `coderd` to compensate (approx. 0.25 cores and 256 MB per provisioner daemon).
- Running `coderd` on a dedicated set of nodes. This will prevent other
workloads from interfering with workspace builds. You can use
[node selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector),
or
[taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)
to achieve this.
- Disabling autoscaling for `coderd` nodes. Autoscaling can cause interruptions
for users, see [Autoscaling](#autoscaling) for more details.
- (Enterprise-only) Running external provisioners instead of Coder's built-in
provisioners (`CODER_PROVISIONER_DAEMONS=0`) will separate the load caused by
workspace provisioning on the `coderd` nodes. For more details, see
[External provisioners](../admin/provisioners.md#running-external-provisioners).
- Alternatively, if increasing the number of integrated provisioner daemons in
`coderd` (`CODER_PROVISIONER_DAEMONS>3`), allocate additional resources to
`coderd` to compensate (approx. 0.25 cores and 256 MB per provisioner daemon).
For example, to support 120 concurrent workspace builds:
- Create a cluster/nodepool with 4 nodes, 8-core each (AWS: `t3.2xlarge` GCP: `e2-highcpu-8`)
- Run coderd with 4 replicas, 30 provisioner daemons each. (`CODER_PROVISIONER_DAEMONS=30`)
- Ensure Coder's [PostgreSQL server](./configure.md#postgresql-database) can use up to 2 cores and 4 GB RAM
- Create a cluster/nodepool with 4 nodes, 8-core each (AWS: `t3.2xlarge` GCP:
`e2-highcpu-8`)
- Run coderd with 4 replicas, 30 provisioner daemons each.
(`CODER_PROVISIONER_DAEMONS=30`)
- Ensure Coder's [PostgreSQL server](./configure.md#postgresql-database) can use
up to 2 cores and 4 GB RAM
## Recent scale tests
> Note: the below information is for reference purposes only, and are not intended to be used as guidelines for infrastructure sizing.
> Note: the below information is for reference purposes only, and are not
> intended to be used as guidelines for infrastructure sizing.
| Environment | Coder CPU | Coder RAM | Database | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested |
| ---------------- | --------- | --------- | ---------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |
@ -69,17 +114,22 @@ For example, to support 120 concurrent workspace builds:
## Scale testing utility
Since Coder's performance is highly dependent on the templates and workflows you support, you may wish to use our internal scale testing utility against your own environments.
Since Coder's performance is highly dependent on the templates and workflows you
support, you may wish to use our internal scale testing utility against your own
environments.
> Note: This utility is intended for internal use only. It is not subject to any compatibility guarantees, and may cause interruptions for your users.
> To avoid potential outages and orphaned resources, we recommend running scale tests on a secondary "staging" environment.
> Run it against a production environment at your own risk.
> Note: This utility is intended for internal use only. It is not subject to any
> compatibility guarantees, and may cause interruptions for your users. To avoid
> potential outages and orphaned resources, we recommend running scale tests on
> a secondary "staging" environment. Run it against a production environment at
> your own risk.
### Workspace Creation
The following command will run our scale test against your own Coder deployment. You can also specify a template name and any parameter values.
The following command will run our scale test against your own Coder deployment.
You can also specify a template name and any parameter values.
```sh
```shell
coder exp scaletest create-workspaces \
--count 1000 \
--template "kubernetes" \
@ -99,16 +149,20 @@ The test does the following:
1. close connections, attempt to delete all workspaces
1. return results (e.g. `998 succeeded, 2 failed to connect`)
Concurrency is configurable. `concurrency 0` means the scaletest test will attempt to create & connect to all workspaces immediately.
Concurrency is configurable. `concurrency 0` means the scaletest test will
attempt to create & connect to all workspaces immediately.
If you wish to leave the workspaces running for a period of time, you can specify `--no-cleanup` to skip the cleanup step.
You are responsible for deleting these resources later.
If you wish to leave the workspaces running for a period of time, you can
specify `--no-cleanup` to skip the cleanup step. You are responsible for
deleting these resources later.
### Traffic Generation
Given an existing set of workspaces created previously with `create-workspaces`, the following command will generate traffic similar to that of Coder's web terminal against those workspaces.
Given an existing set of workspaces created previously with `create-workspaces`,
the following command will generate traffic similar to that of Coder's web
terminal against those workspaces.
```sh
```shell
coder exp scaletest workspace-traffic \
--byes-per-tick 128 \
--tick-interval 100ms \
@ -119,9 +173,10 @@ To generate SSH traffic, add the `--ssh` flag.
### Cleanup
The scaletest utility will attempt to clean up all workspaces it creates. If you wish to clean up all workspaces, you can run the following command:
The scaletest utility will attempt to clean up all workspaces it creates. If you
wish to clean up all workspaces, you can run the following command:
```sh
```shell
coder exp scaletest cleanup
```
@ -129,33 +184,45 @@ This will delete all workspaces and users with the prefix `scaletest-`.
## Autoscaling
We generally do not recommend using an autoscaler that modifies the number of coderd replicas. In particular, scale
down events can cause interruptions for a large number of users.
We generally do not recommend using an autoscaler that modifies the number of
coderd replicas. In particular, scale down events can cause interruptions for a
large number of users.
Coderd is different from a simple request-response HTTP service in that it services long-lived connections whenever it
proxies HTTP applications like IDEs or terminals that rely on websockets, or when it relays tunneled connections to
workspaces. Loss of a coderd replica will drop these long-lived connections and interrupt users. For example, if you
have 4 coderd replicas behind a load balancer, and an autoscaler decides to reduce it to 3, roughly 25% of the
connections will drop. An even larger proportion of users could be affected if they use applications that use more
than one websocket.
Coderd is different from a simple request-response HTTP service in that it
services long-lived connections whenever it proxies HTTP applications like IDEs
or terminals that rely on websockets, or when it relays tunneled connections to
workspaces. Loss of a coderd replica will drop these long-lived connections and
interrupt users. For example, if you have 4 coderd replicas behind a load
balancer, and an autoscaler decides to reduce it to 3, roughly 25% of the
connections will drop. An even larger proportion of users could be affected if
they use applications that use more than one websocket.
The severity of the interruption varies by application. Coder's web terminal, for example, will reconnect to the same
session and continue. So, this should not be interpreted as saying coderd replicas should never be taken down for any
The severity of the interruption varies by application. Coder's web terminal,
for example, will reconnect to the same session and continue. So, this should
not be interpreted as saying coderd replicas should never be taken down for any
reason.
We recommend you plan to run enough coderd replicas to comfortably meet your weekly high-water-mark load, and monitor
coderd peak CPU & memory utilization over the long term, reevaluating periodically. When scaling down (or performing
upgrades), schedule these outside normal working hours to minimize user interruptions.
We recommend you plan to run enough coderd replicas to comfortably meet your
weekly high-water-mark load, and monitor coderd peak CPU & memory utilization
over the long term, reevaluating periodically. When scaling down (or performing
upgrades), schedule these outside normal working hours to minimize user
interruptions.
### A note for Kubernetes users
When running on Kubernetes on cloud infrastructure (i.e. not bare metal), many operators choose to employ a _cluster_
autoscaler that adds and removes Kubernetes _nodes_ according to load. Coder can coexist with such cluster autoscalers,
but we recommend you take steps to prevent the autoscaler from evicting coderd pods, as an eviction will cause the same
interruptions as described above. For example, if you are using the [Kubernetes cluster
autoscaler](https://kubernetes.io/docs/reference/labels-annotations-taints/#cluster-autoscaler-kubernetes-io-safe-to-evict),
you may wish to set `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"` as an annotation on the coderd deployment.
When running on Kubernetes on cloud infrastructure (i.e. not bare metal), many
operators choose to employ a _cluster_ autoscaler that adds and removes
Kubernetes _nodes_ according to load. Coder can coexist with such cluster
autoscalers, but we recommend you take steps to prevent the autoscaler from
evicting coderd pods, as an eviction will cause the same interruptions as
described above. For example, if you are using the
[Kubernetes cluster autoscaler](https://kubernetes.io/docs/reference/labels-annotations-taints/#cluster-autoscaler-kubernetes-io-safe-to-evict),
you may wish to set `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"` as
an annotation on the coderd deployment.
## Troubleshooting
If a load test fails or if you are experiencing performance issues during day-to-day use, you can leverage Coder's [prometheus metrics](./prometheus.md) to identify bottlenecks during scale tests. Additionally, you can use your existing cloud monitoring stack to measure load, view server logs, etc.
If a load test fails or if you are experiencing performance issues during
day-to-day use, you can leverage Coder's [prometheus metrics](./prometheus.md)
to identify bottlenecks during scale tests. Additionally, you can use your
existing cloud monitoring stack to measure load, view server logs, etc.

27
docs/admin/telemetry.md
View File

@ -1,25 +1,38 @@
# Telemetry
Coder collects telemetry data from all free installations. Our users have the right to know what we collect, why we collect it, and how we use the data.
Coder collects telemetry data from all free installations. Our users have the
right to know what we collect, why we collect it, and how we use the data.
## What we collect
First of all, we do not collect any information that could threaten the security of your installation. For example, we do not collect parameters, environment variables, or passwords.
First of all, we do not collect any information that could threaten the security
of your installation. For example, we do not collect parameters, environment
variables, or passwords.
You can find a full list of the data we collect in the source code [here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
You can find a full list of the data we collect in the source code
[here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
Telemetry can be configured with the `CODER_TELEMETRY=x` environment variable.
For example, telemetry can be disabled with `CODER_TELEMETRY=false`.
`CODER_TELEMETRY=true` is our default level. It includes user email and IP addresses. This information is used in aggregate to understand where our users are and general demographic information. We may reach out to the deployment admin, but will never use these emails for outbound marketing.
`CODER_TELEMETRY=true` is our default level. It includes user email and IP
addresses. This information is used in aggregate to understand where our users
are and general demographic information. We may reach out to the deployment
admin, but will never use these emails for outbound marketing.
`CODER_TELEMETRY=false` disables telemetry altogether.
## How we use telemetry
We use telemetry to build product better and faster. Without telemetry, we don't know which features are most useful, we don't know where users are dropping off in our funnel, and we don't know if our roadmap is aligned with the demographics that really use Coder.
We use telemetry to build product better and faster. Without telemetry, we don't
know which features are most useful, we don't know where users are dropping off
in our funnel, and we don't know if our roadmap is aligned with the demographics
that really use Coder.
Typical SaaS companies collect far more than what we do with little transparency and configurability. It's hard to imagine our favorite products today existing without their backers having good intelligence.
Typical SaaS companies collect far more than what we do with little transparency
and configurability. It's hard to imagine our favorite products today existing
without their backers having good intelligence.
We've decided the only way we can make our product open-source _and_ build at a fast pace is by collecting usage data as well.
We've decided the only way we can make our product open-source _and_ build at a
fast pace is by collecting usage data as well.

25
docs/admin/upgrade.md
View File

@ -14,18 +14,18 @@ of [install](../install).
## Via install.sh
If you installed Coder using the `install.sh` script, re-run the below
command on the host:
If you installed Coder using the `install.sh` script, re-run the below command
on the host:
```console
```shell
curl -L https://coder.com/install.sh | sh
```
The script will unpack the new `coder` binary version over the one currently installed.
Next, you can restart Coder with the following commands (if running it as a system
service):
The script will unpack the new `coder` binary version over the one currently
installed. Next, you can restart Coder with the following commands (if running
it as a system service):
```console
```shell
systemctl daemon-reload
systemctl restart coder
```
@ -35,19 +35,22 @@ systemctl restart coder
If you installed using `docker-compose`, run the below command to upgrade the
Coder container:
```console
```shell
docker-compose pull coder && docker-compose up coder -d
```
## Via Kubernetes
See [Upgrading Coder via Helm](../install/kubernetes.md#upgrading-coder-via-helm).
See
[Upgrading Coder via Helm](../install/kubernetes.md#upgrading-coder-via-helm).
## Via Windows
Download the latest Windows installer or binary from [GitHub releases](https://github.com/coder/coder/releases/latest), or upgrade from Winget.
Download the latest Windows installer or binary from
[GitHub releases](https://github.com/coder/coder/releases/latest), or upgrade
from Winget.
```sh
```pwsh
winget install Coder.Coder
```

83
docs/admin/users.md
View File

@ -1,6 +1,7 @@
# Users
This article walks you through the user roles available in Coder and creating and managing users.
This article walks you through the user roles available in Coder and creating
and managing users.
## Roles
@ -17,36 +18,54 @@ Coder offers these user roles in the community edition:
| Execute and use **ALL** Workspaces | | | | ✅ |
| View all user operation [Audit Logs](./audit-logs.md) | ✅ | | | ✅ |
A user may have one or more roles. All users have an implicit Member role
that may use personal workspaces.
A user may have one or more roles. All users have an implicit Member role that
may use personal workspaces.
## Security notes
A malicious Template Admin could write a template that executes commands on the host (or `coder server` container), which potentially escalates their privileges or shuts down the Coder server. To avoid this, run [external provisioners](./provisioners.md).
A malicious Template Admin could write a template that executes commands on the
host (or `coder server` container), which potentially escalates their privileges
or shuts down the Coder server. To avoid this, run
[external provisioners](./provisioners.md).
In low-trust environments, we do not recommend giving users direct access to edit templates. Instead, use [CI/CD pipelines to update templates](../templates/change-management.md) with proper security scans and code reviews in place.
In low-trust environments, we do not recommend giving users direct access to
edit templates. Instead, use
[CI/CD pipelines to update templates](../templates/change-management.md) with
proper security scans and code reviews in place.
## User status
Coder user accounts can have different status types: active, dormant, and suspended.
Coder user accounts can have different status types: active, dormant, and
suspended.
### Active user
An _active_ user account in Coder is the default and desired state for all users. When a user's account is marked as _active_, they have complete access to the Coder platform
and can utilize all of its features and functionalities without any limitations. Active users can access workspaces, templates, and interact with Coder using CLI.
An _active_ user account in Coder is the default and desired state for all
users. When a user's account is marked as _active_, they have complete access to
the Coder platform and can utilize all of its features and functionalities
without any limitations. Active users can access workspaces, templates, and
interact with Coder using CLI.
### Dormant user
A user account is set to _dormant_ status when they have not yet logged in, or have not logged into the Coder platform for the past 90 days. Once the user logs in to the platform, the account status will switch to _active_.
A user account is set to _dormant_ status when they have not yet logged in, or
have not logged into the Coder platform for the past 90 days. Once the user logs
in to the platform, the account status will switch to _active_.
Dormant accounts do not count towards the total number of licensed seats in a Coder subscription, allowing organizations to optimize their license usage.
Dormant accounts do not count towards the total number of licensed seats in a
Coder subscription, allowing organizations to optimize their license usage.
### Suspended user
When a user's account is marked as _suspended_ in Coder, it means that the account has been temporarily deactivated, and the user is unable to access the platform.
When a user's account is marked as _suspended_ in Coder, it means that the
account has been temporarily deactivated, and the user is unable to access the
platform.
Only user administrators or owners have the necessary permissions to manage suspended accounts and decide whether to lift the suspension and allow the user back into the Coder environment.
This level of control ensures that administrators can enforce security measures and handle any compliance-related issues promptly.
Only user administrators or owners have the necessary permissions to manage
suspended accounts and decide whether to lift the suspension and allow the user
back into the Coder environment. This level of control ensures that
administrators can enforce security measures and handle any compliance-related
issues promptly.
## Create a user
@ -64,7 +83,7 @@ The new user will appear in the **Users** list. Use the toggle to change their
To create a user via the Coder CLI, run:
```console
```shell
coder users create
```
@ -98,7 +117,7 @@ To suspend a user via the web UI:
To suspend a user via the CLI, run:
```console
```shell
coder users suspend <username|user_id>
```
@ -117,7 +136,7 @@ To activate a user via the web UI:
To activate a user via the CLI, run:
```console
```shell
coder users activate <username|user_id>
```
@ -128,25 +147,27 @@ Confirm the user activation by typing **yes** and pressing **enter**.
To reset a user's via the web UI:
1. Go to **Users**.
2. Find the user whose password you want to reset, click the vertical ellipsis to the right,
and select **Reset password**.
2. Find the user whose password you want to reset, click the vertical ellipsis
to the right, and select **Reset password**.
3. Coder displays a temporary password that you can send to the user; copy the
password and click **Reset password**.
Coder will prompt the user to change their temporary password immediately after logging in.
Coder will prompt the user to change their temporary password immediately after
logging in.
You can also reset a password via the CLI:
```console
```shell
# run `coder reset-password <username> --help` for usage instructions
coder reset-password <username>
```
> Resetting a user's password, e.g., the initial `owner` role-based user, only works when run on the host running the Coder control plane.
> Resetting a user's password, e.g., the initial `owner` role-based user, only
> works when run on the host running the Coder control plane.
### Resetting a password on Kubernetes
```sh
```shell
kubectl exec -it deployment/coder /bin/bash -n coder
coder reset-password <username>
@ -154,14 +175,22 @@ coder reset-password <username>
## User filtering
In the Coder UI, you can filter your users using pre-defined filters or by utilizing the Coder's filter query. The examples provided below demonstrate how to use the Coder's filter query:
In the Coder UI, you can filter your users using pre-defined filters or by
utilizing the Coder's filter query. The examples provided below demonstrate how
to use the Coder's filter query:
- To find active users, use the filter `status:active`.
- To find admin users, use the filter `role:admin`.
- To find users have not been active since July 2023: `status:active last_seen_before:"2023-07-01T00:00:00Z"`
- To find users have not been active since July 2023:
`status:active last_seen_before:"2023-07-01T00:00:00Z"`
The following filters are supported:
- `status` - Indicates the status of the user. It can be either `active`, `dormant` or `suspended`.
- `role` - Represents the role of the user. You can refer to the [TemplateRole documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#TemplateRole) for a list of supported user roles.
- `last_seen_before` and `last_seen_after` - The last time a used has used the platform (e.g. logging in, any API requests, connecting to workspaces). Uses the RFC3339Nano format.
- `status` - Indicates the status of the user. It can be either `active`,
`dormant` or `suspended`.
- `role` - Represents the role of the user. You can refer to the
[TemplateRole documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#TemplateRole)
for a list of supported user roles.
- `last_seen_before` and `last_seen_after` - The last time a used has used the
platform (e.g. logging in, any API requests, connecting to workspaces). Uses
the RFC3339Nano format.

67
docs/admin/workspace-proxies.md
View File

@ -1,28 +1,47 @@
# Workspace Proxies
> Workspace proxies are in an [experimental state](../contributing/feature-stages.md#experimental-features) and the behavior is subject to change. Use [GitHub issues](https://github.com/coder/coder) to leave feedback. This experiment must be specifically enabled with the `--experiments="moons"` option on both coderd and the workspace proxy. If you have all experiements enabled, you have to add moons as well. `--experiments="*,moons"`
> Workspace proxies are in an
> [experimental state](../contributing/feature-stages.md#experimental-features)
> and the behavior is subject to change. Use
> [GitHub issues](https://github.com/coder/coder) to leave feedback. This
> experiment must be specifically enabled with the `--experiments="moons"`
> option on both coderd and the workspace proxy. If you have all experiements
> enabled, you have to add moons as well. `--experiments="*,moons"`
Workspace proxies provide low-latency experiences for geo-distributed teams.
Coder's networking does a best effort to make direct connections to a workspace. In situations where this is not possible, such as connections via the web terminal and [web IDEs](../ides/web-ides.md), workspace proxies are able to reduce the amount of distance the network traffic needs to travel.
Coder's networking does a best effort to make direct connections to a workspace.
In situations where this is not possible, such as connections via the web
terminal and [web IDEs](../ides/web-ides.md), workspace proxies are able to
reduce the amount of distance the network traffic needs to travel.
A workspace proxy is a relay connection a developer can choose to use when connecting with their workspace over SSH, a workspace app, port forwarding, etc. Dashboard connections and API calls (e.g. the workspaces list) are not served over workspace proxies.
A workspace proxy is a relay connection a developer can choose to use when
connecting with their workspace over SSH, a workspace app, port forwarding, etc.
Dashboard connections and API calls (e.g. the workspaces list) are not served
over workspace proxies.
![ProxyDiagram](../images/workspaceproxy/proxydiagram.png)
# Deploy a workspace proxy
Each workspace proxy should be a unique instance. At no point should 2 workspace proxy instances share the same authentication token. They only require port 443 to be open and are expected to have network connectivity to the coderd dashboard. Workspace proxies **do not** make any database connections.
Each workspace proxy should be a unique instance. At no point should 2 workspace
proxy instances share the same authentication token. They only require port 443
to be open and are expected to have network connectivity to the coderd
dashboard. Workspace proxies **do not** make any database connections.
Workspace proxies can be used in the browser by navigating to the user `Account -> Workspace Proxy`
Workspace proxies can be used in the browser by navigating to the user
`Account -> Workspace Proxy`
## Requirements
- The [Coder CLI](../cli.md) must be installed and authenticated as a user with the Owner role.
- The [Coder CLI](../cli.md) must be installed and authenticated as a user with
the Owner role.
## Step 1: Create the proxy
Create the workspace proxy and make sure to save the returned authentication token for said proxy. This is the token the workspace proxy will use to authenticate back to primary coderd.
Create the workspace proxy and make sure to save the returned authentication
token for said proxy. This is the token the workspace proxy will use to
authenticate back to primary coderd.
```bash
$ coder wsproxy create --name=newyork --display-name="USA East" --icon="/emojis/2194.png"
@ -40,7 +59,9 @@ newyork unregistered
## Step 2: Deploy the proxy
Deploying the workspace proxy will also register the proxy with coderd and make the workspace proxy usable. If the proxy deployment is successful, `coder wsproxy ls` will show an `ok` status code:
Deploying the workspace proxy will also register the proxy with coderd and make
the workspace proxy usable. If the proxy deployment is successful,
`coder wsproxy ls` will show an `ok` status code:
```
$ coder wsproxy ls
@ -53,13 +74,18 @@ sydney https://sydney.example.com ok
Other Status codes:
- `unregistered` : The workspace proxy was created, and not yet deployed
- `unreachable` : The workspace proxy was registered, but is not responding. Likely the proxy went offline.
- `unhealthy` : The workspace proxy is reachable, but has some issue that is preventing the proxy from being used. `coder wsproxy ls` should show the error message.
- `unreachable` : The workspace proxy was registered, but is not responding.
Likely the proxy went offline.
- `unhealthy` : The workspace proxy is reachable, but has some issue that is
preventing the proxy from being used. `coder wsproxy ls` should show the error
message.
- `ok` : The workspace proxy is healthy and working properly!
### Configuration
Workspace proxy configuration overlaps with a subset of the coderd configuration. To see the full list of configuration options: `coder wsproxy server --help`
Workspace proxy configuration overlaps with a subset of the coderd
configuration. To see the full list of configuration options:
`coder wsproxy server --help`
```bash
# Proxy specific configuration. These are REQUIRED
@ -87,7 +113,8 @@ CODER_TLS_KEY_FILE="<key_file_location>"
Make a `values-wsproxy.yaml` with the workspace proxy configuration:
> Notice the `workspaceProxy` configuration which is `false` by default in the coder Helm chart.
> Notice the `workspaceProxy` configuration which is `false` by default in the
> coder Helm chart.
```yaml
coder:
@ -121,7 +148,9 @@ Using Helm, install the workspace proxy chart
helm install coder coder-v2/coder --namespace <your workspace proxy namespace> -f ./values-wsproxy.yaml
```
Test that the workspace proxy is reachable with `curl -vvv`. If for some reason, the Coder dashboard still shows the workspace proxy is `UNHEALTHY`, scale down and up the deployment's replicas.
Test that the workspace proxy is reachable with `curl -vvv`. If for some reason,
the Coder dashboard still shows the workspace proxy is `UNHEALTHY`, scale down
and up the deployment's replicas.
### Running on a VM
@ -132,11 +161,14 @@ coder wsproxy server
### Running in Docker
Modify the default entrypoint to run a workspace proxy server instead of a regular Coder server.
Modify the default entrypoint to run a workspace proxy server instead of a
regular Coder server.
#### Docker Compose
Change the provided [`docker-compose.yml`](https://github.com/coder/coder/blob/main/docker-compose.yaml) file to include a custom entrypoint:
Change the provided
[`docker-compose.yml`](https://github.com/coder/coder/blob/main/docker-compose.yaml)
file to include a custom entrypoint:
```diff
image: ghcr.io/coder/coder:${CODER_VERSION:-latest}
@ -158,6 +190,9 @@ ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
### Selecting a proxy
Users can select a workspace proxy at the top-right of the browser-based Coder dashboard. Workspace proxy preferences are cached by the web browser. If a proxy goes offline, the session will fall back to the primary proxy. This could take up to 60 seconds.
Users can select a workspace proxy at the top-right of the browser-based Coder
dashboard. Workspace proxy preferences are cached by the web browser. If a proxy
goes offline, the session will fall back to the primary proxy. This could take
up to 60 seconds.
![Workspace proxy picker](../images/admin/workspace-proxy-picker.png)