Skip to content

Commit e6a35c7

Browse files
committed
docs(rfc): clarify driver config scope
Signed-off-by: Evan Lezar <[email protected]>
1 parent 9ec6a42 commit e6a35c7

1 file changed

Lines changed: 71 additions & 6 deletions

File tree

‎rfc/0005-driver-config-passthrough/README.md‎

Lines changed: 71 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ constraints for its own config block. The gateway owns only the stable envelope,
2121
driver selection, and the separation between caller-provided `driver_config` and
2222
gateway-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
2626
representative Kubernetes use cases, such as pod scheduling controls, container
2727
resources, sidecar resources, and extended resources, before defining the first
2828
documented Kubernetes config shape.
@@ -60,6 +60,10 @@ not need first-class public API fields for each of those options.
6060
OpenShell needs a caller-provided, driver-owned configuration path that is
6161
distinct 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
168176
capability flag before forwarding a matching config block. Whether drivers
169177
should 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

173205
The 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

308348
The first step should collect a representative set of Kubernetes
309349
driver-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

361402
This 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+
363413
The Kubernetes driver should prefer raw Kubernetes resource names and
364414
Kubernetes quantity strings where it exposes Kubernetes resource requests and
365415
limits. 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
476526
schema discovery RPC or capability field can be added later without changing the
477527
core `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

481546
The passthrough could allow arbitrary platform-native fields, including secret

0 commit comments

Comments
 (0)