diff --git a/docs/how-it-works/workspaces.mdx b/docs/how-it-works/workspaces.mdx index d39a35c962..df5e2e1486 100644 --- a/docs/how-it-works/workspaces.mdx +++ b/docs/how-it-works/workspaces.mdx @@ -17,6 +17,9 @@ The CLI targets the `default` workspace unless you set `--workspace` or `OPENSHELL_WORKSPACE`. The logical OpenShell workspace described here is separate from the `/sandbox` filesystem directory inside a sandbox. +For Kubernetes namespace mapping and managed per-workspace namespaces, see +[Workspace on Kubernetes](/kubernetes/workspaces). + ## Understand the Role Model OpenShell combines an identity-provider role with a membership record for each diff --git a/docs/kubernetes/setup.mdx b/docs/kubernetes/setup.mdx index d9e48c3884..6c40df47be 100644 --- a/docs/kubernetes/setup.mdx +++ b/docs/kubernetes/setup.mdx @@ -118,6 +118,10 @@ helm upgrade --install openshell \ The chart automatically generates PKI secrets on first install using pre-install Helm hooks. No manual secret creation is required. +The default Kubernetes driver puts all workspaces in one sandbox namespace. To +have the gateway create a namespace for each workspace, follow +[Workspace on Kubernetes](/kubernetes/workspaces). + ### Split gateway and workspace releases For a platform-managed namespace, install the gateway without namespace-scoped diff --git a/docs/kubernetes/workspaces.mdx b/docs/kubernetes/workspaces.mdx new file mode 100644 index 0000000000..2683b47d21 --- /dev/null +++ b/docs/kubernetes/workspaces.mdx @@ -0,0 +1,141 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Workspace on Kubernetes" +sidebar-title: "Workspaces" +description: "Configure how OpenShell workspaces map to Kubernetes namespaces, including managed per-workspace namespaces." +keywords: "Kubernetes, Workspaces, Namespaces, Managed Mode, Helm, RBAC" +position: 2 +--- + +The Kubernetes compute driver maps each OpenShell workspace to a Kubernetes +namespace. Choose the mapping when you configure the gateway. OpenShell +workspace membership and roles are separate from Kubernetes namespace access; +see [Workspaces](/how-it-works/workspaces) to create workspaces and assign members. + +| Mode | Namespace mapping | Namespace owner | +|---|---|---| +| `shared` (default) | All workspaces use one sandbox namespace. | The platform operator. | +| `managed` | Each workspace uses `openshell-{gateway_id}-{workspace}`. | The OpenShell Kubernetes driver. | +| `operator` | Each workspace maps to a pre-provisioned namespace on an operator allowlist. | The platform operator. | + +[RFC 0011](https://github.com/NVIDIA/OpenShell/tree/main/rfc/0011-multi-player-design#kubernetes-compute-driver-workspace-mapping) +explains the workspace-to-namespace design. The table above reflects the current +driver modes and default. + +## Configure Managed Workspaces + +Use managed mode when the gateway should create and delete a Kubernetes +namespace for each OpenShell workspace. Start with a working +[Kubernetes installation](/kubernetes/setup): the Agent Sandbox controller and +CRDs must be installed, and the cluster CNI must enforce ingress and egress +`NetworkPolicy` in every sandbox namespace. + +Set the Kubernetes driver mode in the Helm values file: + +```yaml +gatewayConfig: + openshell.drivers.kubernetes: + workspace_mode: managed +``` + +Install or upgrade the gateway with those values: + +```shell +helm upgrade --install openshell \ + oci://ghcr.io/nvidia/openshell/helm-chart \ + --version \ + --namespace openshell \ + -f my-values.yaml +``` + +Keep the chart-managed cluster RBAC enabled, or have a cluster administrator +apply the rendered `ClusterRole` and `ClusterRoleBinding` before installing as +a namespace administrator. Managed mode needs cluster-scoped permissions to +create and delete namespaces and to manage sandbox resources in them. See +[Installing without cluster-admin](/kubernetes/setup#installing-without-cluster-admin) +for the separate RBAC procedure. The driver creates the sandbox +`ServiceAccount` in each managed namespace; do not install the +`openshell-workspace` chart there. + + +If this gateway already runs sandboxes in `shared` mode, plan their removal or +migration before changing `workspace_mode`. The new mode maps workspaces to +different Kubernetes namespaces; it does not move existing sandbox resources. + + +The chart uses its fullname as the default `gateway_id`. With the default +fullname `openshell`, workspace `team-ml` uses namespace +`openshell-openshell-team-ml`. Keep the gateway ID stable after creating +workspaces because it is part of their namespace names. The gateway ID and +resulting namespace name must satisfy the Kubernetes DNS-1123 label limit of +63 characters. See the [gateway configuration reference](/how-it-works/gateways/configuration#kubernetes) +for the driver fields. + +## Create and Verify a Workspace + +A Platform Admin creates the OpenShell workspace. Creating the workspace record +alone does not create its Kubernetes namespace. The driver creates the namespace +and sandbox `ServiceAccount` when an operation first needs them, such as +provisioning a sandbox: + +```shell +openshell workspace create --name team-ml +openshell sandbox create --workspace team-ml +``` + +In an OIDC deployment, assign a Workspace Admin or Workspace User membership +before that person uses the workspace. See +[Create a Workspace and Add Members](/how-it-works/workspaces#create-a-workspace-and-add-members). + +Check the namespace after the sandbox is provisioned: + +```shell +kubectl get namespace openshell-openshell-team-ml +kubectl -n openshell-openshell-team-ml get serviceaccount openshell-sandbox +``` + +Replace the namespace name if you use another chart fullname or gateway ID. +The gateway labels managed namespaces with `openshell.ai/managed-by=openshell`, +`openshell.ai/gateway-id`, and `openshell.ai/sandbox-workspace`. + +### Pull Images from a Private Registry + +If the sandbox images require an image-pull Secret, create that Secret in the +configured source namespace (`server.sandboxNamespace`, which defaults to the +Helm release namespace) and list its name in the gateway values: + +```yaml +gatewayConfig: + openshell.drivers.kubernetes: + workspace_mode: managed + image_pull_secrets: [regcred] +``` + +The driver copies each configured Secret into a managed workspace namespace +for each sandbox runtime generation. It removes the copy with that generation. +See the [Kubernetes driver configuration](/how-it-works/gateways/configuration#kubernetes) +for other image settings. + +## Remove a Managed Workspace + +Delete the workspace through OpenShell after removing its sandboxes and other +workspace resources: + +```shell +openshell workspace delete team-ml +``` + +The gateway asks the Kubernetes driver to delete the managed namespace during +workspace deletion. Do not delete the namespace directly while the OpenShell +workspace still exists. See [Delete a Workspace](/how-it-works/workspaces#delete-a-workspace) +for the full list of resources that must be removed first. + +## Use Operator-Managed Namespaces + +If your platform provisions workspace namespaces, use `operator` mode instead. +Configure either `operator_namespace_label` or `operator_namespace_file` in +`gatewayConfig.openshell.drivers.kubernetes`, then install the +`openshell-workspace` chart in each allowlisted namespace. The gateway does not +create or delete those namespaces. See +[Split gateway and workspace releases](/kubernetes/setup#split-gateway-and-workspace-releases).