Repository navigation
Description
User Story
I operate OpenShell gateways for multiple tenants in a shared Kubernetes platform. Each tenant's namespace design is customized — for example, tenant 01234 requires sandbox namespaces named t-01234-{WS}-runtime. I directly need the gateway to render each workspace's sandboxes into namespaces that follow our tenant naming convention, so OpenShell fits the platform standards our RBAC, quotas, NetworkPolicy, and GitOps tooling are keyed on.
Problem Statement
The Kubernetes compute driver's workspace-to-namespace mapping is fixed today:
| Mode | Mapping | Configurable? |
|---|---|---|
shared |
all workspaces → one configured namespace |
name only, no per-workspace mapping |
managed |
openshell-{gateway_id}-{workspace} |
no |
operator |
workspace name = namespace name (identity) | no |
There is no naming rule, template, or mapping configuration. CreateWorkspaceRequest carries only name/labels/request_id, and the driver resolves the target namespace directly from the mode (driver.rs, let target_namespace = match self.config.workspace_mode). Verified unchanged in v0.1.7, v0.1.10-pre.3, and current main.
A tenant convention like t-01234-{WS}-runtime cannot be expressed in any mode.
Impact / Why This Matters
Multi-tenant platforms standardize namespace names per tenant; admission policy, resource quotas, RBAC bindings, and audit tooling match those patterns. Today the only workarounds are:
- Operator mode with workspaces named after the full namespace (e.g. workspace
t-01234-team-ml-runtime): couples the user-facing workspace identity to infrastructure naming. Every CLI call, membership record, and API reference carries the tenant prefix and suffix, and users must know platform internals to name their own workspace. - Managed mode: namespaces get the foreign
openshell-{gateway_id}-{workspace}name, which violates tenant naming standards and breaks pattern-based platform tooling.
Both are adoption blockers for enterprises with customized per-tenant namespace designs.
Proposed Design
Add an optional, deterministic workspace namespace naming rule (template) to the Kubernetes compute driver configuration:
- The rule is a pattern with placeholders, e.g.
t-01234-{workspace}-runtime. Supported placeholders:{workspace}and{gateway_id}; everything else is literal text. - Managed mode: the driver creates, labels, watches, and deletes namespaces using the rendered name. Ownership labels and workspace-delete cleanup follow the rendered name.
- Operator mode: a workspace resolves to the rendered pre-provisioned namespace name instead of the identity mapping. The operator allowlist (
operator_namespace_label/operator_namespace_file) applies to rendered namespace names. The driver still never creates or deletes namespaces. - Default unchanged: with no rule configured, both modes behave exactly as today.
- Validation:
- the template is validated at configuration load (known placeholders only, non-empty, renders to a valid DNS-1123 label shape);
- workspace creation is rejected when the rendered name exceeds the DNS-1123 label limit (63 chars) or is otherwise invalid;
- the mapping must stay collision-free: two workspaces that render to the same namespace are rejected, preserving workspace isolation.
- The rule keeps the mapping deterministic and derivable from the workspace name, so cross-gateway isolation and watch scoping continue to work as designed in RFC 0011. Whether
{gateway_id}(or another uniqueness segment) should be required in multi-gateway clusters is an open question for maintainers. - Configurable through the supported Helm
gatewayConfiginterface.
Open design questions:
- Per-tenant rule sets: one template per gateway deployment covers one convention. Should multiple rules be selectable per workspace (e.g. by workspace label) for gateways serving several tenants with different conventions?
- Relationship to an explicit map: stale PR feat(kubernetes): map workspaces to namespaces #2644 proposes a fail-closed explicit workspace→namespace map. A naming rule expresses a convention once instead of one entry per workspace; the two could coexist (explicit entries overriding the rule). Maintainer preference welcome.
Suggested UX (if applicable)
[openshell.drivers.kubernetes]
workspace_mode = "managed"
workspace_namespace_template = "t-01234-{workspace}-runtime"| Workspace | Rendered namespace (managed: created; operator: pre-provisioned) |
|---|---|
team-ml |
t-01234-team-ml-runtime |
team-data |
t-01234-team-data-runtime |
| rule omitted | openshell-{gateway_id}-team-ml (today's behavior) |
Helm:
gatewayConfig:
openshell.drivers.kubernetes:
workspace_mode: operator
workspace_namespace_template: "t-01234-{workspace}-runtime"
operator_namespace_label: "openshell.ai/workspace=true"Field name is a proposal; workspace_namespace_rule or similar is equally fine.
Acceptance Criteria
- With no rule configured, namespace resolution is unchanged in
shared,managed, andoperatormodes. - Managed mode with a rule creates, labels, and cleans up namespaces under the rendered name, and sandboxes land there.
- Operator mode with a rule renders sandboxes into the matching pre-provisioned namespace; the allowlist is enforced on rendered names; no namespace create/delete permission is required.
- Invalid templates fail configuration validation; workspaces whose rendered name is invalid or too long are rejected at creation.
- Two workspaces rendering to the same namespace are rejected (collision-free mapping).
- Unit tests and the managed/operator workspace-namespace E2E lanes cover custom rules;
docs/kubernetes/workspaces.mdx, gateway configuration docs, and Helm rendering are updated.
Alternatives Considered
- Name workspaces after the target namespace (operator identity mapping): works today but leaks infrastructure naming into every user-facing workspace reference and cannot express conventions where the workspace name is only one segment of the namespace name.
- Explicit per-workspace map (stale PR feat(kubernetes): map workspaces to namespaces #2644): satisfies arbitrary mappings but requires one configuration entry per workspace, kept in sync with tenant provisioning by hand. A rule expresses the tenant convention once and stays deterministic. The two approaches are complementary; this request proposes the rule because our tenants follow conventions, not ad-hoc names.
sharedmode: no per-tenant namespace isolation, so it does not meet the requirement.- External admission/mutating webhooks: the driver's watch scoping, ownership labels, and workspace-delete lifecycle key on the namespace it rendered; redirecting namespaces out-of-band breaks those flows.
Agent Investigation
Verified on v0.1.7, v0.1.10-pre.3, and current main (behavior identical in all three):
crates/openshell-driver-kubernetes/src/driver.rs—target_namespaceresolution:Shared→ configured namespace,Managed→ensure_namespace(workspace)(openshell-{gateway_id}-{workspace}),Operator→ allowlist check thenworkspace.to_string().crates/openshell-driver-kubernetes/src/config.rs—WorkspaceModeenum andoperator_namespace_label/operator_namespace_file; no template or mapping field exists.proto/openshell.protoCreateWorkspaceRequestandproto/datamodel.protoWorkspace— no namespace field.- RFC 0011 (multi-player design) deliberately chose identity mapping for operator mode ("No mapping configuration is required") and deterministic naming for cross-gateway isolation; a naming rule preserves both properties while making the convention configurable.
- Existing coverage to extend:
e2e/rust/tests/workspace_namespace_managed.rs,e2e/rust/tests/workspace_namespace_operator.rs, Helm CI overlaysvalues-workspace-managed.yaml/values-workspace-operator.yaml. - Related: stale PR feat(kubernetes): map workspaces to namespaces #2644 (explicit map, unmerged), feat(kubernetes): inherit operator-assigned sandbox UID/GID from tenant namespaces #5494 (inherit operator-assigned UID/GID from tenant namespaces — same tenant-namespace direction).
Activity