mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: add organizations, provisioners, and premium license docs (#14778)
- [x] Mention Orgs is beta and add a link to get feedback - [x] Add docs on new provisioner authentication architecture and deprecate the old one - [x] Add/update docs for IdP sync - [x] Organization Sync - [x] Group Sync - [x] Role Sync - [x] Modify `coder.com` codebase to add `Premium` and `Beta` pill, and allow multiple pills: https://github.com/coder/coder.com/pull/638 - [x] Replace all mentions of "Enterprise" with "Premium" in docs - [x] edit: change it to "Licensing" - [x] Remove the enterprise page and change all links to coder.com/pricing - [x] Merge #14786 - [x] Add redirects for coder.com to redirect the `using-organizations` guide to the new orgs one and /enterprise to /premium https://github.com/coder/coder.com/pull/645 - [x] Custom roles - [x] https://github.com/coder/coder/pull/14786 - [x] Remove all mentions of orgs experiment - [x] Update in-product copy & links to link to the new docs pages Anything I am missing? --- [Preview this](https://coder.com/docs/@orgs-licenses/admin/organizations) --------- Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com> Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Jaayden Halko <jaayden.halko@gmail.com>
This commit is contained in:
Ben Potter
co-authored by
Edward Angert
EdwardAngert
Jaayden Halko
Edward Angert
EdwardAngert
Jaayden Halko
parent
b786166ddf
commit
d04eaf8392
@@ -1,4 +1,4 @@
|
||||
# Appearance (enterprise)
|
||||
# Appearance (enterprise) (premium)
|
||||
|
||||
Customize the look of your Coder deployment to meet your enterprise
|
||||
requirements.
|
||||
@@ -93,7 +93,3 @@ For CLI, use,
|
||||
export CODER_SUPPORT_LINKS='[{"name": "Hello GitHub", "target": "https://github.com/coder/coder", "icon": "bug"}, {"name": "Hello Slack", "target": "https://codercom.slack.com/archives/C014JH42DBJ", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/slack.svg"}, {"name": "Hello Discord", "target": "https://discord.gg/coder", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/discord.svg"}, {"name": "Hello Foobar", "target": "https://discord.gg/coder", "icon": "/emojis/1f3e1.png"}]'
|
||||
coder-server
|
||||
```
|
||||
|
||||
## Up next
|
||||
|
||||
- [Enterprise](../enterprise.md)
|
||||
|
||||
@@ -122,5 +122,5 @@ entry:
|
||||
|
||||
## Enabling this feature
|
||||
|
||||
This feature is only available with an enterprise license.
|
||||
[Learn more](../enterprise.md)
|
||||
This feature is only available with a
|
||||
[Premium or Enterprise license](https://coder.com/pricing).
|
||||
|
||||
+290
-30
@@ -1,7 +1,5 @@
|
||||
# Authentication
|
||||
|
||||
.
|
||||
|
||||
By default, Coder is accessible via password authentication. Coder does not
|
||||
recommend using password authentication in production, and recommends using an
|
||||
authentication provider with properly configured multi-factor authentication
|
||||
@@ -227,7 +225,7 @@ your Coder deployment:
|
||||
CODER_DISABLE_PASSWORD_AUTH=true
|
||||
```
|
||||
|
||||
## SCIM (enterprise)
|
||||
## SCIM (enterprise) (premium)
|
||||
|
||||
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
|
||||
authentication. Upon deactivation, users are
|
||||
@@ -249,36 +247,50 @@ CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
|
||||
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
|
||||
```
|
||||
|
||||
## Group Sync (enterprise)
|
||||
## Group Sync (enterprise) (premium)
|
||||
|
||||
If your OpenID Connect provider supports group claims, you can configure Coder
|
||||
to synchronize groups in your auth provider to groups within Coder.
|
||||
to synchronize groups in your auth provider to groups within Coder. To enable
|
||||
group sync, ensure that the `groups` claim is being sent by your OpenID
|
||||
provider. You might need to request an additional
|
||||
[scope](../reference/cli/server.md#--oidc-scopes) or additional configuration on
|
||||
the OpenID provider side.
|
||||
|
||||
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.
|
||||
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 user login.
|
||||
|
||||
```env
|
||||
# as an environment variable
|
||||
CODER_OIDC_SCOPES=openid,profile,email,groups
|
||||
There are two ways you can configure group sync:
|
||||
|
||||
<div class="tabs">
|
||||
|
||||
## Server Flags
|
||||
|
||||
First, confirm that your OIDC provider is sending claims by logging in with OIDC
|
||||
and visiting the following URL with an `Owner` account:
|
||||
|
||||
```text
|
||||
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
|
||||
```
|
||||
|
||||
```shell
|
||||
# as a flag
|
||||
--oidc-scopes openid,profile,email,groups
|
||||
```
|
||||
You should see a field in either `id_token_claims`, `user_info_claims` or both
|
||||
followed by a list of the user's OIDC groups in the response. This is the
|
||||
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
|
||||
the OIDC provider. See
|
||||
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
|
||||
|
||||
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`.
|
||||
> Depending on the OIDC provider, this claim may be named differently. Common
|
||||
> ones include `groups`, `memberOf`, and `roles`.
|
||||
|
||||
```env
|
||||
Next configure the Coder server to read groups from the claim name with the
|
||||
[OIDC group field](../reference/cli/server.md#--oidc-group-field) server flag:
|
||||
|
||||
```sh
|
||||
# as an environment variable
|
||||
CODER_OIDC_GROUP_FIELD=groups
|
||||
```
|
||||
|
||||
```shell
|
||||
```sh
|
||||
# as a flag
|
||||
--oidc-group-field groups
|
||||
```
|
||||
@@ -288,14 +300,16 @@ names in Coder and removed from groups that the user no longer belongs to.
|
||||
|
||||
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.
|
||||
you can configure mapping between the two with the
|
||||
[OIDC group mapping](../reference/cli/server.md#--oidc-group-mapping) server
|
||||
flag.
|
||||
|
||||
```env
|
||||
```sh
|
||||
# as an environment variable
|
||||
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
|
||||
```
|
||||
|
||||
```shell
|
||||
```sh
|
||||
# as a flag
|
||||
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
|
||||
```
|
||||
@@ -313,11 +327,103 @@ coder:
|
||||
From the example above, users that belong to the `myOIDCGroupID` group in your
|
||||
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
|
||||
|
||||
## Runtime (Organizations)
|
||||
|
||||
> Note: You must have a Premium license with Organizations enabled to use this.
|
||||
> [Contact your account team](https://coder.com/contact) for more details
|
||||
|
||||
For deployments with multiple [organizations](./organizations.md), you must
|
||||
configure group sync at the organization level. In future Coder versions, you
|
||||
will be able to configure this in the UI. For now, you must use CLI commands.
|
||||
|
||||
First confirm you have the [Coder CLI](../install/index.md) installed and are
|
||||
logged in with a user who is an Owner or Organization Admin role. Next, confirm
|
||||
that your OIDC provider is sending a groups claim by logging in with OIDC and
|
||||
visiting the following URL:
|
||||
|
||||
```text
|
||||
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
|
||||
```
|
||||
|
||||
You should see a field in either `id_token_claims`, `user_info_claims` or both
|
||||
followed by a list of the user's OIDC groups in the response. This is the
|
||||
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
|
||||
the OIDC provider. See
|
||||
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
|
||||
|
||||
> Depending on the OIDC provider, this claim may be named differently. Common
|
||||
> ones include `groups`, `memberOf`, and `roles`.
|
||||
|
||||
To fetch the current group sync settings for an organization, run the following:
|
||||
|
||||
```sh
|
||||
coder organizations settings show group-sync \
|
||||
--org <org-name> \
|
||||
> group-sync.json
|
||||
```
|
||||
|
||||
The default for an organization looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"field": "",
|
||||
"mapping": null,
|
||||
"regex_filter": null,
|
||||
"auto_create_missing_groups": false
|
||||
}
|
||||
```
|
||||
|
||||
Below is an example that uses the `groups` claim and maps all groups prefixed by
|
||||
`coder-` into Coder:
|
||||
|
||||
```json
|
||||
{
|
||||
"field": "groups",
|
||||
"mapping": null,
|
||||
"regex_filter": "^coder-.*$",
|
||||
"auto_create_missing_groups": true
|
||||
}
|
||||
```
|
||||
|
||||
> Note: You much specify Coder group IDs instead of group names. The fastest way
|
||||
> to find the ID for a corresponding group is by visiting
|
||||
> `https://coder.example.com/api/v2/groups`.
|
||||
|
||||
Here is another example which maps `coder-admins` from the identity provider to
|
||||
2 groups in Coder and `coder-users` from the identity provider to another group:
|
||||
|
||||
```json
|
||||
{
|
||||
"field": "groups",
|
||||
"mapping": {
|
||||
"coder-admins": [
|
||||
"2ba2a4ff-ddfb-4493-b7cd-1aec2fa4c830",
|
||||
"93371154-150f-4b12-b5f0-261bb1326bb4"
|
||||
],
|
||||
"coder-users": ["2f4bde93-0179-4815-ba50-b757fb3d43dd"]
|
||||
},
|
||||
"regex_filter": null,
|
||||
"auto_create_missing_groups": false
|
||||
}
|
||||
```
|
||||
|
||||
To set these group sync settings, use the following command:
|
||||
|
||||
```sh
|
||||
coder organizations settings set group-sync \
|
||||
--org <org-name> \
|
||||
< group-sync.json
|
||||
```
|
||||
|
||||
Visit the Coder UI to confirm these changes:
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
### Group allowlist
|
||||
|
||||
You can limit which groups from your identity provider can log in to Coder with
|
||||
@@ -326,11 +432,36 @@ Users who are not in a matching group will see the following error:
|
||||
|
||||
|
||||
|
||||
## Role sync (enterprise)
|
||||
## Role sync (enterprise) (premium)
|
||||
|
||||
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 roles within Coder.
|
||||
|
||||
There are 2 ways to do role sync. Server Flags assign site wide roles, and
|
||||
runtime org role sync assigns organization roles
|
||||
|
||||
<div class="tabs">
|
||||
|
||||
## Server Flags
|
||||
|
||||
First, confirm that your OIDC provider is sending a roles claim by logging in
|
||||
with OIDC and visiting the following URL with an `Owner` account:
|
||||
|
||||
```text
|
||||
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
|
||||
```
|
||||
|
||||
You should see a field in either `id_token_claims`, `user_info_claims` or both
|
||||
followed by a list of the user's OIDC roles in the response. This is the
|
||||
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
|
||||
the OIDC provider. See
|
||||
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
|
||||
|
||||
> Depending on the OIDC provider, this claim may be named differently.
|
||||
|
||||
Next configure the Coder server to read groups from the claim name with the
|
||||
[OIDC role field](../reference/cli/server.md#--oidc-user-role-field) server
|
||||
flag:
|
||||
|
||||
Set the following in your Coder server [configuration](./configure.md).
|
||||
|
||||
@@ -346,7 +477,136 @@ 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.)
|
||||
|
||||
## Troubleshooting group/role sync
|
||||
## Runtime (Organizations)
|
||||
|
||||
> Note: You must have a Premium license with Organizations enabled to use this.
|
||||
> [Contact your account team](https://coder.com/contact) for more details
|
||||
|
||||
For deployments with multiple [organizations](./organizations.md), you can
|
||||
configure role sync at the organization level. In future Coder versions, you
|
||||
will be able to configure this in the UI. For now, you must use CLI commands.
|
||||
|
||||
First, confirm that your OIDC provider is sending a roles claim by logging in
|
||||
with OIDC and visiting the following URL with an `Owner` account:
|
||||
|
||||
```text
|
||||
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
|
||||
```
|
||||
|
||||
You should see a field in either `id_token_claims`, `user_info_claims` or both
|
||||
followed by a list of the user's OIDC roles in the response. This is the
|
||||
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
|
||||
the OIDC provider. See
|
||||
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
|
||||
|
||||
> Depending on the OIDC provider, this claim may be named differently.
|
||||
|
||||
To fetch the current group sync settings for an organization, run the following:
|
||||
|
||||
```sh
|
||||
coder organizations settings show role-sync \
|
||||
--org <org-name> \
|
||||
> role-sync.json
|
||||
```
|
||||
|
||||
The default for an organization looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"field": "",
|
||||
"mapping": null
|
||||
}
|
||||
```
|
||||
|
||||
Below is an example that uses the `roles` claim and maps `coder-admins` from the
|
||||
IDP as an `Organization Admin` and also maps to a custom `provisioner-admin`
|
||||
role.
|
||||
|
||||
```json
|
||||
{
|
||||
"field": "roles",
|
||||
"mapping": {
|
||||
"coder-admins": ["organization-admin"],
|
||||
"infra-admins": ["provisioner-admin"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Note: Be sure to use the `name` field for each role, not the display name. Use
|
||||
> `coder organization roles show --org=<your-org>` to see roles for your
|
||||
> organization.
|
||||
|
||||
To set these role sync settings, use the following command:
|
||||
|
||||
```sh
|
||||
coder organizations settings set role-sync \
|
||||
--org <org-name> \
|
||||
< role-sync.json
|
||||
```
|
||||
|
||||
Visit the Coder UI to confirm these changes:
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
## Organization Sync (Premium)
|
||||
|
||||
> Note: In a future Coder release, this can be managed via the Coder UI instead
|
||||
> of server flags.
|
||||
|
||||
If your OpenID Connect provider supports groups/role claims, you can configure
|
||||
Coder to synchronize claims in your auth provider to organizations within Coder.
|
||||
|
||||
First, confirm that your OIDC provider is sending clainms by logging in with
|
||||
OIDC and visiting the following URL with an `Owner` account:
|
||||
|
||||
```text
|
||||
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
|
||||
```
|
||||
|
||||
You should see a field in either `id_token_claims`, `user_info_claims` or both
|
||||
followed by a list of the user's OIDC groups in the response. This is the
|
||||
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
|
||||
the OIDC provider. See
|
||||
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
|
||||
|
||||
> Depending on the OIDC provider, this claim may be named differently. Common
|
||||
> ones include `groups`, `memberOf`, and `roles`.
|
||||
|
||||
Next configure the Coder server to read groups from the claim name with the
|
||||
[OIDC organization field](../reference/cli/server.md#--oidc-organization-field)
|
||||
server flag:
|
||||
|
||||
```sh
|
||||
# as an environment variable
|
||||
CODER_OIDC_ORGANIZATION_FIELD=groups
|
||||
```
|
||||
|
||||
Next, fetch the corresponding organization IDs using the following endpoint:
|
||||
|
||||
```text
|
||||
https://[coder.example.com]/api/v2/organizations
|
||||
```
|
||||
|
||||
Set the following in your Coder server [configuration](./configure.md).
|
||||
|
||||
```env
|
||||
CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
|
||||
```
|
||||
|
||||
> One claim value from your identity provider can be mapped to many
|
||||
> organizations in Coder (e.g. the example above maps to 2 organizations in
|
||||
> Coder.)
|
||||
|
||||
By default, all users are assigned to the default (first) organization. You can
|
||||
disable that with:
|
||||
|
||||
```env
|
||||
CODER_OIDC_ORGANIZATION_ASSIGN_DEFAULT=false
|
||||
```
|
||||
|
||||
## Troubleshooting group/role/organization sync
|
||||
|
||||
Some common issues when enabling group/role sync.
|
||||
|
||||
|
||||
@@ -195,10 +195,10 @@ Optionally, you can request custom scopes:
|
||||
CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
|
||||
```
|
||||
|
||||
### Multiple External Providers (enterprise)
|
||||
### Multiple External Providers (enterprise) (premium)
|
||||
|
||||
Multiple providers are an Enterprise feature. [Learn more](../enterprise.md).
|
||||
Below is an example configuration with multiple providers.
|
||||
Multiple providers are an [Enterprise feature](https://coder.com/pricing). Below
|
||||
is an example configuration with multiple providers.
|
||||
|
||||
```env
|
||||
# Provider 1) github.com
|
||||
|
||||
@@ -9,5 +9,5 @@ access to specific templates. They can be defined via the Coder web UI,
|
||||
|
||||
## Enabling this feature
|
||||
|
||||
This feature is only available with an enterprise license.
|
||||
[Learn more](../enterprise.md)
|
||||
This feature is only available with a
|
||||
[Premium or Enterprise license](https://coder.com/pricing).
|
||||
|
||||
@@ -73,4 +73,3 @@ Then, increase the number of pods.
|
||||
|
||||
- [Networking](../networking/index.md)
|
||||
- [Kubernetes](../install/kubernetes.md)
|
||||
- [Enterprise](../enterprise.md)
|
||||
|
||||
@@ -231,7 +231,7 @@ notification is indicated on the right hand side of this table.
|
||||
|
||||
|
||||
|
||||
## Delivery Preferences (enterprise)
|
||||
## Delivery Preferences (enterprise) (premium)
|
||||
|
||||
Administrators can configure which delivery methods are used for each different
|
||||
[event type](#event-types).
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
# Organizations (Premium)
|
||||
|
||||
> Note: Organizations requires a [Premium license](../licensing.md). For more
|
||||
> details, [contact your account team](https://coder.com/contact).
|
||||
|
||||
Organizations can be used to segment and isolate resources inside a Coder
|
||||
deployment for different user groups or projects.
|
||||
|
||||
## Example
|
||||
|
||||
Here is an example of how one could use organizations to run a Coder deployment
|
||||
with multiple platform teams, all with unique resources:
|
||||
|
||||
|
||||
|
||||
## The default organization
|
||||
|
||||
All Coder deployments start with one organization called `Coder`.
|
||||
|
||||
To edit the organization details, navigate to `Deployment -> Organizations` in
|
||||
the top bar:
|
||||
|
||||
|
||||
|
||||
From there, you can manage the name, icon, description, users, and groups:
|
||||
|
||||
|
||||
|
||||
## Additional organizations
|
||||
|
||||
Any additional organizations have unique admins, users, templates, provisioners,
|
||||
groups, and workspaces. Each organization must have at least one
|
||||
[provisioner](./provisioners.md) as the built-in provisioner only applies to the
|
||||
default organization.
|
||||
|
||||
You can configure [organization/role/group sync](./auth.md) from your identity
|
||||
provider to avoid manually assigning users to organizations.
|
||||
|
||||
## Creating an organization
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Coder v2.16+ deployment with Premium license with Organizations enabled
|
||||
([contact your account team](https://coder.com/contact)) for more details.
|
||||
- User with `Owner` role
|
||||
|
||||
### 1. Create the organization
|
||||
|
||||
Within the sidebar, click `New organization` to create an organization. In this
|
||||
example, we'll create the `data-platform` org.
|
||||
|
||||
|
||||
|
||||
From there, let's deploy a provisioner and template for this organization.
|
||||
|
||||
### 2. Deploy a provisioner
|
||||
|
||||
[Provisioners](../admin/provisioners.md) are organization-scoped and are
|
||||
responsible for executing Terraform/OpenTofu to provision the infrastructure for
|
||||
workspaces and testing templates. Before creating templates, we must deploy at
|
||||
least one provisioner as the built-in provisioners are scoped to the default
|
||||
organization.
|
||||
|
||||
Using Coder CLI, run the following command to create a key that will be used to
|
||||
authenticate the provisioner:
|
||||
|
||||
```sh
|
||||
coder provisioner keys create data-cluster-key --org data-platform
|
||||
Successfully created provisioner key data-cluster! Save this authentication token, it will not be shown again.
|
||||
|
||||
< key omitted >
|
||||
```
|
||||
|
||||
Next, start the provisioner with the key on your desired platform. In this
|
||||
example, we'll start it using the Coder CLI on a host with Docker. For
|
||||
instructions on using other platforms like Kubernetes, see our
|
||||
[provisioner documentation](../admin/provisioners.md).
|
||||
|
||||
```sh
|
||||
export CODER_URL=https://<your-coder-url>
|
||||
export CODER_PROVISIONER_DAEMON_KEY=<key>
|
||||
coder provisionerd start --org <org-name>
|
||||
```
|
||||
|
||||
### 3. Create a template
|
||||
|
||||
Once you've started a provisioner, you can create a template. You'll notice the
|
||||
"Create Template" screen now has an organization dropdown:
|
||||
|
||||
|
||||
|
||||
### 5. Add members
|
||||
|
||||
Navigate to `Deployment->Organizations` to add members to your organization.
|
||||
Once added, they will be able to see the organization-specific templates.
|
||||
|
||||
|
||||
|
||||
### 6. Create a workspace
|
||||
|
||||
Now, users in the data platform organization will see the templates related to
|
||||
their organization. Users can be in multiple organizations.
|
||||
|
||||
|
||||
|
||||
## Beta
|
||||
|
||||
Organizations is in beta. If you encounter any issues, please
|
||||
[file an issue](https://github.com/coder/coder/issues/new) or contact your
|
||||
account team.
|
||||
+151
-78
@@ -3,10 +3,10 @@
|
||||
By default, the Coder server runs
|
||||
[built-in provisioner daemons](../reference/cli/server.md#provisioner-daemons),
|
||||
which execute `terraform` during workspace and template builds. However, there
|
||||
are sometimes benefits to running external provisioner daemons:
|
||||
are often 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.
|
||||
preventing malicious templates from gaining sh 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
|
||||
@@ -20,82 +20,101 @@ are sometimes benefits to running external provisioner daemons:
|
||||
times from the Coder server. See
|
||||
[Scaling Coder](scaling/scale-utility.md#recent-scale-tests) for more details.
|
||||
|
||||
Each provisioner can run a single
|
||||
[concurrent workspace build](scaling/scale-testing.md#control-plane-provisionerd).
|
||||
Each provisioner runs a single
|
||||
[concurrent workspace build](scaling/scale-testing.md#control-plane-provisioner).
|
||||
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](../reference/cli/provisioner_start.md) command.
|
||||
[`coder provisioner start`](../reference/cli/provisioner_start.md) command in
|
||||
the [full Coder binary](https://github.com/coder/coder/releases). Keep reading
|
||||
to learn how to start provisioners via Docker, Kubernetes, Systemd, etc.
|
||||
|
||||
## Authentication
|
||||
|
||||
The provisioner daemon must authenticate with your Coder deployment.
|
||||
The provisioner daemon must authenticate with your Coder deployment. If you have
|
||||
multiple [organizations](./organizations.md), you'll need at least 1 provisioner
|
||||
running for each organization.
|
||||
|
||||
Set a
|
||||
<div class="tabs">
|
||||
|
||||
## Scoped Key (Recommended)
|
||||
|
||||
We recommend creating finely-scoped keys for provisioners. Keys are scoped to an
|
||||
organization.
|
||||
|
||||
```sh
|
||||
coder provisioner keys create my-key \
|
||||
--org default
|
||||
|
||||
Successfully created provisioner key my-key! Save this authentication token, it will not be shown again.
|
||||
|
||||
<key omitted>
|
||||
```
|
||||
|
||||
Or, restrict the provisioner to jobs with specific tags
|
||||
|
||||
```sh
|
||||
coder provisioner keys create kubernetes-key \
|
||||
--org default \
|
||||
--tag environment=kubernetes
|
||||
|
||||
Successfully created provisioner key kubernetes-key! Save this authentication token, it will not be shown again.
|
||||
|
||||
<key omitted>
|
||||
```
|
||||
|
||||
To start the provisioner:
|
||||
|
||||
```sh
|
||||
export CODER_URL=https://<your-coder-url>
|
||||
export CODER_PROVISIONER_DAEMON_KEY=<key>
|
||||
coder provisioner start
|
||||
```
|
||||
|
||||
Keep reading to see instructions for running provisioners on
|
||||
Kubernetes/Docker/etc.
|
||||
|
||||
## User Tokens
|
||||
|
||||
A user account with the role `Template Admin` or `Owner` can start provisioners
|
||||
using their user account. This may be beneficial if you are running provisioners
|
||||
via [automation](./automation.md).
|
||||
|
||||
```sh
|
||||
coder login https://<your-coder-url>
|
||||
coder provisioner start
|
||||
```
|
||||
|
||||
To start a provisioner with specific tags:
|
||||
|
||||
```sh
|
||||
coder login https://<your-coder-url>
|
||||
coder provisioner start \
|
||||
--tag environment=kubernetes
|
||||
```
|
||||
|
||||
Note: Any user can start [user-scoped provisioners](#User-scoped-Provisioners),
|
||||
but this will also require a template on your deployment with the corresponding
|
||||
tags.
|
||||
|
||||
## Global PSK
|
||||
|
||||
A deployment-wide PSK can be used to authenticate any provisioner. We do not
|
||||
recommend this approach anymore, as it makes key rotation or isolating
|
||||
provisioners far more difficult. To use a global PSK, set a
|
||||
[provisioner daemon pre-shared key (PSK)](../reference/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.
|
||||
on the Coder server.
|
||||
|
||||
> Coder still supports authenticating the provisioner daemon with a
|
||||
> [token](../reference/cli/README.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.
|
||||
Next, start the provisioner:
|
||||
|
||||
## Types of provisioners
|
||||
|
||||
Provisioners can broadly be categorized by scope: `organization` or `user`. The
|
||||
scope of a provisioner can be specified with
|
||||
[`-tag=scope=<scope>`](../reference/cli/provisioner_start.md#t---tag) when
|
||||
starting the provisioner daemon. Only users with at least the
|
||||
[Template Admin](../admin/users.md#roles) role or higher may create
|
||||
organization-scoped provisioner daemons.
|
||||
|
||||
There are two exceptions:
|
||||
|
||||
- [Built-in provisioners](../reference/cli/server.md#provisioner-daemons) are
|
||||
always organization-scoped.
|
||||
- External provisioners started using a
|
||||
[pre-shared key (PSK)](../reference/cli/provisioner_start.md#psk) are always
|
||||
organization-scoped.
|
||||
|
||||
### Organization-Scoped Provisioners
|
||||
|
||||
**Organization-scoped Provisioners** can pick up build jobs created by any user.
|
||||
These provisioners always have the implicit tags `scope=organization owner=""`.
|
||||
|
||||
```shell
|
||||
coder provisionerd start --org <organization_name>
|
||||
```sh
|
||||
coder provisioner start --psk <your-psk>
|
||||
```
|
||||
|
||||
If you omit the `--org` argument, the provisioner will be assigned to the
|
||||
default organization.
|
||||
</div>
|
||||
|
||||
```shell
|
||||
coder provisionerd start
|
||||
```
|
||||
|
||||
### User-scoped Provisioners
|
||||
|
||||
**User-scoped Provisioners** can only pick up build jobs created from
|
||||
user-tagged templates. Unlike the other provisioner types, any Coder user can
|
||||
run user provisioners, but they have no impact unless there exists at least one
|
||||
template with the `scope=user` provisioner tag.
|
||||
|
||||
```shell
|
||||
coder provisionerd start \
|
||||
--tag scope=user
|
||||
|
||||
# In another terminal, create/push
|
||||
# a template that requires user provisioners
|
||||
coder templates push on-prem \
|
||||
--provisioner-tag scope=user
|
||||
```
|
||||
|
||||
### Provisioner Tags
|
||||
## Provisioner Tags
|
||||
|
||||
You can use **provisioner tags** to control which provisioners can pick up build
|
||||
jobs from templates (and corresponding workspaces) with matching explicit tags.
|
||||
@@ -110,10 +129,10 @@ automatically.
|
||||
|
||||
For example:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
# Start a provisioner with the explicit tags
|
||||
# environment=on_prem and datacenter=chicago
|
||||
coder provisionerd start \
|
||||
coder provisioner start \
|
||||
--tag environment=on_prem \
|
||||
--tag datacenter=chicago
|
||||
|
||||
@@ -129,6 +148,10 @@ coder templates push on-prem-chicago \
|
||||
--provisioner-tag datacenter=chicago
|
||||
```
|
||||
|
||||
Alternatively, a template can target a provisioner via
|
||||
[workspace tags](https://github.com/coder/coder/tree/main/examples/workspace-tags)
|
||||
inside the Terraform.
|
||||
|
||||
A provisioner can run a given build job if one of the below is true:
|
||||
|
||||
1. A job with no explicit tags can only be run on a provisioner with no explicit
|
||||
@@ -176,9 +199,59 @@ This is illustrated in the below table:
|
||||
> copy the output:
|
||||
>
|
||||
> ```
|
||||
> go test -v -count=1 ./coderd/provisionerdserver/ -test.run='^TestAcquirer_MatchTags/GenTable$'
|
||||
> go test -v -count=1 ./coderd/provisionerserver/ -test.run='^TestAcquirer_MatchTags/GenTable$'
|
||||
> ```
|
||||
|
||||
## Types of provisioners
|
||||
|
||||
Provisioners can broadly be categorized by scope: `organization` or `user`. The
|
||||
scope of a provisioner can be specified with
|
||||
[`-tag=scope=<scope>`](../reference/cli/provisioner_start.md#t---tag) when
|
||||
starting the provisioner daemon. Only users with at least the
|
||||
[Template Admin](../admin/users.md#roles) role or higher may create
|
||||
organization-scoped provisioner daemons.
|
||||
|
||||
There are two exceptions:
|
||||
|
||||
- [Built-in provisioners](../reference/cli/server.md#provisioner-daemons) are
|
||||
always organization-scoped.
|
||||
- External provisioners started using a
|
||||
[pre-shared key (PSK)](../reference/cli/provisioner_start.md#psk) are always
|
||||
organization-scoped.
|
||||
|
||||
### Organization-Scoped Provisioners
|
||||
|
||||
**Organization-scoped Provisioners** can pick up build jobs created by any user.
|
||||
These provisioners always have the implicit tags `scope=organization owner=""`.
|
||||
|
||||
```sh
|
||||
coder provisioner start --org <organization_name>
|
||||
```
|
||||
|
||||
If you omit the `--org` argument, the provisioner will be assigned to the
|
||||
default organization.
|
||||
|
||||
```sh
|
||||
coder provisioner start
|
||||
```
|
||||
|
||||
### User-scoped Provisioners
|
||||
|
||||
**User-scoped Provisioners** can only pick up build jobs created from
|
||||
user-tagged templates. Unlike the other provisioner types, any Coder user can
|
||||
run user provisioners, but they have no impact unless there exists at least one
|
||||
template with the `scope=user` provisioner tag.
|
||||
|
||||
```sh
|
||||
coder provisioner start \
|
||||
--tag scope=user
|
||||
|
||||
# In another terminal, create/push
|
||||
# a template that requires user provisioners
|
||||
coder templates push on-prem \
|
||||
--provisioner-tag scope=user
|
||||
```
|
||||
|
||||
## Example: Running an external provisioner with Helm
|
||||
|
||||
Coder provides a Helm chart for running external provisioner daemons, which you
|
||||
@@ -187,21 +260,21 @@ 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
|
||||
|
||||
```shell
|
||||
```sh
|
||||
kubectl create secret generic coder-provisioner-psk --from-literal=psk=`head /dev/urandom | base64 | tr -dc A-Za-z0-9 | head -c 26`
|
||||
```
|
||||
|
||||
1. Modify your Coder `values.yaml` to include
|
||||
|
||||
```yaml
|
||||
provisionerDaemon:
|
||||
provisioneraemon:
|
||||
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.
|
||||
|
||||
```shell
|
||||
```sh
|
||||
helm upgrade coder coder-v2/coder \
|
||||
--namespace coder \
|
||||
--version <your version> \
|
||||
@@ -217,7 +290,7 @@ will use in concert with the Helm chart for deploying the Coder server.
|
||||
- name: CODER_URL
|
||||
value: "https://coder.example.com"
|
||||
replicaCount: 10
|
||||
provisionerDaemon:
|
||||
provisioneraemon:
|
||||
pskSecretName: "coder-provisioner-psk"
|
||||
tags:
|
||||
location: auh
|
||||
@@ -235,7 +308,7 @@ will use in concert with the Helm chart for deploying the Coder server.
|
||||
|
||||
1. Install the provisioner daemon chart
|
||||
|
||||
```shell
|
||||
```sh
|
||||
helm install coder-provisioner coder-v2/coder-provisioner \
|
||||
--namespace coder \
|
||||
--version <your version> \
|
||||
@@ -244,26 +317,26 @@ will use in concert with the Helm chart for deploying the Coder server.
|
||||
|
||||
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.
|
||||
`provisioner: successfully connected to coderd` from each Pod.
|
||||
|
||||
## Example: Running an external provisioner on a VM
|
||||
|
||||
```shell
|
||||
```sh
|
||||
curl -L https://coder.com/install.sh | sh
|
||||
export CODER_URL=https://coder.example.com
|
||||
export CODER_SESSION_TOKEN=your_token
|
||||
coder provisionerd start
|
||||
coder provisioner start
|
||||
```
|
||||
|
||||
## Example: Running an external provisioner via Docker
|
||||
|
||||
```shell
|
||||
```sh
|
||||
docker run --rm -it \
|
||||
-e CODER_URL=https://coder.example.com/ \
|
||||
-e CODER_SESSION_TOKEN=your_token \
|
||||
--entrypoint /opt/coder \
|
||||
ghcr.io/coder/coder:latest \
|
||||
provisionerd start
|
||||
provisioner start
|
||||
```
|
||||
|
||||
## Disable built-in provisioners
|
||||
@@ -272,7 +345,7 @@ 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](../reference/cli/server.md#provisioner-daemons).
|
||||
|
||||
```shell
|
||||
```sh
|
||||
coder server --provisioner-daemons=0
|
||||
```
|
||||
|
||||
|
||||
@@ -102,5 +102,4 @@ Form will never get held up by quota enforcement.
|
||||
|
||||
## Up next
|
||||
|
||||
- [Enterprise](../enterprise.md)
|
||||
- [Configuring](./configure.md)
|
||||
|
||||
+2
-2
@@ -19,5 +19,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 or Premium license](https://coder.com/pricing).
|
||||
|
||||
@@ -53,7 +53,3 @@ from Winget.
|
||||
```pwsh
|
||||
winget install Coder.Coder
|
||||
```
|
||||
|
||||
## Up Next
|
||||
|
||||
- [Learn how to enable Enterprise features](../enterprise.md).
|
||||
|
||||
+11
-1
@@ -10,7 +10,7 @@ Coder offers these user roles in the community edition:
|
||||
| | Auditor | User Admin | Template Admin | Owner |
|
||||
| ----------------------------------------------------- | ------- | ---------- | -------------- | ----- |
|
||||
| Add and remove Users | | ✅ | | ✅ |
|
||||
| Manage groups (enterprise) | | ✅ | | ✅ |
|
||||
| Manage groups (premium) | | ✅ | | ✅ |
|
||||
| Change User roles | | | | ✅ |
|
||||
| Manage **ALL** Templates | | | ✅ | ✅ |
|
||||
| View **ALL** Workspaces | | | ✅ | ✅ |
|
||||
@@ -22,6 +22,16 @@ Coder offers these user roles in the community edition:
|
||||
A user may have one or more roles. All users have an implicit Member role that
|
||||
may use personal workspaces.
|
||||
|
||||
## Custom Roles (Premium) (Beta)
|
||||
|
||||
Coder v2.16+ deployments can configure custom roles on the
|
||||
[Organization](./organizations.md) level.
|
||||
|
||||
|
||||
|
||||
> Note: This requires a Premium license.
|
||||
> [Contact your account team](https://coder.com/contact) for more details.
|
||||
|
||||
## Security notes
|
||||
|
||||
A malicious Template Admin could write a template that executes commands on the
|
||||
|
||||
Reference in New Issue
Block a user