Description
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: align driver ownership of gateway callback listeners #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.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
TaylorMutch commentedon Jun 26, 2026
Implementation Plan
Issue type:
refactorComplexity: 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 bothsandbox_namespaceandservice_account_name; otherwise leave the bootstrap path disabled without requiring or validating an unrelated Kubernetes driver table.Scope
crates/openshell-server/src/lib.rs: replacekubernetes_config_for_k8s_sa_bootstrapwith 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: renderservice_account_nameat gateway scope so Helm output reflects gateway ownership while preserving the existing Kubernetes driver value for compatibility.docs/reference/gateway-config.mdx: document thatsandbox_namespaceandservice_account_namealso 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
K8sSaBootstrapConfigwithnamespaceandservice_account_name, plus a resolver that accepts the selected driver kind and the loadedConfigFile.kubernetes, resolve from the merged Kubernetes driver config to preserve existing deployments and inherited gateway defaults.[openshell.gateway].sandbox_namespaceand[openshell.gateway].service_account_name; if neither is set, return disabled; if only one is set, return a config error.K8sServiceAccountAuthenticatorwhen it returns a config.Test Plan
crates/openshell-server/src/lib.rsfor 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].Risks & Open Questions
service_account_nameavoids schema churn, but human review should confirm that a dedicated[openshell.gateway.k8s_sa_bootstrap]table is not preferred for long-term clarity./proc, binary execution, or inter-process visibility.Documentation Impact
docs/reference/gateway-config.mdx,docs/reference/sandbox-compute-drivers.mdx, andarchitecture/gateway.md.docs/index.ymlnavigation change expected.Revision 1 — initial plan
elezar commentedon Jul 7, 2026
The build plan's activation model needs adjustment before implementation proceeds.
Problem with the current plan
The proposed activation condition — enable bootstrap when both
sandbox_namespaceandservice_account_nameare explicitly set — infers intent from config presence rather than expressing it directly. These fields already exist as gateway-level inheritance defaults for the K8s driver; repurposing them as bootstrap activation signals would be subtle and surprising.More fundamentally: bootstrap is a K8s API operation (TokenReview, Pod lookup, Sandbox CR resolution). It only makes sense when sandboxes are K8s pods. The natural gate is driver selection, not config presence.
Revised direction
Bootstrap activation should be owned by driver selection:
KUBERNETES_SERVICE_HOSTset) +gateway_jwtconfigured → bootstrap enabled, namespace and service account sourced from the already-resolved K8s driver configThis also eliminates
kubernetes_config_for_k8s_sa_bootstrap— it exists solely because the bootstrap block currently does a second independent parse of[openshell.drivers.kubernetes]. Once the bootstrap block is gated on K8s driver selection, it can read from the driver config that was already resolved during startup.Revised Definition of Done
gateway_jwtis configuredkubernetes_config_for_k8s_sa_bootstrap; source namespace and service account from the already-resolved K8s driver configgateway_jwt→ bootstrap enabled; K8s selected + not in-cluster → skipped; named remote + in-cluster +gateway_jwt→ skipped without errordocs/reference/gateway-config.mdxanddocs/reference/sandbox-compute-drivers.mdxto document that bootstrap is gated on Kubernetes driver selectionarchitecture/gateway.mdto reflect the corrected activation modelThe open question about a
[openshell.gateway.k8s_sa_bootstrap]sub-table is explicitly out of scope — close it as deferred.github-actions commentedon Jul 22, 2026
This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.
grs commentedon Jul 24, 2026
I believe #2460 (still in draft) would address the issue by only enabling the kubernetes bootstrap when that is used as the compute driver:
github-actions commentedon Aug 28, 2026
This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.
jiripetrlik commentedon Sep 16, 2026
/assign
drew commentedon Sep 19, 2026
This is complete
drew commentedon Sep 19, 2026
Closure evidence: #2968 moved Kubernetes sandbox bootstrap authentication behind the selected compute driver. Kubernetes TokenReview, namespace, pod UID, and Sandbox-owner validation now live in the Kubernetes driver, so a selected remote driver no longer implicitly depends on
[openshell.drivers.kubernetes]bootstrap configuration.