chore: update orgs docs (#620)

Author: Katie Horne

admin/organizations.md

@@ -0,0 +1,48 @@
+---
+title: Organizations
+description: Learn about Coder organizations.
+---
+
+Organizations are groups that tie together users, workspaces, and images. You
+must assign all of your images and workspaces to a specific organization. An
+end-user can only access images that are assigned to the same organization they
+are.
+
+> Be sure to familiarize yourself with the
+> [types of roles](../access-control/organizations.md) you can assign users
+> within an organization.
+
+## The default organization
+
+Coder automatically creates a default organization for you during the deployment
+process. You can then assign users and their workspaces to that organization.
+
+If you have multiple organizations, you can set one or more as the default; you
+can also change which organizations are defaults at any time.
+
+## Namespaces
+
+> **Deprecation notice**: The `namespaceWhitelist` field has been deprecated in
+> [Coder version 1.17](../../changelog/1.17.0.md).
+
+Coder's Helm chart previously included a `namespaceWhitelist` field that
+accepted a list of cluster namespaces and made them available to Coder. The
+[workspace provider feature](../workspace-providers/index.md) supersedes this
+field.
+
+You will not be able to make any changes _unless_ you are removing namespaces
+that no longer contain workspaces with Coder deployments v1.17.0 or later (if
+you remove namespaces from the `namespaceWhitelist` field, the workspaces in the
+namespaces are no longer accessible).
+
+For older Coder deployments, you can continue using existing workspaces in
+whitelisted namespaces, though you cannot create new workspaces in those
+namespaces.
+
+If you want to separate Coder workspaces by namespaces in a Kubernetes cluster,
+you can do so by
+[deploying a new workspace provider](../workspace-providers/deployment.md) to
+each additional namespace in the cluster. The workspace provider provisions
+workspaces to the namespace it has been deployed to, and you can control access
+to each workspace provider via an organization allowlist to replace the previous
+organization namespace behaviors.

admin/organizations/index.md

@@ -0,0 +1,71 @@
+---
+title: Org management
+description: Learn about managing organizations.
+---
+
+This article shows how you can create, view, edit, or delete an organization.
+
+## Create a new organization
+
+[Site admins and site managers](../access-control/user-roles.md) can create new
+organizations by going to **Manage** > **Organizations** > **New Organization**.
+
+![Create a new organization dialog](../../assets/admin/create-an-org.png)
+
+Provide a **name** and (optionally) a **description** for this organization. If
+you want this to become a **Default organization**, make sure to check the box
+for this.
+
+You can also control how Coder manages resources for workspaces in this
+organization. You can set the:
+
+- **CPU Provisioning Rate**: sets the ratio of virtual CPUs to physical CPUs; if
+  you set a higher ratio, you can schedule a larger number of workspaces per
+  node, though it will also lead to greater CPU contention
+- **Workspace Shutdown Behavior**: The number of hours a workspace may be idle
+  before Coder stops it automatically to help free up resources
+
+Finally, you can set **Resource Quotas**. These are limits on the number of
+**CPUs** and **GPUs**, as well as the amount of **memory** and **disk space**,
+each developer can request concurrently for running workspaces in this
+organization. The limits for what you can set are as follows:
+
+- **CPUs**: 128 CPU cores
+- **Memory**: 256 GBs
+- **Disk**: 8192 GB
+- **GPUs**: 20 GPUs
+
+When you've set your parameters, click **Create** to proceed.
+
+## Viewing an organization
+
+You can view information about an organization at any time by going to
+**Manage** > **Organizations** and selecting the org of interest.
+
+The **Members** tab displays users that belong to the org. The **Workspaces**
+tab displays the workspaces that belong to the org, as well as the resources
+they consume.
+
+![Org resources](../../assets/admin/org-resources.png)
+
+## Editing an organization
+
+You can edit an organization at any time by going to **Manage** >
+**Organizations**.
+
+![Edit an organization dialog](../../assets/admin/edit-an-org.png)
+
+Find the organization you want to edit, and click to open. In the top-right,
+click **Edit** to launch the **Edit Organizations** dialog.
+
+When you're finished making your changes, click **Update** to save.
+
+## Deleting an organization
+
+You can edit an organization at any time by going to **Manage** >
+**Organizations**. Find the organization that you want to delete, and click to
+open. In the top right, click **Delete**. Confirm that you would like to delete
+the org.
+
+> Deleting an organization does not delete users or workspaces. Coder reassigns
+> existing users and workspaces to a default org.

admin/organizations/manage.md

@@ -34,8 +34,8 @@ the application (you can get a trial license for free
 [here](https://coder.com/trial)). Once logged in, you’ll be able to access the
 [administration management](./admin/index.md) menu to set up things such as
 [access controls](./admin/access-control/index.md) with OpenID Connect (OIDC),
-[create organizations](./admin/organizations.md), and create an OAuth app for
-your users to [connect to your Git provider](./admin/git.md).
+[create organizations](./admin/organizations/index.md), and create an OAuth app
+for your users to [connect to your Git provider](./admin/git.md).
 
 At a minimum, you’ll want to ensure you
 [add a container registry](./admin/registries/index.md) for your development
@@ -52,8 +52,8 @@ Connect (OIDC) with [Azure AD](./guides/admin/oidc-azuread.md) or
 [Okta](./guides/admin/oidc-okta.md). If you are using another Identity Provider
 (IdP), the process should be very similar. With OIDC configured, Coder will
 automatically create a user and add them to the
-[default organization](./admin/organizations.md) when a developer logs in for
-the first time.
+[default organization](./admin/organizations/index.md) when a developer logs in
+for the first time.
 
 ## Automate
 

assets/admin/org-resources.png

@@ -190,6 +190,36 @@
             }
           ]
         },
