diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index c929cef4..a4cbcb67 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -103,11 +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 | -When using the Helm chart, enable `serviceAccount.rbac.enabled=true` so the -server can manage `ModelMetadata` and `ModelCacheEntry` resources. For a -standalone Kubernetes deployment, apply `examples/crds.yaml` and -`examples/p2p_transfer_k8s/server/kubernetes_backend/rbac-modelmetadata.yaml` -before deploying the server. +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 diff --git a/helm/README.md b/helm/README.md index f677ea49..2bcd7fc6 100644 --- a/helm/README.md +++ b/helm/README.md @@ -72,6 +72,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 | `{}` | @@ -181,6 +182,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 diff --git a/helm/templates/rbac.yaml b/helm/templates/rbac.yaml index a2c66f50..00716307 100644 --- a/helm/templates/rbac.yaml +++ b/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 diff --git a/helm/values.yaml b/helm/values.yaml index c06a767f..f551a258 100644 --- a/helm/values.yaml +++ b/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