add byoc

Makefile

@@ -60,6 +60,7 @@ SHELL_SRC_FILES := $(shell find . $(FIND_EXCLUSIONS) -type f -name '*.sh')
 OS_ARCHES := \
 	linux_amd64 linux_arm64 linux_armv7 \
 	darwin_amd64 darwin_arm64 \
+	linux_riscv64 \
 	windows_amd64.exe windows_arm64.exe
 
 # Archive formats and their corresponding ${OS}_${ARCH} combos.

docs/admin/rabbit/README.md

@@ -7,6 +7,7 @@ Tiered RBAC is a suite of features that improves Coder's security posture for hi
 This includes:
 
 - Organizations
+- Groups
 - Service Accounts
 - Custom Roles
 
@@ -14,13 +15,22 @@ This includes:
 
 Organizations allow multiple platform teams to coexist within a single Coder instance with isolated cloud credentials, templates, and Coder provisioners. Unlike groups, users within an organization can hold roles that allow them to access all resources within the organization, but not the Coder deployment.
 
-There are several use cases for this:
+Examples:
 
-- The data science platform team wants to use their own cluster for data science workloads and needs to manage several templates and troubleshoot broken workspaces
-- Contractors are isolated to their own organization, can't access resources in other organizations
+- Contractors are isolated to their own `External Developers` organization so they can't access resources in other organizations
+- The `ML Platform` and `Developer Platform` teams coexist on a single Coder deployment but bring different provisioners and credentials
 
 Users can belong to multiple organizations. Workspaces, templates, provisioners, and groups are scoped to a single organization.
 
+## Groups
+
+Groups are a logical grouping of users inside an organization. They inherently do not have permissions or roles but, like users, groups can own workspaces and provisioners.
+
+Examples:
+
+- The `@quality-assurance` group has a Windows workspace they use share for testing
+- The `@data-science` group has a provisioner in their own Kubernetes cluster but use a standard template
+
 ## Service Accounts
 
 Service accounts can be used for CI jobs, third-party integrations, and other automation. Unlike other accounts in Coder, service accounts do not consume a license seat or have an OIDC/password login method, so they cannot be used to log in to the Coder UI.
@@ -29,22 +39,22 @@ Service accounts can be used for CI jobs, third-party integrations, and other au
 
 Custom roles can be created to give users a granular set of permissions within the Coder deployment or organization.
 
-There are several cases for this:
+Examples:
 
-- The "Banking Compliance Auditor" custom role cannot create workspaces, but can read template source code and view audit logs
-- The "Team Lead" role can access user workspaces for troubleshooting purposes, but cannot edit templates
-- The "Platform Member" role cannot edit or create workspaces as they are created via a third-party system
+- The `Banking Compliance Auditor` custom role cannot create workspaces, but can read template source code and view audit logs
+- The `Organization Lead` role can access user workspaces for troubleshooting purposes, but cannot edit templates
+- The `Platform Member` role cannot edit or create workspaces as they are created via a third-party system
 
 Custom roles can also be applied to service accounts:
 
-- A "Health Check" role can view deployment status but cannot create workspaces, manage templates, or view users
-- A "CI" role can update manage templates but cannot create workspaces or view users
+- A `Health Check` role can view deployment status but cannot create workspaces, manage templates, or view users
+- A `CI` role can update manage templates but cannot create workspaces or view users
 
 ---
 
 ### Recipes
 
-Learn how to use tiered RBAC with concrete examples.
+Learn how to use tiered RBAC with concrete examples:
 
