Skip to content

feat(kubernetes): configurable workspace-to-namespace naming rules #5827

Open

Description

@laik

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 gatewayConfig interface.

Open design questions:

  1. 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?
  2. 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, and operator modes.
  • 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.
  • shared mode: 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_namespace resolution: Shared → configured namespace, Managed → ensure_namespace(workspace) (openshell-{gateway_id}-{workspace}), Operator → allowlist check then workspace.to_string().
  • crates/openshell-driver-kubernetes/src/config.rs — WorkspaceMode enum and operator_namespace_label / operator_namespace_file; no template or mapping field exists.
  • proto/openshell.proto CreateWorkspaceRequest and proto/datamodel.proto Workspace — 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 overlays values-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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:triage-neededOpened without agent diagnostics and needs triage

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions