From 2bda0aa48d6f6e114d506c7f8e07ea788493bcda Mon Sep 17 00:00:00 2001
From: mesutoezdil <mesudozdil@gmail.com>
Date: Sat, 23 May 2026 16:26:05 +0300
Subject: [PATCH] docs(kubernetes): add RBAC section to setup page

Documents the ServiceAccount, Role, and ClusterRole created by the Helm
chart inline on the setup page, per reviewer feedback on #1250. Reflects
the current chart templates including pods/get for sandbox identity and
tokenreviews/create for projected token validation.

Closes #1018
---
 docs/kubernetes/setup.mdx | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/kubernetes/setup.mdx b/docs/kubernetes/setup.mdx
index b1df4758f..918f0c62c 100644
--- a/docs/kubernetes/setup.mdx
+++ b/docs/kubernetes/setup.mdx
@@ -152,6 +152,45 @@ helm upgrade --install openshell \
   --values my-values.yaml
 ```
 
+## RBAC
+
+The chart creates the following RBAC resources in the release namespace:
+
+| Resource | Scope | Name |
+|---|---|---|
+| ServiceAccount | Namespace | `openshell` |
+| ServiceAccount | Namespace | `openshell-sandbox` (for sandbox pods) |
+| Role + RoleBinding | Namespace | `openshell-sandbox` |
+| ClusterRole + ClusterRoleBinding | Cluster | `openshell-node-reader` |
+
+The namespaced Role covers sandbox lifecycle and identity:
+
+| API Group | Resource | Verbs |
+|---|---|---|
+| `agents.x-k8s.io` | `sandboxes`, `sandboxes/status` | create, delete, get, list, patch, update, watch |
+| `""` | `events` | get, list, watch |
+| `""` | `pods` | get |
+
+The ClusterRole grants node inspection and token validation:
+
+| API Group | Resource | Verbs |
+|---|---|---|
+| `authentication.k8s.io` | `tokenreviews` | create |
+| `""` | `nodes` | get, list, watch |
+
+To use an existing ServiceAccount instead of creating one, set `serviceAccount.create=false` and supply its name:
+
+```shell
+helm upgrade --install openshell \
+  oci://ghcr.io/nvidia/openshell/helm-chart \
+  --version <version> \
+  --namespace openshell \
+  --set serviceAccount.create=false \
+  --set serviceAccount.name=my-existing-sa
+```
+
+The ServiceAccount must already have the Role and ClusterRole bindings described above.
+
 ## Next Steps
 
 - To enable automatic certificate rotation with cert-manager, refer to [Managing Certificates](/kubernetes/managing-certificates).