opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: copy edit the organizations doc and add link to best practices (#15888)

Browse Source 
[preview](https://coder.com/docs/@orgs-edit-202412/admin/users/organizations)

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
This commit is contained in:
Edward Angert
2024-12-17 10:44:21 +05:00
committed by GitHub
co-authored by EdwardAngert
parent e191d9650c
commit 468ffd9919
2 changed files with 37 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/users/organizations.md
+37 -32
View File
@@ -14,9 +14,14 @@ with multiple platform teams, all with unique resources:
![Organizations Example](../../images/admin/users/organizations/diagram.png)
For more information about how to use organizations, visit the
[organizations best practices](../../tutorials/best-practices/organizations.md)
guide.
## The default organization
All Coder deployments start with one organization called `Coder`.
All Coder deployments start with one organization called `Coder`. All new users
are added to this organization by default.
To edit the organization details, navigate to `Deployment -> Organizations` in
the top bar:
@@ -30,29 +35,29 @@ 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
groups, and workspaces. Each organization must have at least one dedicated
[provisioner](../provisioners.md) since the built-in provisioner only applies to
the default organization.
You can configure [organization/role/group sync](./idp-sync.md) from your
identity provider to avoid manually assigning users to organizations.
## Creating an organization
## How to create an organization
### Prerequisites
- Coder v2.16+ deployment with Premium license with Organizations enabled
- Coder v2.16+ deployment with Premium license and 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
In the sidebar, select **New organization** to create an organization. In this
example, we'll create the `data-platform` org.
![New Organization](../../images/admin/users/organizations/new-organization.png)
From there, let's deploy a provisioner and template for this organization.
Next deploy a provisioner and template for this organization.
### 2. Deploy a provisioner
@@ -61,50 +66,50 @@ 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:
1. 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.
```shell
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 >
```
< 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](../provisioners.md).
1. Start the provisioner with the key on your desired platform.
```sh
export CODER_URL=https://<your-coder-url>
export CODER_PROVISIONER_DAEMON_KEY=<key>
coder provisionerd start --org <org-name>
```
In this example, start the provisioner using the Coder CLI on a host with
Docker. For instructions on using other platforms like Kubernetes, see our
[provisioner documentation](../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:
**Create Template** screen now has an organization dropdown:
![Template Org Picker](../../images/admin/users/organizations/template-org-picker.png)
### 5. Add members
### 4. Add members
Navigate to `Deployment->Organizations` to add members to your organization.
Once added, they will be able to see the organization-specific templates.
From **Administration > Settings**, select **Organizations** to add members to
your organization. Once added, they will be able to see the
organization-specific templates.
![Add members](../../images/admin/users/organizations/organization-members.png)
### 6. Create a workspace
### 5. Create a workspace
Now, users in the data platform organization will see the templates related to
their organization. Users can be in multiple organizations.
![Workspace List](../../images/admin/users/organizations/workspace-list.png)
## Beta
## Next steps
As of v2.16.0, 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.
- [Organizations - best practices](../../tutorials/best-practices/organizations.md)
docs/tutorials/using-organizations.md
-135
View File
@@ -1,135 +0,0 @@
# Using Organizations
> Note: Organizations is still under active development and requires a
> non-standard enterprise license to use. Do not use organizations on your
> production instance!
>
> For more details, [contact your account team](https://coder.com/contact).
Organizations allow you to run a Coder deployment with multiple platform teams,
all with uniquely scoped templates, provisioners, users, groups, and workspaces.
## Prerequisites
- Coder deployment with non-standard license with Organizations enabled
([contact your account team](https://coder.com/contact))
- User with `Owner` role
- Coder CLI installed on local machine
## Switch to the preview image and enable the experiment
To try the latest organizations features, switch to a preview image in your Helm
chart and enable the
[experimental flag](../reference/cli/server.md#--experiments).
For example, with Kubernetes, set the following in your `values.yaml`:
```yaml
coderd:
image:
repo: ghcr.io/coder/coder-preview
tag: orgs-preview-aug-16
env:
- name: CODER_EXPERIMENTS
value: multi-organization
```
> See all
> [preview images](https://github.com/coder/coder/pkgs/container/coder-preview)
> in GitHub. Preview images prefixed with `main-` expire after a week.
Then, upgrade your deployment:
```sh
helm upgrade coder coder-v2/coder -f values.yaml
```
## The default organization
All Coder deployments start with one organization called `Default`.
To edit the organization details, navigate to `Deployment -> Organizations` in
the top bar:
![Organizations Menu](../images/guides/using-organizations/deployment-organizations.png)
From there, you can manage the name, icon, description, users, and groups:
![Organization Settings](../images/guides/using-organizations/default-organization.png)
## Guide: Your first organization
### 1. Create the organization
Within the sidebar, click `New organization` to create an organization. In this
example, we'll create the `data-platform` org.
![New Organization](../images/guides/using-organizations/new-organization.png)
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:
![Template Org Picker](../images/guides/using-organizations/template-org-picker.png)
### 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.
![Add members](../images/guides/using-organizations/organization-members.png)
### 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.
![Workspace List](../images/guides/using-organizations/workspace-list.png)
## Planned work
Organizations is under active development. The work is planned before
organizations is generally available:
- View provisioner health via the Coder UI
- Custom Role support in Coder UI
- Per-organization quotas
- Improved visibility of organization-specific resources throughout the UI
- Sync OIDC claims to auto-assign users to organizations / roles + SCIM support
## Support & Feedback
[Contact your account team](https://coder.com/contact) if you have any questions
or feedback.