OpenClaw EnterpriseDOCSGitHub

Existing Kubernetes Namespace Placement Flow

Overview

An Installation administrator explicitly selects an operator-owned Kubernetes namespace while creating its platform Namespace. The running worker verifies authorization and isolation, binds exact tenant identity, and preserves the namespace after deletion. Other tenants retain deterministic managed placement; existing managed namespaces created with the previous deterministic name remain in place when their tenant markers and OpenClaw manager label are exact.

Entry Points

Flow

graph TD
  A["Create platform Namespace"] --> B{"existingNamespace selected"}
  B -->|no| C["Provision deterministic managed namespace"]
  C --> J{"Tenant marker already exists"}
  J -->|current or previous managed name| H
  J -->|wrong name or ownership conflict| K["Fail closed"]
  B -->|yes| D["Authorize administer and persist unique selection"]
  D --> E["Running worker reauthorizes and verifies exact external namespace"]
  E --> F["Bind generated tenant identity while preserving external manager"]
  F --> G["Provision owned infrastructure and mark Namespace ready"]
  G --> H["Place workloads and ConfigMaps in the bound namespace"]
  H --> I["Delete owned infrastructure only; retain external ownership"]

Execution Trace

1. Authorize and persist explicit external selection

packages/occ/src/index.ts:OpenClawController.createNamespace

POST /namespaces accepts { "name": "support", "existingNamespace": "customer-support-prod" }. Omitting existingNamespace keeps ordinary managed placement and creates the current oce-<hash15> namespace name when no tenant namespace already exists. Existing-namespace selection requires ordinary Namespace-create permission plus Installation-level administer and the selected bundled Kubernetes Compute Driver; Docker or external Compute selections reject it with 409. OCC persists the exact physical name with its generated platform Namespace ID before queuing worker provisioning. Partial database uniqueness prevents simultaneous active claims for the same name.

2. Reauthorize and bind the exact external namespace

apps/controller/src/drivers/compute/kubernetes/index.ts:KubernetesComputeDriver.ensureNamespace

The running worker rechecks Installation administer immediately before adoption. Compute reads the exact selected Kubernetes namespace and requires Active status, openclaw.dev/namespace-lifecycle: external, all three restricted Pod Security labels, and no foreign tenant markers or NetworkPolicies. It binds its full Namespace-ID label and matching Namespace-ID annotation together through a resourceVersion-guarded, non-forced patch; concurrent ownership changes fail safely while preserving the manager and unrelated metadata. Missing targets, termination, foreign ownership or additive policies, ambiguous identity, and revoked authorization fail closed without managed fallback. A missing worker RoleBinding keeps provisioning pending; a missing API RoleBinding instead makes subsequent Configuration operations return 503. Compute reconciles its owned quota, limit range, and isolation policies; no worker pause, restart, or Installation setting is needed.

3. Colocate Configuration and workload resources

apps/controller/src/drivers/configuration/kubernetes/index.ts:KubernetesConfigurationDriver

Configuration discovers the bound backing namespace by tenant label for each ConfigMap operation. Managed discovery fails closed when multiple Kubernetes Namespaces claim the tenant, when the claiming object lacks the full openclaw.dev/namespace label and openclaw.dev/namespace-id annotation, or when a managed namespace name is neither the current oce-<hash15> form nor the previous oce-<slug>-<hash12> form. The previous form is accepted only for an already discovered namespace with app.kubernetes.io/managed-by=openclaw-enterprise; new managed namespaces still use the current name. Explicitly external Namespace provisioning rejects Configuration creation with 409 until the worker marks the Namespace ready. Compute uses the same resolved namespace for workloads, dedicated Agent-owned shared PersistentVolumeClaims, private gateway state claims, credentials, and deletion cleanup. Existing exact Namespace, Agent, revision, service-account, and child-resource ownership checks remain unchanged. Revision retirement preserves the current gateway and its owned claims; final gateway teardown removes the exact-owned private and shared claims by UID.

4. Preserve externally owned namespaces during deletion

apps/controller/src/drivers/compute/kubernetes/index.ts:KubernetesComputeDriver.deleteNamespace

OCC first rejects deletion while Agents, Configurations, or service accounts remain. Compute therefore removes only its owned openclaw-quota, openclaw-limits, allow-dns, allow-gateway-ingress, and default-deny objects, preserving default-deny until last. External namespace objects, their tenant markers, RoleBindings, Secrets, and unrelated resources remain untouched. Deleting a failed selection that was never bound to either tenant marker also leaves the external namespace untouched; partial or foreign markers fail closed. An already-missing namespace counts as deleted. After deleting an unclaimed failed tenant, an administrator can correct preparation and retry. Previously claimed namespaces cannot be readopted until an operator deliberately clears both old tenant markers. Managed namespaces retain their existing complete-deletion lifecycle.

Debugging and Verification

Search documentation