ROB-523 docs: namespace-scoped RBAC guide (restore + how-it-works)

[Avi-Robusta]

Summary

Restores the RBAC namespace-scoping guide (docs/setup-robusta/rbac-namespace-scoping.rst) and its index.rst toctree entry.

This page was added in #2110 but removed in two commits right before that PR merged (e45a5d90 "Delete rbac-namespace-scoping.rst" + ca8f0398 "Update index.rst"), so it never made it onto master. The runner read-only guide and the runner.overrideClusterRoles chart change from #2110 are already merged; only this page was dropped.

What's in the page

• How to scope HolmesGPT to specific namespaces via holmes.roleBindingNamespaces (list of namespaces → namespaced RoleBinding per namespace instead of a cluster-wide ClusterRoleBinding).
• A new "How it works" section: the ClusterRole-vs-binding scope table, the rendered RoleBinding manifest, why cluster-scoped resources (e.g. nodes) are not granted, and the kubectl auth can-i caveat.
• Verification commands and a note that the runner stays cluster-wide (with a pointer to the read-only guide).

Related

Depends on the Holmes chart value holmes.roleBindingNamespaces from HolmesGPT/holmesgpt#2257 (open).

🤖 Generated with Claude Code

[github-actions]

✅ Docker image ready for db474b0 (built in 37s)

• us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:db474b0

⚠️ Warning: does not support ARM (ARM images are built on release only - not on every PR)

Use this tag to pull the image for testing.

📋 Copy commands

⚠️ Temporary images are deleted after 30 days. Copy to a permanent registry before using them:

gcloud auth configure-docker us-central1-docker.pkg.dev
docker pull us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:db474b0
docker tag us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:db474b0 me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:db474b0
docker push me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:db474b0

Patch Helm values in one line:

helm upgrade --install robusta robusta/robusta \
  --reuse-values \
  --set runner.image=me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:db474b0

[coderabbitai]

Walkthrough

Adds a new documentation page about namespace-scoped RBAC, links it into the setup-robusta docs index, and documents the binding model, limits, verification commands, and runner scope notes.

Changes

RBAC Namespace Scoping Docs

Layer / File(s)	Summary
Docs index entry docs/setup-robusta/index.rst	Adds rbac-namespace-scoping to the hidden Sphinx toctree.
RBAC scope overview docs/setup-robusta/rbac-namespace-scoping.rst	Introduces the default cluster-wide RBAC model and the chart objects used to scope access with per-namespace RoleBindings.
Cluster binding removal docs/setup-robusta/rbac-namespace-scoping.rst	Describes deleting the cluster-wide ClusterRoleBinding and warns that helm upgrade recreates it.
RBAC behavior and limits docs/setup-robusta/rbac-namespace-scoping.rst	Explains ClusterRoleBinding versus RoleBinding scope, authorization behavior, scoped-mode limitations, and node-related kubectl auth can-i behavior.
Verification and runner notes docs/setup-robusta/rbac-namespace-scoping.rst	Adds kubectl auth can-i verification examples and notes that the runner remains cluster-wide with limited override support.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• robusta-dev/robusta#2110: The new doc references runner.overrideClusterRoles, which is the RBAC override mechanism changed in this PR.

Suggested reviewers: RoiGlinik

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: restoring a namespace-scoped RBAC documentation guide.
Description check	✅ Passed	The description accurately explains the restored guide, its toctree entry, and the namespace-scoping details.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch avi/restore-rbac-namespace-scoping

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/setup-robusta/rbac-namespace-scoping.rst`:
- Around line 37-38: The wording in the namespace-scoping docs overstates the
security outcome by calling it “fully restricted” even though the runner remains
cluster-wide later in the page; update the sentence in the affected docs section
to use the more accurate phrasing “namespace-scoped, read-only deployment” and
keep the surrounding reference to the read-only runner consistent.
- Around line 96-100: Rephrase the `can-i` explanation in the section around the
`kubectl auth can-i list nodes` example so it explicitly says the check is
namespace-scoped when `-n default` is used. Make clear in the same paragraph
that `can-i` may return `yes` for `nodes` inside `default`, but the `holmes-sa`
ServiceAccount still cannot perform a real cluster-scoped `kubectl get nodes`
without a cluster-wide binding.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d0159d7c-746d-4709-9d69-1033a7725df8

📥 Commits

Reviewing files that changed from the base of the PR and between 349f194 and e18bd7b.

📒 Files selected for processing (2)

• docs/setup-robusta/index.rst
• docs/setup-robusta/rbac-namespace-scoping.rst