From 49cf1cd3d4aefef8ba3d4505eeb02116cbce41a9 Mon Sep 17 00:00:00 2001
From: Ben <me@bpmct.net>
Date: Wed, 24 Apr 2024 14:14:08 +0000
Subject: [PATCH] initial work for byoc

---
 .../{tiered-rbac.md => rabbit/README.md}      | 23 ++++++--
 docs/admin/rabbit/guides/byoc.md              | 57 +++++++++++++++++++
 docs/manifest.json                            | 15 ++++-
 3 files changed, 88 insertions(+), 7 deletions(-)
 rename docs/admin/{tiered-rbac.md => rabbit/README.md} (60%)
 create mode 100644 docs/admin/rabbit/guides/byoc.md

diff --git a/docs/admin/tiered-rbac.md b/docs/admin/rabbit/README.md
similarity index 60%
rename from docs/admin/tiered-rbac.md
rename to docs/admin/rabbit/README.md
index ae3c02c886..94c95c84e3 100644
--- a/docs/admin/tiered-rbac.md
+++ b/docs/admin/rabbit/README.md
@@ -7,8 +7,8 @@ Tiered RBAC is a suite of features that improves Coder's security posture for hi
 This includes:
 
 - Organizations
+- Service Accounts
 - Custom Roles
-- Custom Token Scopes
 
 ## Organizations
 
@@ -21,6 +21,10 @@ There are several use cases for this:
 
 Users can belong to multiple organizations. Workspaces, templates, provisioners, and groups are scoped to a single organization.
 
+## 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.
+
 ## Custom Roles
 
 Custom roles can be created to give users a granular set of permissions within the Coder deployment or organization.
@@ -28,12 +32,19 @@ Custom roles can be created to give users a granular set of permissions within t
 There are several cases for this:
 
 - 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 trobuleshooting but cannot edit templates
+- 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
 
-## Custom Token Scopes
+Custom roles can also be applied to service accounts:
 
-Custom Token scopes are functionally the same as custom roles, but are designed for service accounts and CI jobs
+- 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" token can view deployment status but cannot create workspaces, manage templates, or view users
-- A "CI" token can update manage templates but cannot create workspaces or view users
+---
+
+### Recipes
+
+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.
+- [Shared workspaces](#): Allow users to share workspaces with other users in the same organization.
diff --git a/docs/admin/rabbit/guides/byoc.md b/docs/admin/rabbit/guides/byoc.md
new file mode 100644
index 0000000000..260dbe9d0a
--- /dev/null
+++ b/docs/admin/rabbit/guides/byoc.md
@@ -0,0 +1,57 @@
+# 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.
+
+## Prerequisites
+
+- A Coder deployment with [tiered RBAC](../README.md) enabled
+
+## Tutorial
+
+Not inside a list:
+
+<div class="tabs">
+
+## UI
+
+## CLI
+
+## HCL
+
+```hcl
+provider "coderd" {}
+
+resource "coderd_organization" {
+  name        = "data-science"
+  description = "Lorem ipsum"
+}
+```
+
+</div>
+
+Text below it
+
+1. Inside a list
+
+    <div class="tabs">
+
+    ## UI
+
+    ## CLI
+
+    ## HCL
+
+    ```hcl
+    provider "coderd" {}
+
+    resource "coderd_organization" {
+      name        = "data-science"
+      description = "Lorem ipsum"
+    }
+    ```
+
+    </div>
+
+    For optimal auditing and self-service, we recommend managing organizations with infrastructure as code (HCL).
+
+1. idk
diff --git a/docs/manifest.json b/docs/manifest.json
index 3717600421..e8659fb9e3 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -1,5 +1,7 @@
 {
-  "versions": ["main"],
+  "versions": [
+    "main"
+  ],
   "routes": [
     {
       "title": "About",
@@ -328,6 +330,17 @@
       "path": "./admin/README.md",
       "icon_path": "./images/icons/wrench.svg",
       "children": [
+        {
+          "title": "Tiered RBAC",
+          "description": "Granular access control",
+          "path": "./admin/rabbit/README.md",
+          "children": [
+            {
+              "title": "Bring Your Own Cluster",
+              "path": "./admin/rabbit/guides/byoc.md"
+            }
+          ]
+        },
         {
           "title": "Authentication",
           "description": "Learn how to set up authentication using GitHub or OpenID Connect",