refactor(server): decouple K8s ServiceAccount bootstrap from selected compute driver config

[elezar]

Description

K8s ServiceAccount bootstrap currently derives its namespace and service-account settings from [openshell.drivers.kubernetes] whenever the gateway has gateway_jwt configured and detects that it is running in-cluster.

That assumes the Kubernetes compute driver is the source of sandbox bootstrap identity configuration. With named remote compute drivers, an in-cluster gateway may select a non-Kubernetes driver but still hit the bootstrap path and require [openshell.drivers.kubernetes].

Context

PR #1974 normalizes selected compute-driver config acquisition so unselected driver tables are no longer validated during startup. That makes the ServiceAccount bootstrap path stand out as a separate consumer of Kubernetes driver config, outside the selected driver acquisition flow.

Related issues:

• refactor(server): normalize compute driver acquisition path #1949 normalized compute driver acquisition.
• refactor: make sandbox readiness gateway-owned across compute drivers #1951 tracks gateway-owned readiness across drivers.
• refactor: make sandbox callback listeners gateway-owned #1952 tracks gateway-owned callback listeners.

Proposed Direction

Make K8s ServiceAccount bootstrap configuration explicit and independent from the selected compute driver, or only enable the current Kubernetes-driver-derived bootstrap behavior when Kubernetes is the selected driver.

The implementation should decide how an in-cluster gateway using a named remote driver configures or disables ServiceAccount bootstrap without requiring an unrelated [openshell.drivers.kubernetes] table.

Definition of Done

• Define the ownership model for ServiceAccount bootstrap namespace and service-account settings.
• Avoid requiring [openshell.drivers.kubernetes] when the selected compute driver is a named remote driver.
• Preserve current Kubernetes-driver behavior for in-cluster gateways that rely on ServiceAccount bootstrap.
• Add tests for Kubernetes selected, remote driver selected in-cluster with bootstrap enabled, and remote driver selected with bootstrap disabled or explicitly configured.
• Update gateway configuration documentation if new config fields are introduced.

[TaylorMutch]

🏗️ build-plan

Implementation Plan

Issue type: refactor
Complexity: Medium
Confidence: High — clear path; the main design choice is to reuse existing gateway-level fields instead of adding a new TOML table.

Summary

Decouple K8s ServiceAccount bootstrap from [openshell.drivers.kubernetes] by resolving the bootstrap namespace and service account from gateway-owned configuration. Preserve current Kubernetes-driver behavior by falling back to the selected Kubernetes driver config when the Kubernetes driver is selected. For named remote drivers, enable ServiceAccount bootstrap only when [openshell.gateway] explicitly supplies both sandbox_namespace and service_account_name; otherwise leave the bootstrap path disabled without requiring or validating an unrelated Kubernetes driver table.

Scope

• crates/openshell-server/src/lib.rs: replace kubernetes_config_for_k8s_sa_bootstrap with a small bootstrap-config resolver that takes the selected compute driver and returns either explicit bootstrap config or disabled state.
• crates/openshell-server/src/config_file.rs: no schema changes expected; add or adjust tests only if the resolver needs additional helper access to existing gateway fields.
• deploy/helm/openshell/templates/gateway-config.yaml: render service_account_name at gateway scope so Helm output reflects gateway ownership while preserving the existing Kubernetes driver value for compatibility.
• docs/reference/gateway-config.mdx: document that sandbox_namespace and service_account_name also control K8s ServiceAccount bootstrap when the gateway is in-cluster with sandbox JWT issuing enabled.
• docs/reference/sandbox-compute-drivers.mdx: clarify Kubernetes fallback behavior and named remote driver bootstrap requirements.
• architecture/gateway.md: update the authentication overview to describe the gateway-owned bootstrap identity check.

Implementation Steps

1. Introduce an internal K8sSaBootstrapConfig with namespace and service_account_name, plus a resolver that accepts the selected driver kind and the loaded ConfigFile.
2. For selected kubernetes, resolve from the merged Kubernetes driver config to preserve existing deployments and inherited gateway defaults.
3. For named remote drivers, resolve only from explicit [openshell.gateway].sandbox_namespace and [openshell.gateway].service_account_name; if neither is set, return disabled; if only one is set, return a config error.
4. Keep Docker, Podman, and VM gateways from implicitly enabling this bootstrap path unless a future issue explicitly defines that behavior.
5. Update gateway startup to call the resolver after compute-driver selection and only construct K8sServiceAccountAuthenticator when it returns a config.
6. Update Helm rendering and docs to make the ownership model visible.
7. Run focused unit tests, then the repository pre-commit lane before committing.

Test Plan

• Unit tests: Add resolver tests in crates/openshell-server/src/lib.rs for Kubernetes selected, named remote selected with explicit bootstrap config, named remote selected with bootstrap disabled, and named remote selected with partial bootstrap config rejected. Include a regression case showing a named remote selection does not require [openshell.drivers.kubernetes].
• Integration tests: N/A — the change is startup config resolution and authenticator wiring; no live Kubernetes API is needed for the resolver behavior.
• E2E tests: N/A unless implementation touches Helm/E2E fixtures. This is not expected to require a sandbox e2e lane.

Risks & Open Questions

• Reusing the existing gateway-level service_account_name avoids schema churn, but human review should confirm that a dedicated [openshell.gateway.k8s_sa_bootstrap] table is not preferred for long-term clarity.
• Named remote drivers that rely on this bootstrap path must create sandbox pods using the same namespace and service account configured on the gateway.
• LSM compatibility impact is not expected; the change does not touch process identity, /proc, binary execution, or inter-process visibility.

Documentation Impact

• Update docs/reference/gateway-config.mdx, docs/reference/sandbox-compute-drivers.mdx, and architecture/gateway.md.
• No docs/index.yml navigation change expected.
• No gateway TOML schema field is added, but existing fields gain clarified behavior.

---

Revision 1 — initial plan