OpenClaw EnterpriseDOCSGitHub

Kubernetes Compute Driver

Contents

Overview

This implementation follows the ComputeDriver contract.

Kubernetes Compute provisions or adopts one namespace per tenant and creates each Agent’s gateway. Dedicated Gateways and Harnesses use separate Pods, identities and volumes; embedded OpenClaw shares one Pod. Experimental executionCluster places dedicated Harnesses in a second cluster; cloud and complete runtime acceptance remain pending.

New managed namespaces use oce- plus 15 hexadecimal characters of the Namespace ID’s SHA-256 digest, which fits OpenShell pre.5 Workspace names. Earlier oce-<slug>-<hash12> namespaces require the exact tenant label, matching namespace-id annotation and OpenClaw manager label; the Driver never creates this form. Wrong names or duplicate tenant claims fail closed. Adopted namespaces keep their names; OpenShell rejects names exceeding its Workspace limit.

The optional OpenShell Sandbox Driver is designed to own dedicated Codex and native OpenClaw Harness Pods while Compute keeps the other resources. Dedicated native OpenClaw requires a selected SandboxDriver that provisions the Harness and declares networking, filesystem, and process containment. Stock OpenShell cannot provide required credential and workload-identity projections; Agent deployment with OpenShell remains unsupported.

Operator contracts:

Lifecycle

Execution modes

Each Agent-owned gateway Deployment has exactly one desired replica and uses Recreate: Kubernetes stops the previous Pod before starting its replacement, so gateway rollout can cause transient downtime. Neither Kubernetes Deployment nor OCC routing provides node-level process fencing during partitions or manual replacement.

Harness configuration selects the Agent's execution topology:

Dedicated replacement opts into the exclusive preparation contract: the worker stops predecessors before starting the new Harness. This permits RWO workspace storage with deployment downtime; restore previous configuration through a new version instead of restarting its old snapshot.

Enabled external channels require dedicated execution. Unsupported Harness and execution-mode combinations fail deployment. Embedded OpenClaw is never delegated to OpenShell.

Stopping an Agent first deletes its exact gateway route and gateway runtime, then removes the dedicated Harness Deployment or delegates provider-owned Harness removal; Sandbox cleanup follows the provisioning lifecycle. Stop retains Agent-owned PersistentVolumeClaims and runtime credential Secrets; retirement removes resources for that Agent revision. Repeated stop observes exact ownership and converges when the runtime objects are already absent.

Plugin startup status

Compute-owned OpenClaw and Codex runtimes publish private startup results after attempting plugins and verifying configuration: Agent revision ID, runtime instance, successful selection IDs, and warnings (PLUGIN_INSTALL_FAILED or PLUGIN_AUTH_REQUIRED) for disabled selections. Compute reads the exact workload through the authenticated Pod proxy under tenant-local RBAC; workloads receive no Kubernetes write credentials. The endpoint is not public. Ownership, startup identity, selection keys, and warning codes must match; missing, malformed, or foreign status cannot establish readiness.

Embedded OpenClaw disables failed plugins and their managed tool allowances before Gateway startup. Dedicated Codex applies current results before serving and refreshes them after changed restart results. Failed-only app bindings are disabled; successful selections retain admitted policy and required shared bindings.

The Codex app-server credential derives from the Agent's transport Secret, Agent revision ID, and startup identity, so a gateway configured for the previous startup cannot authenticate to a restarted Agent. Its supervisor obtains the new status, applies the matching exclusions, and respawns the gateway process with the new credential, closing the interval before its next status poll.

The worker commits warnings with successful deployment under its live claim; restarts recompute status. No receipt ConfigMaps, finalizers, failure latches, or post-commit acknowledgments are used. Requested selections and account-wide installations remain unchanged; rollback is not promised.

Current runtime diagnostics

Kubernetes Compute implements the optional deployment diagnostics contract. OCC authorizes the specific Agent and Agent revision, then the Driver reads the owned runtime Pods through the Kubernetes apiserver Pod proxy. The private runtime endpoint returns generic checks for the requested Agent revision ID. Compute rejects responses larger than 65,536 bytes or containing more than 32 checks. The API needs Pod get/list and pods/proxy get permission in each runtime namespace. Both roles are read in the tenant namespace for a single cluster. The two-cluster profile reads dedicated Gateways in its control-cluster Gateway namespace. The chart adds these read permissions to the unbound tenant API and Gateway observer roles; operators retain control of their namespace-local bindings. Missing Pods or unavailable private endpoints report unknown diagnostic checks instead of mutating deployment status. The Agent container currently returns no channel checks.

