Kubernetes

Kubernetes Sandbox Topology

View as Markdown

Kubernetes sandbox pods run the OpenShell supervisor in combined topology by default. Combined topology keeps network, filesystem, and process controls in the agent pod so the supervisor can enforce the complete OpenShell sandbox contract before launching the workload.

Choose a Topology

The default combined topology preserves the full OpenShell enforcement model. Use it when you need OpenShell to apply all sandbox controls inside the workload pod and your cluster policy permits the required Linux capabilities.

TopologyUse whenMain tradeoff
combinedYou need OpenShell network, filesystem, and process controls in the sandbox workload.The agent container carries the Linux capabilities the supervisor needs.

Additional Kubernetes sandbox topologies are still being designed. Until they are documented as supported configuration values, combined is the only supported value for supervisor.topology.

Privilege Model

The long-running container permissions for combined topology are:

TopologyPod or containerUID/GIDPrivilege escalationCapabilitiesResult
combinedAgent container, which also runs the supervisorNot forced by topologyNot explicitly disabled by the driverAdds SYS_ADMIN, NET_ADMIN, SYS_PTRACE, and SYSLOG; adds SETUID, SETGID, and DAC_READ_SEARCH when user namespaces are enabledFull supervisor controls run in the agent container.

Short-lived setup containers still have the permissions needed to prepare the pod:

TopologySetup containerUID/GIDPrivilege escalationCapabilitiesPurpose
combinedSupervisor install init container0Not setNot setCopies the supervisor binary into the agent container volume.

Combined Topology

Combined topology is the original Kubernetes mode and remains the default. The agent container starts the OpenShell supervisor, and the supervisor launches the workload after applying sandbox setup.

Combined topology keeps these controls in one supervisor path:

  • Network endpoint and L7 policy enforcement.
  • Filesystem policy enforcement.
  • Process and binary identity checks.
  • Privilege drop into the sandbox user.
  • Gateway relay, SSH sessions, exec, and file sync.

Because the supervisor performs network namespace setup and process/filesystem controls from the agent container, Kubernetes grants that container elevated Linux capabilities. Use this mode when you need the complete OpenShell sandbox contract and your cluster policy permits those capabilities.

RuntimeClass Isolation

RuntimeClass isolation can add a stronger container boundary for the sandbox workload when the cluster supports it. Runtime classes do not replace the combined topology’s supervisor controls; they add another isolation boundary around the same supervised workload.

You can set a default runtime class in the Kubernetes driver configuration or override it per sandbox with driver config:

$openshell sandbox create \
>  --driver-config-json '{"kubernetes":{"pod":{"runtime_class_name":"kata-containers"}}}' \
>  -- claude

Configure Combined Mode

For direct gateway TOML configuration, leave supervisor_topology unset, or set it to combined, to use the default single-container supervisor path:

1[openshell.drivers.kubernetes]
2supervisor_topology = "combined"

When the Helm chart renders gateway.toml, leave supervisor.topology unset, or set it to combined, to produce the same driver configuration:

1supervisor:
2  topology: combined

Next Steps