coder · EdwardAngert · Dec 11, 2024 · Nov 27, 2024 · Dec 3, 2024 · Dec 9, 2024
diff --git a/.github/.linkspector.yml b/.github/.linkspector.yml
@@ -18,5 +18,6 @@ ignorePatterns:
   - pattern: "i.imgur.com"
   - pattern: "code.visualstudio.com"
   - pattern: "www.emacswiki.org"
+  - pattern: "linux.die.net/man"
 aliveStatusCodes:
   - 200
diff --git a/docs/images/best-practice/organizations-architecture.png b/docs/images/best-practice/organizations-architecture.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -739,6 +739,11 @@
 					"description": "Guides to help you make the most of your Coder experience",
 					"path": "./tutorials/best-practices/index.md",
 					"children": [
+						{
+							"title": "Organizations - best practices",
+							"description": "How to make the best use of Coder Organizations",
+							"path": "./tutorials/best-practices/organizations.md"
+						},
 						{
 							"title": "Speed up your workspaces",
 							"description": "Speed up your Coder templates and workspaces",

diff --git a/docs/tutorials/best-practices/organizations.md b/docs/tutorials/best-practices/organizations.md
@@ -0,0 +1,149 @@
+# Organizations - best practices
+
+December 9, 2024
+
+---
+
+Coder [Organizations](../../admin/users/organizations.md) allow administrators
+finer control over groups, templates, workspaces, and provisioners within their
+Coder deployment.
+
+Organizations allow multiple platform teams to offer templates and
+infrastructure to their users instead of having them entirely managed in a
+centralized fashion.
+
+Each organization can have its own unique admin and users can belong to multiple
+organizations, but every organization must have separate templates,
+provisioners, groups, and workspaces.
+
+On this best practice page, we cover some of the ways you can use Organizations
+to make it easier to manage your groups smoothly.
+
+## How Coder organizations work
+
+Organizations are the hierarchical parent for templates, groups, and
+provisioners. Every new organization must have separate templates, provisioners,
+and groups.
+
+![Organizations architecture](../../images/best-practice/organizations-architecture.png)
+
+Users can belong to multiple organizations while templates and provisioners
+cannot.
+
+## When to use organizations
+
+Organizations increase the maintenance overhead of a Coder deployment, so we
+recommend that you only use them when necessary.
+
+Use organizations when a separate group of users needs to manage their own
+templates and underlying infrastructure. If a group of users already has a
+separate, functional platform team willing to write templates or manage
+clusters, organizations may be a good fit.
+
+### Organization use case examples
+
+Here are a few examples for a fictional organization called MegaCo. It is
+deployed with Coder and has 1000 users in production. Today, MegaCo has a single
+(default) organization and a central platform team but is evaluating whether to
+use organizations for several use cases.
+
+| **Use Case**                                                                         | **Description**                                                                                                                                                                                                                                                                                                                                                                 | **Good fit for organizations?**                                                                         |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Mergers and acquisitions                                                             | Raptix, a 180-person startup recently acquired by MegaCo, has an independent cloud account, platform team, and Terraform modules and pipelines for deploying their code. They want to use Coder.                                                                                                                                                                                | ✅ Organizations                                                                                        |
+| Independent cloud-native teams that manage their namespaces, images, and/or clusters | MegaCo has six teams responsible for their own dev, staging, and production Kubernetes clusters and frequently deploy & test their work with `kubectl` and `helm`.</br></br>They wish to hook up Coder to their cluster so they can write and manage IDE templates for connecting to the cluster with their IDE                                                                 | ✅ Organizations                                                                                        |
+| Java monolith                                                                        | MegaCo has identified that anyone developing the Java monolith is best served with a VM instead of a container/cloud-native environment.</br></br>However, the Java team is supported by MegaCo's central platform team.                                                                                                                                                        | ❌ Use instead:</br>A separate template and/or groups                                                   |
+| Off-shore contractors                                                                | MegaCo employs off-shore contractors but has not onboarded them onto Coder due to privacy concerns, data sovereignty rules, and latency considerations.</br></br>They considered a minimal, localized second deployment of Coder, but decided against it due to maintenance overhead.                                                                                           | ✅ Organizations + Workspace Proxies                                                                    |
+| Dev teams                                                                            | Dev teams often need to bring their requirements for dev environments, such as specific repositories and tools                                                                                                                                                                                                                                                                  | ❌ Use instead:</br>Parameters, dev containers, and/or groups                                           |
+| ML Platform Team & ML Developers                                                     | MegaCo's data platform team maintains a homegrown "MLBox" product for data environments with a GPU, Jupyter, etc.</br></br>This team is interested in migrating to Coder for improved cost-saving and auditing of environments, but they need to hook up their own cluster and cloud accounts. They also want their templates only to be accessible to a specific set of users. | ✅ Organizations                                                                                        |
+| Supporting developers in various regions                                             | MegaCo's central platform team supports developers connecting from the East Coast, the West Coast, and Australia. These developers are working on the same projects but need low-latency access to their environments.                                                                                                                                                          | ❌ Use instead:</br>Provisioners and workspace proxies to support multiple regions on a single template |
+
+## How to migrate to organizations
+
+Since templates and workspaces cannot be moved nor can they belong to multiple
+organizations, we recommend that you deprecate your template
+[through the API](../../reference/api/templates.md#update-template-metadata-by-id)
+or [through the Coder CLI](../../reference/cli/templates_edit.md#--deprecated).
+When a template is deprecated, the admin prevents new workspaces from being
+created and developers are notified with a deprecation message which can link to
+an external wiki page on migration instructions.
+
+Users can use a file transfer tool such as
+[rsync](https://linux.die.net/man/1/rsync) to migrate their files from one
+workspace to another.
+
+## Provisioner Isolation and Zero Trust
+
+In the organizations model, provisioners run in a separate
+cluster/infrastructure and have an isolated key to authenticate back with Coder.
+The provisioners have access to separate cloud resources that the control plane
+cannot access. Instead, the control plane sends simple "provisioner jobs" to the
+provisioner and the provisioner is responsible for executing the Terraform.
+
+There are planned improvements to the troubleshooting provisioners process.
+Follow these GitHub issues for more details:
+
+- [coder/coder#15048](https://github.com/coder/coder/issues/15048)
+- [coder/coder#15087](https://github.com/coder/coder/issues/15087)
+- [coder/coder#15192](https://github.com/coder/coder/issues/15192)
+
+## Identity Provider (SSO) Sync
+
+While the Coder UI or API can be used to assign specific users to organizations,
+this is discouraged. Instead, we recommend syncing the state from your identity
+provider such as Okta. A single claim from the identity provider (like
+`memberOf`) can be used to sync site-wide roles, organizations, groups, and
+organization roles.
+
+### Planned enhancements
+
+Site-wide role sync is managed via server flags. We plan on changing this to
+runtime configuration so Coder does not need a re-deploy:
+
+- Issue [coder/internal#86](https://github.com/coder/internal/issues/86)
+
+Make all sync configurable via the dashboard UI:
+
+- [coder/coder#15290](https://github.com/coder/coder/issues/15290)
+
+Regex filters and mapping can be configured to ensure the proper resources are
+allocated in Coder. Learn more about [IDP sync](../../admin/users/idp-sync.md).
+
+## Custom Roles
+
+Custom roles are organization-scoped and can be used to limit access controls
+within an organization. Custom roles can be applied to the default organization.
+
+Some examples of custom roles that can be created:
+
+**Provisioner Admin**
+
+- The user can deploy provisioners but not manage templates. This may be useful
+  if automation is used to create and update templates in the organization.
+
+**Template Editor**
+
+- Inverse of provisioner admin: User can manage templates but not deploy
+  provisioners. This may be useful if the provisioner and template are deployed
+  via automation and users are allowed to edit them.
+
+**Template Pusher**
+
+- A system account that can push new templates from a git repo but cannot manage
+  users or delete templates.
+
+We’re interested in identifying new use cases for custom roles. Please
+[create a GitHub issue](https://github.com/coder/internal/issues/new?title=request%28orgs%29%3A+request+title+here&labels=["customer-feedback"]&body=please+enter+your+request+here)
+with your suggestion or request.
+
+## Managing Organizations at Scale
+
+Using ClickOps to onboard new organizations, set quotas, and SSO sync can be
+cumbersome, especially if you want to "seed" organizations with provisioners and
+starter templates.
+
+Support for managing Organizations via the coderd Terrafom provider is planned
+so that this can be done declaratively and bulk updates to things like templates
+and quotas can be performed easily:
+
+- Issue
+  [coder/terraform-provider-coderd#39](https://github.com/coder/terraform-provider-coderd/issues/39)