feat(helm): support cluster-wide metadata RBAC

docs/DEPLOYMENT.md

@@ -103,7 +103,13 @@ reachable.
 | `REDIS_URL` | e.g. `redis://host:6379` | when Redis | Redis connection (or set `MX_REDIS_HOST` / `MX_REDIS_PORT`) |
 | `POD_NAMESPACE` / `MX_METADATA_NAMESPACE` | e.g. `default` | when Kubernetes | Namespace for the `ModelMetadata` and `ModelCacheEntry` CRDs |
 
-To use the Kubernetes backend, apply `examples/crds.yaml` at cluster install time (installs both the `ModelMetadata` P2P CRD and the `ModelCacheEntry` registry CRD), then either enable `serviceAccount.rbac.enabled=true` on the Helm chart or apply `examples/p2p_transfer_k8s/server/kubernetes_backend/rbac-modelmetadata.yaml`.
+To use the Kubernetes backend, apply `examples/crds.yaml` at cluster install time
+(installs both the `ModelMetadata` P2P CRD and the `ModelCacheEntry` registry CRD),
+then either enable `serviceAccount.rbac.enabled=true` on the Helm chart or apply
+`examples/p2p_transfer_k8s/server/kubernetes_backend/rbac-modelmetadata.yaml`.
+The chart creates a `ClusterRole` and `ClusterRoleBinding`, allowing the server
+to run in a dedicated namespace while accessing metadata resources in another
+namespace.
 
 For automatic cleanup of P2P metadata, expose the client Pod identity through
 the Kubernetes Downward API. The checked-in vLLM, SGLang, and Dynamo manifests

helm/README.md

@@ -108,6 +108,7 @@ The following table lists the configurable parameters of the ModelExpress chart
 | `serviceAccount.create`                      | Create a service account                       | `true`   |
 | `serviceAccount.annotations`                 | Service account annotations                    | `{}`     |
 | `serviceAccount.name`                        | Service account name                           | `""`     |
+| `serviceAccount.rbac.enabled`                | Create a ClusterRole and ClusterRoleBinding for the Kubernetes metadata backend | `false` |
 | `podAnnotations`                             | Pod annotations                                | `{}`     |
 | `podSecurityContext`                         | Pod security context                           | `{}`     |
 | `securityContext`                            | Container security context                     | `{}`     |
@@ -217,6 +218,21 @@ extraEnv:
         key: secret-key
 ```
 
+### With Kubernetes Backend RBAC
+
+Enabling `serviceAccount.rbac.enabled` creates a `ClusterRole` and
+`ClusterRoleBinding`, allowing a ModelExpress server deployed in a dedicated
+namespace to access metadata resources in a workload namespace:
+
+```yaml
+serviceAccount:
+  rbac:
+    enabled: true
+
+env:
+  MX_METADATA_BACKEND: kubernetes
+```
+
 ## Upgrading
 
 ```bash

helm/templates/rbac.yaml

@@ -3,14 +3,13 @@
 
 # RBAC for the Kubernetes metadata backend.
 # Required when MX_METADATA_BACKEND=kubernetes so the server can manage
-# ModelMetadata CRDs and tensor descriptor ConfigMaps in its namespace.
+# ModelMetadata CRDs and tensor descriptor ConfigMaps across namespaces.
 {{- if and .Values.serviceAccount.create .Values.serviceAccount.rbac.enabled }}
 ---
 apiVersion: rbac.authorization.k8s.io/v1
-kind: Role
+kind: ClusterRole
 metadata:
   name: {{ include "modelexpress.fullname" . }}
-  namespace: {{ .Release.Namespace }}
   labels:
     {{- include "modelexpress.labels" . | nindent 4 }}
 rules:
@@ -27,15 +26,14 @@ rules:
     verbs: ["get", "list", "create", "update", "patch", "delete"]
 ---
 apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
+kind: ClusterRoleBinding
 metadata:
   name: {{ include "modelexpress.fullname" . }}
-  namespace: {{ .Release.Namespace }}
   labels:
     {{- include "modelexpress.labels" . | nindent 4 }}
 roleRef:
   apiGroup: rbac.authorization.k8s.io
-  kind: Role
+  kind: ClusterRole
   name: {{ include "modelexpress.fullname" . }}
 subjects:
   - kind: ServiceAccount

helm/values.yaml

@@ -23,7 +23,7 @@ serviceAccount:
   name: ""
   automount: false
   rbac:
-    # Enable Role + RoleBinding for the Kubernetes metadata backend.
+    # Enable ClusterRole + ClusterRoleBinding for the Kubernetes metadata backend.
     # Required when MX_METADATA_BACKEND=kubernetes.
     enabled: false