+        {
+          "path": "./admin/organizations/index.md",
+          "children": [
+            {
+              "path": "./admin/organizations/manage.md"
+            }
+          ]
+        },
+        {
+          "path": "./admin/registries/index.md",
+          "children": [
+            {
+              "path": "./admin/registries/default-registry.md"
+            },
+            {
+              "path": "./admin/registries/gcr.md"
+            }
+          ]
+        },
+        {
+          "path": "./admin/satellites/index.md",
+          "children": [
+            {
+              "path": "./admin/satellites/management.md"
+            },
+            {
+              "path": "./admin/satellites/migration.md"
+            }
+          ]
+        },
         {
           "path": "./admin/workspace-management/index.md",
           "children": [
@@ -219,28 +249,6 @@
             }
           ]
         },
-        {
-          "path": "./admin/registries/index.md",
-          "children": [
-            {
-              "path": "./admin/registries/default-registry.md"
-            },
-            {
-              "path": "./admin/registries/gcr.md"
-            }
-          ]
-        },
-        {
-          "path": "./admin/satellites/index.md",
-          "children": [
-            {
-              "path": "./admin/satellites/management.md"
-            },
-            {
-              "path": "./admin/satellites/migration.md"
-            }
-          ]
-        },
         {
           "path": "./admin/workspace-providers/index.md",
           "children": [
@@ -273,9 +281,6 @@
         {
           "path": "./admin/git.md"
         },
-        {
-          "path": "./admin/organizations.md"
-        },
         {
           "path": "./admin/stun.md"
         },

getting-started.md

@@ -17,6 +17,15 @@ Install the following dependencies if you haven't already:
 [PostgreSQL](https://www.postgresql.org/docs/12/admin.html) instance to store
 data, including workspace information and session tokens.
 
+## Doctor
+
+Before proceeding, we strongly recommend running
+[Doctor](https://github.com/cdr/coder-doctor), which is Coder-supplied
+command-line tool that evaluates whether your environment is ready to install
+Coder. If there are issues with your cluster that may impact the installation
+process, Doctor will return information on what the issue is and suggestions on
+how you can fix it.
+
 ## Creating the Coder namespace (optional)
 
 We recommend running Coder in a separate

manifest.json

@@ -97,7 +97,7 @@ By default, Coder allocates resources (CPU cores, memory, and disk space) based
 on the parent image. You can modify these starting values, though the maximum
 number of CPU cores, amount of memory, and allocation of disk space you can
 request for your workspace are determined by the Coder
-[site manager on an organization level](../admin/organizations.md#create-a-new-organization).
+[site manager on an organization level](../admin/organizations/index.md#create-a-new-organization).
 
 Coder displays a warning if you choose your resource settings and they're less
 than the image-recommended default, but you can still create the workspace.