-- [Bring your own cluster](#): Allow different groups to bring their own Kubernetes cluster into Coder, or optionally build their own templates on entirely different infrastructure.
+- [Bring your own cluster](./guides/byoc.md): Allow different groups to bring their own Kubernetes cluster into Coder, or optionally build their own templates on entirely different infrastructure.
 - [Shared workspaces](#): Allow users to share workspaces with other users in the same organization.

docs/admin/rabbit/guides/byoc.md

@@ -1,21 +1,33 @@
 # Bring your own cluster
 
-Allow different groups to bring their own Kubernetes cluster into Coder, or optionally build their own templates on entirely different infrastructure.
+Allow different teams to bring their own Kubernetes cluster into Coder, or optionally build their own templates on entirely different infrastructure.
 
-## Prerequisites
+## Before you start
 
-- A Coder deployment with [tiered RBAC](../README.md) enabled
+First, you need a Coder deployment with [tiered RBAC](../README.md) enabled. You also must have the `Global Administrator` role.
 
-## Tutorial
+## Option 1: Isolated Organizations
 
-Not inside a list:
+To give teams full autonomy of their Coder usage, templates, and infrastructure, consider giving them an isolated organization.
+
+First, create an organization:
 
 <div class="tabs">
 
 ## UI
 
+Visit your deployment settings page: `https://coder.example.com/deployment/organizations`
+
+![Create Organization](../../../images/rabbit/create-organization.png)
+
 ## CLI
 
+```sh
+coder organization create \
+  --name data-science \
+  --description "Templates managed by the data platform team"
+```
+
 ## HCL
 
 ```hcl
@@ -23,35 +35,117 @@ provider "coderd" {}
 
 resource "coderd_organization" {
   name        = "data-science"
-  description = "Lorem ipsum"
+  description = "Templates managed by the data platform team"
 }
 ```
 
 </div>
 
-Text below it
+While template management is the responsibility of this new organization, you can optionally provide a set of starter templates that are tailored to them, outside of the Coder defaults:
 
-1. Inside a list
+![Starter templates](../../../images/rabbit/starter-templates.png)
 
-    <div class="tabs">
+The best way to give users access to this group is via claims identity provider claims:
 
-    ## UI
+<div class="tabs">
 
-    ## CLI
+## coder server
 
-    ## HCL
+The following server config maps people with the `ds` group claim to the `Everyone` group in the `data-science` organization:
 
-    ```hcl
-    provider "coderd" {}
+```text
+CODER_OIDC_GROUP_MAPPING '{"ds-user": "data-science::Member:Everyone"}'
+CODER_OIDC_ROLE_MAPPING '{"ds-admin": "data-science:Administrator:Everyone"}'
+```
 
-    resource "coderd_organization" {
-      name        = "data-science"
-      description = "Lorem ipsum"
-    }
-    ```
+## HCL
 
-    </div>
+The following HCL maps people with the `ds-user` group claim to the `Everyone` group in the `data-science` organization:
 
-    For optimal auditing and self-service, we recommend managing organizations with infrastructure as code (HCL).
+```hcl
+provider "coderd" {}
 
-1. idk
+data "coder_organization" "data_science" {
+  name = "data-science"
+}
+
+# Add users to the data science group
+resource "coderd_idp_mapping" "data_science_members" {
+  claim_name = "groups"
+  claim_value_includes = "ds-user"
+  organization_id = data.coder_organization.data_science.id
+  group_id = data.coder_organization.data_science.default_group_id
+  role_id = data.coder_organization.data_science.member_role_id
+}
+
+# Add admins to the data science group
+resource "coderd_idp_mapping" "data_science_admins" {
+  claim_name = "groups"
+  claim_value_includes = "ds-user"
+  organization_id = data.coder_organization.data_science.id
+  group_id = data.coder_organization.data_science.default_group_id
+  role_id = data.coder_organization.data_science.admin_role_id
+}
+```
+
+</div>
+
+Now, users can log in and gain access to the data science organization. Users with the `ds-admin` group in their identity provider will be able to manage provisioners, templates, and users within the organization.
+
+## Option 2: Group Provisioners
+
+If you want to manage a central set of templates, while allowing teams to bring their own infrastructure, group provisioners may be a good option.
+
+First, create a custom role allowing certain organization members to create provisioners:
+
+<div class="tabs">
+
+## HCL
+
+The `write:group-provisioner` role allows users to create provisioners in their organization on behalf of any groups they belong to.
+
+```hcl
+provider "coderd" {}
+
+data "coder_organization" "default" {
+  name = "default"
+}
+
+resource "coderd_custom_role" {
+  organization = data.coder_organization.default.id
+  name         = "provisioner-admin"
+  description  = "Create provisioners"
+
+  permission {
+    action = "write"
+    object = "group-provisioner"
+  }
+}
+```
+</div>
+
+[Role sync](#) can be used to automatically add users to the `provisioner-admin` role based on group or role membership in the identity provider.
+
+Users with this role will be able to create provisioners on behalf of their group:
+
+<div class="tabs">
+
+## UI
+
+![Create a provisioner](../../../images/rabbit/create-provisioner.png)
+
+## CLI
+
+<!-- This needs work -->
+
+```sh
+coder provisionerd create \
+  --scope=group \
+  --group=data-science
+```
+
+</div>
+
+When users are creating workspaces, they can now pick from a compatible provisioner:
+
+![Provisioner picker](../../../images/rabbit/create-workspace-provisioner-picker.png)