|
| 1 | +#Using Organizations |
| 2 | + |
| 3 | +>Note: Organizations is still under active development and requires a |
| 4 | +>non-standard enterprise license to use. Do not use organizations on your |
| 5 | +>production instance! |
| 6 | +> |
| 7 | +>For more details,[contact your account team](https://coder.com/contact). |
| 8 | +
|
| 9 | +Organizations allow you to run a Coder deployment with multiple platform teams, |
| 10 | +all with uniquely scoped templates, provisioners, users, groups, and workspaces. |
| 11 | + |
| 12 | +##Prerequisites |
| 13 | + |
| 14 | +- Coder deployment with non-standard license with Organizations enabled |
| 15 | + ([contact your account team](https://coder.com/contact)) |
| 16 | +- User with`Owner` role |
| 17 | +- Coder CLI installed on local machine |
| 18 | + |
| 19 | +##Switch to the preview image and enable the experiment |
| 20 | + |
| 21 | +To try the latest organizations features, switch to a preview image in your Helm |
| 22 | +chart and enable the |
| 23 | +[experimental flag](../reference/cli/server.md#--experiments). |
| 24 | + |
| 25 | +For example, with Kubernetes, set the following in your`values.yaml`: |
| 26 | + |
| 27 | +```yaml |
| 28 | +coderd: |
| 29 | +image: |
| 30 | +repo:ghcr.io/coder/coder-preview |
| 31 | +tag:orgs-preview-aug-16 |
| 32 | +env: |
| 33 | + -name:CODER_EXPERIMENTS |
| 34 | +value:multi-organization |
| 35 | +``` |
| 36 | +
|
| 37 | +> See all |
| 38 | +> [preview images](https://github.com/coder/coder/pkgs/container/coder-preview) |
| 39 | +> in GitHub. Preview images prefixed with`main-` expire after a week. |
| 40 | + |
| 41 | +Then, upgrade your deployment: |
| 42 | + |
| 43 | +```sh |
| 44 | +helm upgrade coder coder-v2/coder -f values.yaml |
| 45 | +``` |
| 46 | + |
| 47 | +## The default organization |
| 48 | + |
| 49 | +All Coder deployments start with one organization called `Default`. |
| 50 | + |
| 51 | +To edit the organization details, navigate to `Deployment -> Organizations` in |
| 52 | +the top bar: |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | +From there, you can manage the name, icon, description, users, and groups: |
| 57 | + |
| 58 | + |
| 59 | + |
| 60 | +## Guide: Your first organization |
| 61 | + |
| 62 | +### 1. Create the organization |
| 63 | + |
| 64 | +Within the sidebar, click `New organization` to create an organization. In this |
| 65 | +example, we'll create the `data-platform` org. |
| 66 | + |
| 67 | + |
| 68 | + |
| 69 | +From there, let's deploy a provisioner and template for this organization. |
| 70 | + |
| 71 | +### 2. Deploy a provisioner |
| 72 | + |
| 73 | +[Provisioners](../admin/provisioners.md) are organization-scoped and are |
| 74 | +responsible for executing Terraform/OpenTofu to provision the infrastructure for |
| 75 | +workspaces and testing templates. Before creating templates, we must deploy at |
| 76 | +least one provisioner as the built-in provisioners are scoped to the default |
| 77 | +organization. |
| 78 | + |
| 79 | +using Coder CLI, run the following command to create a key that will be used to |
| 80 | +authenticate the provisioner: |
| 81 | + |
| 82 | +```sh |
| 83 | +coder provisioner keys create data-cluster-key --org data-platform |
| 84 | +Successfully created provisioner key data-cluster! Save this authentication token, it will not be shown again. |
| 85 | +
|
| 86 | +< key omitted > |
| 87 | +``` |
| 88 | + |
| 89 | +Next, start the provisioner with the key on your desired platform. In this |
| 90 | +example, we'll start it using the Coder CLI on a host with Docker. For |
| 91 | +instructions on using other platforms like Kubernetes, see our |
| 92 | +[provisioner documentation](../admin/provisioners.md). |
| 93 | + |
| 94 | +```sh |
| 95 | +export CODER_URL=https://<your-coder-url> |
| 96 | +export CODER_PROVISIONER_DAEMON_KEY=<key> |
| 97 | +coder provisionerd start --org <org-name> |
| 98 | +``` |
| 99 | + |
| 100 | +### 3. Create a template |
| 101 | + |
| 102 | +Once you've started a provisioner, you can create a template. You'll notice the |
| 103 | +"Create Template"screen now has an organization dropdown: |
| 104 | + |
| 105 | + |
| 106 | + |
| 107 | +### 5. Add members |
| 108 | + |
| 109 | +Navigate to `Deployment->Organizations` to add members to your organization. |
| 110 | +Once added, they will be able to see the organization-specific templates. |
| 111 | + |
| 112 | + |
| 113 | + |
| 114 | +### 6. Create a workspace |
| 115 | + |
| 116 | +Now, users in the data platform organization will see the templates related to |
| 117 | +their organization. Users can be in multiple organizations. |
| 118 | + |
| 119 | + |
| 120 | + |
| 121 | +## Planned work |
| 122 | + |
| 123 | +Organizations is under active development. The work is planned before |
| 124 | +organizations is generally available: |
| 125 | + |
| 126 | +-View provisioner health via the Coder UI |
| 127 | +-Custom Role support in Coder UI |
| 128 | +-Per-organization quotas |
| 129 | +-Improved visibility of organization-specific resources throughout the UI |
| 130 | +-Sync OIDC claims to auto-assign users to organizations / roles + SCIM support |
| 131 | + |
| 132 | +## Support & Feedback |
| 133 | + |
| 134 | +[Contact your account team](https://coder.com/contact) if you have any questions |
| 135 | +or feedback. |