feat(helm): support cluster-wide metadata RBAC

[kevin85421]

Summary

A Kubernetes production best practice is to deploy a controller or control-plane service in a dedicated namespace while allowing its namespaced custom resources to live alongside workloads in other namespaces.

ModelExpress currently cannot support this deployment pattern with the RBAC generated by its Helm chart. For example, when the ModelExpress server is deployed in the modelexpress namespace and ModelMetadata or ModelCacheEntry resources are created in the default namespace, the server receives a 403 Forbidden error:

modelcacheentries.modelexpress.nvidia.com is forbidden:
User "system:serviceaccount:modelexpress:mx-modelexpress" cannot list resource
"modelcacheentries" in API group "modelexpress.nvidia.com" in the namespace "default"

This happens because the Helm chart currently creates a namespace-scoped Role and RoleBinding in the Helm release namespace. Those resources only grant the ModelExpress ServiceAccount access to resources in the same namespace.

This PR changes the resources created by serviceAccount.rbac.enabled=true to a ClusterRole and ClusterRoleBinding, allowing a ModelExpress server deployed in a dedicated namespace to manage its metadata resources in other namespaces.

The setting remains disabled by default.

Future RBAC granularity

If ModelExpress needs more granular, least-privilege RBAC in the future, the Helm chart can add a namespaced installation mode and explicit watch-namespace configuration. The KubeRay Helm chart RBAC design provides a useful reference for supporting both cluster-scoped RBAC and namespace-scoped RBAC based on the operator's installation and watch scope.

Usage

serviceAccount:
  rbac:
    enabled: true

env:
  MX_METADATA_BACKEND: kubernetes
  MX_METADATA_NAMESPACE: default

Validation

• Reproduced the failure in kind with the server in modelexpress and its metadata namespace set to default
• Confirmed that the existing Role and RoleBinding cause a 403 Forbidden error and CrashLoopBackOff
• Confirmed that this PR creates a ClusterRole and ClusterRoleBinding
• Confirmed that kubectl auth can-i returns yes for the ModelExpress ServiceAccount in default
• Confirmed that the ModelExpress Pod becomes 1/1 Running after applying this PR
• helm lint helm
• Rendered and asserted that RBAC remains absent when serviceAccount.rbac.enabled=false
• git diff --check

Full kind reproduction: #621 (comment)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Walkthrough

The Helm chart adds an opt-in clusterWide RBAC setting. It renders namespaced or cluster-scoped Kubernetes RBAC resources and documents configuration, permissions, and MX_METADATA_NAMESPACE behavior.

Changes

Kubernetes RBAC configuration

Layer / File(s)	Summary
Conditional RBAC resources helm/values.yaml, helm/templates/rbac.yaml	The chart adds serviceAccount.rbac.clusterWide, defaulting to false. The templates render either namespaced or cluster-scoped RBAC resources.
Deployment configuration documentation docs/DEPLOYMENT.md, helm/README.md	The documentation describes RBAC modes, cluster-wide configuration, required CRDs, and namespace selection through MX_METADATA_NAMESPACE.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: 🔵 Low · up to 29448

When enabled, the chart grants metadata access across namespaces, including full ConfigMap access, while the documentation does not consistently explain that scope or the ServiceAccount prerequisite. The default behavior remains unchanged, so the PR is mergeable with explicit owner awareness and documentation follow-up.

Poem

I’m a rabbit with a chart in my paws,
Namespaced roles follow Kubernetes laws.
Cluster-wide access can now hop in,
With MX_METADATA_NAMESPACE guiding within.
Helm values make the choice precise—
RBAC blooms with documented advice.

🚥 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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding optional cluster-wide metadata RBAC support to the Helm chart.

---

_{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/DEPLOYMENT.md`:
- Around line 108-109: Update the RBAC guidance in docs/DEPLOYMENT.md lines
108-109 and helm/README.md lines 224-226 to state that chart-managed RBAC
requires both serviceAccount.create=true and serviceAccount.rbac.enabled=true;
alternatively, explain that when using an existing ServiceAccount, RBAC must be
applied externally.

In `@helm/values.yaml`:
- Around line 29-31: Update the clusterWide RBAC description in helm/values.yaml
(29-31) to explicitly warn that cluster-wide mode grants access to ConfigMaps in
all namespaces; add the same warning to the deployment procedure in
docs/DEPLOYMENT.md (110-113) and the Helm example in helm/README.md (238-241),
without changing behavior.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 897b98b3-d0c9-4ab2-a8fd-74ba2490f3f5

📥 Commits

Reviewing files that changed from the base of the PR and between 46da339 and 29448d5.

📒 Files selected for processing (4)

• docs/DEPLOYMENT.md
• helm/README.md
• helm/templates/rbac.yaml
• helm/values.yaml

[kevin85421]

cc @ganeshku1 @KavinKrishnan for review. Thanks!