The bundled gateway maps Slack channel status into configuration, authentication, and connectivity checks. They exclude raw Slack responses, credential values, logs, and message text, and never post a message or run a model turn.

Sandbox provisioning

With OpenShell sandboxing, composition adapts SandboxDriver.ensureNamespace to OCC Namespace lifecycle hooks. Compute resolves the exact backing namespace and selected Kubernetes client without calling Sandbox. The hook applies approved namespace-scoped OpenShell labels and NetworkPolicy resources, checks OpenShell gateway readiness, and creates or adopts the Namespace Workspace. Harness provisioning and cleanup follow the SandboxDriver lifecycle: Agent revision cleanup runs even when Compute's ordinary Harness Deployment is absent, and a failed provider Namespace cleanup keeps the Kubernetes namespace. Provider-owned Harness removal stays with the provider, so Compute needs no Sandbox custom-resource permissions. Allow privileged OpenShell init or sidecar containers only through an operator-approved RuntimeClass or equivalent admission exemption with a matching fail-closed policy (admission requirements); the Harness container itself remains unprivileged.

A provider-owned dedicated Harness is ready only when exactly one live Pod in the resolved namespace carries the Agent ID, Agent revision ID, and agent workload-role labels used by the active Service selector, plus all supplied Harness requirement labels, and reports Ready=True. Zero candidates, multiple live candidates (including one Ready and one unready), or a single unready candidate leave preparation at ready: false and prevent activation. Pods with a valid deletion timestamp, in another namespace, or with another Agent ID, Agent revision ID, or role do not count.

Malformed or incomplete Pod lists, invalid identities or conditions, duplicate condition types, contradictory Harness labels, and pagination with more results are errors. Missing optional status or conditions means not ready. Preparation errors run workload cleanup hooks; activation errors precede routing changes. Cancelled observations cannot report ready. Checks establish workload readiness and label uniqueness, not Sandbox IDs, Pod UIDs, guest authentication or runtime generation fencing.

Selected-driver lifecycle hooks

The Driver invokes selected non-Compute lifecycle hooks around Namespace preparation and workload startup or teardown. Hooks receive the operation's cancellation signal; failed revocation blocks resource teardown. The ComputeDriver contract owns the hook ordering and environment restrictions, and the lifecycle-hook flow traces the implementation.

Configuration

Set drivers.compute.id: compute-kubernetes in the Installation YAML loaded by both API and worker through OCC_CONFIG_PATH. Restart both after changes. The field tables and example define the settings inside drivers.compute.configuration:

Setting Type Requirement Value, default, and constraints
authentication object Required Explicit in-cluster identity or named kubeconfig context.
images object Required Gateway/Agent images and immutable-digest policy.
resources object Required Workload requests/limits and namespace quotas/defaults.
network object Required DNS, gateway port, proxy trust, and permitted peers.
servicePrincipalCredentials object Required Explicit workload-identity projection policy.
runtime object Optional Required in production; omission selects the verification runtime.
gatewayRouting object Conditional Dedicated Harnesses with runtime need this and node enrollment.
executionCluster object Optional Experimental second cluster; omitted by default.

See authentication and images and resources.

Limits

Requirements

The worker manages PersistentVolumeClaims and, when private gateway routing is enabled, HTTPRoutes through tenant-local RoleBindings. Only the controller API issues provider credentials. The worker reads admitted transport/channel material and maintains Harness Secret projections for each Agent revision in the tenant namespace. The API does not need gateway Pod reads, exec, route writes, or certificate management for workspace-file access. Do not grant wildcard permissions, cluster-wide access to tenant resources, workload access to controller credentials, or permission to create or escalate RoleBindings.

Existing split-layout installations

Releases before #925 kept each Namespace's Gateways, Gateway state and canonical Secrets in a separate oce-gateways-<hash> namespace. Check for and adopt these tenants with Existing split-layout installations before replacing the controller images.

Troubleshooting

Search documentation