@@ -21,8 +21,8 @@ constraints for its own config block. The gateway owns only the stable envelope,
2121driver selection, and the separation between caller-provided ` driver_config ` and
2222gateway-computed ` platform_config ` .
2323
24- Kubernetes is the first driver used to inform the nested config shape. The RFC
25- does not finalize every Kubernetes key up front. Instead, it requires collecting
24+ Kubernetes is a primary proving driver for the nested config shape. The RFC does
25+ not finalize every Kubernetes key up front. Instead, it requires collecting
2626representative Kubernetes use cases, such as pod scheduling controls, container
2727resources, sidecar resources, and extended resources, before defining the first
2828documented Kubernetes config shape.
@@ -60,6 +60,10 @@ not need first-class public API fields for each of those options.
6060OpenShell needs a caller-provided, driver-owned configuration path that is
6161distinct from the existing gateway-computed ` platform_config ` .
6262
63+ This RFC scopes that path to sandbox compute drivers because sandbox creation
64+ already has a clear driver selection step, a ` DriverSandboxTemplate ` handoff,
65+ and driver-owned validation before any platform resource is created.
66+
6367## Non-goals
6468
6569- Do not add first-class support for any specific GPU stack.
@@ -72,6 +76,10 @@ distinct from the existing gateway-computed `platform_config`.
7276- Do not apply wildcard matching to driver config keys.
7377- Do not make ` driver_config ` a dynamic update mechanism for existing
7478 sandboxes.
79+ - Do not define a generic extension mechanism for every top-level OpenShell
80+ resource. Provider secrets, gateways, policies, and other resources may need
81+ analogous extension points, but each should be designed around its own owner,
82+ lifecycle, authorization, and security invariants.
7583
7684## Proposal
7785
@@ -168,6 +176,30 @@ For the initial implementation, the gateway does not need a separate driver
168176capability flag before forwarding a matching config block. Whether drivers
169177should advertise support for ` driver_config ` is an open question.
170178
179+ ### Scope boundary
180+
181+ ` driver_config ` is attached to sandbox creation requests because a sandbox has a
182+ single selected compute driver and a direct gateway-to-driver handoff. The
183+ selected compute driver can validate the nested config before it creates or
184+ modifies any underlying platform resources.
185+
186+ Other top-level OpenShell resources may also be backed by subsystem-specific or
187+ platform-specific implementations, but they do not automatically share the same
188+ ownership boundary. For example, provider secret handling involves credential
189+ lifecycle and access-control rules rather than pod/container scheduling rules.
190+ Those resources should not reuse ` SandboxTemplate.driver_config ` or the compute
191+ driver key space by implication.
192+
193+ If another resource needs a passthrough mechanism later, it should get a
194+ resource-specific design that answers:
195+
196+ - which component owns the nested schema and validation;
197+ - which stable envelope identifies that owner;
198+ - whether the config is create-time only or updateable;
199+ - which fields are protected by the control plane; and
200+ - how authorization, secret handling, auditing, and compatibility work for that
201+ resource.
202+
171203### Driver validation
172204
173205The selected driver validates the nested config it receives:
@@ -301,14 +333,23 @@ the API design should not preclude adding it later.
301333
302334### Initial Kubernetes driver use cases
303335
304- Kubernetes should be the first driver used to inform the nested ` driver_config `
305- shape, but the nested Kubernetes schema should not be finalized from a single
306- GPU resource example.
336+ Kubernetes should be a primary driver used to inform the nested ` driver_config `
337+ shape. For all drivers, the following constraints should guide the nested shape:
338+
339+ - ` driver_config ` must not bypass or override first-class resource requests
340+ exposed by the public API, such as typed GPU, CPU, and memory fields.
341+ - Driver-specific resource config is still in scope when it represents
342+ driver-owned detail, such as sidecar resource sizing, extended resources, or
343+ platform-specific resource controls that the public API does not model.
344+ - API design should be informed by more than non-standard resource requests.
345+ For Kubernetes, it should answer: which Kubernetes-specific properties could
346+ a user want to set?
307347
308348The first step should collect a representative set of Kubernetes
309349driver-specific use cases, including:
310350
311- - container resource requests and limits for the primary sandbox container;
351+ - additional container resource requests and limits for the primary sandbox
352+ container that the public API does not model;
312353- resource requests and limits for driver-owned sidecars such as a proxy
313354 container;
314355- extended resources used by installed GPU stacks;
@@ -360,6 +401,15 @@ include a Kubernetes-native pod/container structure:
360401
361402This example is illustrative, not the final required schema.
362403
404+ Note that the top-level ` "kubernetes" ` key represents a concrete driver name.
405+ This is important because it defines which driver is responsible for validating
406+ and interpreting the spec. This also allows multiple drivers to be supported --
407+ but not required -- in the future.
408+
409+ Furthermore, keying the config by driver name and using a generic message
410+ payload allows out-of-tree drivers to be supported in the future without
411+ requiring coordinated deployment of gateway updates.
412+
363413The Kubernetes driver should prefer raw Kubernetes resource names and
364414Kubernetes quantity strings where it exposes Kubernetes resource requests and
365415limits. It should not introduce OpenShell-owned aliases such as ` gpu_memory_mb `
@@ -476,6 +526,21 @@ driver-side validation is sufficient for the initial passthrough mechanism. A
476526schema discovery RPC or capability field can be added later without changing the
477527core ` driver_config ` contract.
478528
529+ ### Generic passthrough for all top-level resources
530+
531+ Every top-level OpenShell resource could receive a similarly shaped
532+ implementation-owned config block.
533+
534+ This might make the model feel consistent across APIs, but it would obscure the
535+ owner and validation boundary. Sandbox compute drivers have a concrete selected
536+ driver and a creation-time driver template. Other resources may be owned by the
537+ gateway, provider backends, policy engines, identity systems, or external
538+ platform components. Their extension points need separate lifecycle,
539+ authorization, secret-handling, audit, and compatibility rules.
540+
541+ This RFC should not block analogous resource-specific designs, but it should not
542+ turn the sandbox compute-driver mechanism into a global extension contract.
543+
479544### Allow secrets or privileged platform controls
480545
481546The passthrough could allow arbitrary platform-native fields, including secret
0 commit comments