Kubernetes Compute configuration
Contents
- Authentication
- Images and resources
- Network
- Workload identity
- Runtime
- Private routing
- Experimental execution cluster
- Example
Set these fields under drivers.compute.configuration in the Installation
startup YAML. Both API and worker load the file at OCC_CONFIG_PATH; restart
both after changes. The schema and validator
reject unknown fields and invalid combinations before provisioning.
Selection fields are shared with other Drivers.
Required rows have no default. Requirements inside an optional object apply when that object is supplied; conditional requirements appear in the last column. See the implementation limits before deployment.
Authentication
| Setting | Type | Requirement | Value, default, and constraints |
|---|---|---|---|
authentication.mode |
string | Required | inCluster uses the controller ServiceAccount and cluster CA; kubeconfig uses an explicit file and context. |
authentication.kubeconfigPath |
string | Optional | Required with kubeconfig; no ambient-file fallback. |
authentication.context |
string | Optional | Required with kubeconfig; no current-context fallback. |
Kubernetes API certificates must be verified in either mode. Credentials remain in the controller's ServiceAccount or protected kubeconfig, not inline YAML values.
Images and resources
| Setting | Type | Requirement | Value, default, and constraints |
|---|---|---|---|
images.gateway, images.agent |
string | Required | Approved image references with lowercase repository paths. |
images.requireImmutableDigest |
boolean | Required | Must be true in production, requiring lowercase @sha256: digests. |
resources.gateway, resources.agent |
object | Required | Each has requests and limits, both with non-negative cpu and memory quantity strings. Requests must fit limits. |
resources.namespace.quota |
string map | Required | Nonempty Kubernetes resource quota; non-negative quantity strings. |
resources.namespace.containerDefaults |
object | Required | Namespace default requests and limits, each with non-negative cpu and memory quantities. |
Quotas and defaults cover both roles in a shared tenant namespace; the two-cluster
profile applies them to each physical target. Quote quantities such as cpu: "4".
The installation profiles explain
the measured memory defaults. Invalid resource pairs, quotas, and selector labels
fail before resource creation.
Object-count quotas, such as pods, services, and count/deployments.apps,
must satisfy Kubernetes integer precision. Use whole counts such as "4";
quantity suffixes that represent a whole count, such as "1000m" or "1.5Ki",
remain valid. Fractional CPU and storage quotas retain their existing rules.
Previously accepted counted quotas that Kubernetes refuses now stop API and
worker startup with a diagnostic naming resources.namespace.quota and the
resource. Correct that entry before restarting either process.
Network
A peer object has required namespace and podLabels fields. Use exact workload
selectors; see networking and isolation
for label constraints, egress rules, and source-address verification.
| Setting | Type | Requirement | Value, default, and constraints |
|---|---|---|---|
network.dns |
peer | Required | Cluster DNS namespace and Pod labels. |
network.gatewayPort |
integer | Required | 1–65535; cannot use runtime-status port 18791. Sandbox routing also reserves the next port. |
network.gatewayTrustedProxyCidrs |
string array | Required | Nonempty proxy socket-source CIDRs; all-source ranges are rejected. |
network.gatewayClients |
peer array | Optional | Nonempty without gatewayRouting; must be omitted with private routing. |
network.pluginStatusProxySourceCidrs |
string array | Optional | API-server Pod-proxy sources, preferably /32 or /128. Omission adds no diagnostics ingress. |
network.repositoryCredentials |
object | Optional | Broker peer plus port (1–65535). Omission adds no broker peer rule. |
network.publicGithubRead |
object | Optional | Reader peer plus IPv4 ClusterIP address; single-cluster only. No reader rule by default. |
network.providerHarness |
object | Optional | Provider peer plus IP address and port (1–65535). No bridge by default; supported only for the documented local OpenShell profile. |
Workload identity
| Setting | Type | Requirement | Value, default, and constraints |
|---|---|---|---|
servicePrincipalCredentials.mode |
string | Required | disabled or projectedServiceAccountToken. Production requires projection unless a Sandbox Driver is selected. |
servicePrincipalCredentials.audience |
string | Optional | Required nonempty audience when projecting a token; no default. |
servicePrincipalCredentials.expirationSeconds |
integer | Optional | Required with projection; 600–86400 seconds, no default. |
Runtime
runtime is optional in the schema, but required for production workloads.
Omission selects the verification runtime. Storage requirements are defined in
storage and credentials.
| Setting | Type | Requirement | Value, default, and constraints |
|---|---|---|---|
runtime.transportSecretPrefix |
string | Required | Must form a DNS-safe Secret name with - and a 12-character suffix. |
runtime.gatewayStorageClassName |
string | Required | DNS-safe StorageClass name for private RWO Gateway disks with filesystem locking and durability. |
runtime.gatewayStorageSizeGiB |
integer | Optional | 1–65536 GiB, default 10. Choose before creating claims and keep fixed until they are removed; see Gateway storage. |
runtime.nodeSelector |
string map | Optional | Compute-owned Harness and embedded Pod placement. Omission adds no selector. OpenShell does not forward it. |
runtime.gatewayNodeSelector |
string map | Optional | Required for dedicated real Gateways, including their state initializer. Use separate trusted and tenant node pools. |
runtime.nativeOpenClawSessionCapacity |
integer | Optional | 1–1024, default 8 retained native session workers per AgentRevision Sandbox. |
runtime.codexSeccompProfile |
string | Optional | Relative localhost profile installed on every eligible node. Omission uses RuntimeDefault. |
runtime.modelProvider |
object | Optional | Default OpenAI-compatible provider for new revisions. Requires protocol and baseUrl; see model providers. |
runtime.channels |
object | Optional | Requires proxyUrl; optional managedProxy has hostname, namespace, podLabels, and port. No channel proxy by default. See channel egress. |
runtime.scratchVolumes |
object array | Optional | Exclusive per-Agent bindings to existing scratch PVCs. Omission adds no scratch mount; see scratch volumes. |
Stopping a hosted native session releases its slot; saved history does not consume capacity. OpenClaw does not retire idle paired-node workers, so size capacity against workload CPU and memory limits. See workload capacity checks before relying on totals reported inside the Sandbox.
Revision model settings own endpoint selection and validation. Credential Sources retain separate destination authorization. Only the Harness receives its key. For dedicated Codex, transport uses the authenticated app server and fail-closed HTTP; see Harness execution.
Scratch volumes
runtime.scratchVolumes selects existing, operator-owned filesystem PVCs for
dedicated Codex or OpenClaw Harnesses provisioned by OpenShell. Each entry requires
namespaceId and agentId (OCE IDs), namespace (the resolved execution Kubernetes
namespace), claimName, and claimUid. Each Agent and each namespace/claim pair
may appear only once in the configuration. The operator must reserve the claim
for that Agent while any retained revision can use it. The claim must be separate
from OCE's workspace and Gateway claims. Fields use nonempty visible ASCII without whitespace,
at most 253 characters each; namespace must be a Kubernetes DNS label and
claimName a DNS subdomain. The combined saved Compute admission must fit 1,024
characters.
Admission freezes the selected binding in the Agent revision. Changing or removing
the Installation entry affects new revisions only; revisions without a selection
do not inherit one later. Preparation and activation reread the claim, rejecting
missing, replaced, terminating, Lost, block-mode, or nonwritable claims. Pending
claims are allowed for WaitForFirstConsumer; a successful check does not prove
scheduling, filesystem permissions, or available capacity.
The Harness mounts private subpath scratch read-write at /sandbox/scratch.
OpenShell's sandboxDataMount cannot select the scratch claim or a path that
overlaps /sandbox/scratch, including normalized aliases. It must retain separate
durable storage. Native OpenClaw preparation creates the scratch directory if
absent; an existing directory must already be owned by the preparation process
with mode 0700. The initializer does not chmod/chown existing scratch or move,
delete or rewrite sibling content. Kubernetes or the storage driver may still
change volume group ownership and modes through fsGroup; dedicate the claim to
this Agent.
Its workspace and the Gateway's state mounts stay unchanged. OCE retains the
scratch claim on revision retirement and Agent deletion; the operator owns
reclamation. Deleting its Kubernetes namespace still deletes the namespaced PVC. Native permission profiles still govern tool access. Commands must
select scratch explicitly; caches, temporary files, and workspaces are not
redirected automatically.
Follow scratch setup and verification before admitting a replacement. The stop-before-prepare limitation also applies to failed scratch checks.
Private routing
With runtime configured, dedicated Harnesses require gatewayRouting and
node enrollment. Direct gateway clients cannot satisfy this requirement.
When using private routing, omit network.gatewayClients;
Compute derives the Envoy peer. See private routes
for deployment and authentication requirements.
| Setting | Type | Requirement | Value, default, and constraints |
|---|---|---|---|
gatewayRouting.gatewayName |
string | Required | Existing Gateway name. |
gatewayRouting.gatewayNamespace |
string | Required | Namespace containing the Gateway. |
gatewayRouting.envoyNamespace |
string | Required | Namespace containing the Envoy proxy. |
gatewayRouting.hostname |
string | Optional | DNS hostname without port/path. Omission derives an internal hostname from Gateway identity; two-cluster execution requires an explicit hostname. |
gatewayRouting.endpointPort |
integer | Optional | External endpoint port, 1–65535; default 443. |
gatewayRouting.envoyHttpsTargetPort |
integer | Optional | Envoy target port, 1–65535; default 10443. |
gatewayRouting.sandbox |
object | Optional | Requires domain; publicPort defaults to 443. Requires runtime and a valid, unreserved gateway port plus one. No sandbox route by default. |
Experimental execution cluster
Omit executionCluster for a single cluster. Two-cluster execution requires
runtime and an explicit control-plane routing hostname. Diagnostics identify /executionCluster/... fields, including
/executionCluster/caBundle. This profile still needs complete runtime acceptance.
| Setting | Type | Requirement | Value, default, and constraints |
|---|---|---|---|
executionCluster.authentication |
object | Required | mode: kubeconfig with its own explicit kubeconfigPath and context. |
executionCluster.harnessRouting |
object | Required | hostname, gatewayName, gatewayNamespace, envoyNamespace; optional envoyHttpsTargetPort defaults to 10443. |
executionCluster.network.dns |
peer | Required | Execution-cluster DNS selector. |
executionCluster.network.harnessEndpointCidrs |
string array | Required | Explicit nonempty Harness endpoint ranges. |
executionCluster.network.gatewayEndpointCidrs |
string array | Required | Explicit nonempty Gateway endpoint ranges. |
executionCluster.network.pluginStatusProxySourceCidrs |
string array | Required | Explicit nonempty Pod-proxy source ranges. |
executionCluster.caBundle |
string | Optional | Up to 65,536 characters of X.509 PEM certificates and whitespace. Omission uses default trust. |
Example
This example uses direct gateway clients and supports only embedded Harnesses. Replace the illustrative image digests, StorageClass, node labels, and proxy source CIDR with verified values for your cluster:
drivers: compute: id: compute-kubernetes configuration: authentication: mode: inCluster images: gateway: registry.example/openclaw-gateway@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa agent: registry.example/openclaw-codex@sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb requireImmutableDigest: true resources: gateway: requests: { cpu: 100m, memory: 2560Mi } limits: { cpu: "4", memory: 4Gi } agent: requests: { cpu: 100m, memory: 768Mi } limits: { cpu: "4", memory: 6Gi } namespace: quota: { pods: "10" } containerDefaults: requests: { cpu: 100m, memory: 128Mi } limits: { cpu: "4", memory: 256Mi } network: dns: namespace: kube-system podLabels: { k8s-app: kube-dns } gatewayPort: 8080 # Replace with verified source CIDRs for your authenticated proxy. gatewayTrustedProxyCidrs: ["<actual-proxy-source-cidr>"] gatewayClients: - namespace: openclaw-system podLabels: { app: approved-gateway-client } servicePrincipalCredentials: mode: projectedServiceAccountToken audience: openclaw-enterprise expirationSeconds: 900 runtime: gatewayStorageClassName: sqlite-block nativeOpenClawSessionCapacity: 8 nodeSelector: { oce-role: agents } gatewayNodeSelector: { oce-role: control-plane } transportSecretPrefix: openclaw-agent-transport # Optional; first install this reviewed profile on every eligible node. codexSeccompProfile: profiles/codex-0.160.0.jsonThe complete Installation example adds the other required Drivers and settings.