Secure, Fast, and Extensible Sandbox runtime for AI agents.
feat(templates): bake EXECD_INIT into fsb golden images when runtime.execd_run_as_init is set
高然df5c120cf210
diff --git a/docs/architecture/fast-sandbox/templates.md b/docs/architecture/fast-sandbox/templates.mdindex 6a57b7f4d..c6f73af60 100644--- a/docs/architecture/fast-sandbox/templates.md+++ b/docs/architecture/fast-sandbox/templates.md@@ -20,7 +20,7 @@ Builds are asynchronous by design: the API returns an accepted state immediatelyA `SandboxTemplate` describes a conversion, not just a copy: an ordinary OCI image plus the OpenSandbox guest wiring, compiled into an immutable golden image.-- **Guest wiring is injected**: an init path (PID 1, carrying the readiness marker and heartbeat) and the execd runtime files always come from the template — every sandbox built from it is execd-ready by construction.+- **Guest wiring is injected**: an init path (PID 1, carrying the readiness marker and heartbeat) and the execd runtime files always come from the template — every sandbox built from it is execd-ready by construction. With the server's `runtime.execd_run_as_init` enabled, the server bakes `EXECD_INIT=1` into the template envs, so the baked `bootstrap.sh` execs into `execd --init` and execd becomes the root of the workload tree as a subreaper under the guest init (child reaping, signal forwarding, and the optional hardening floor; the PID 1 signal shield stays with the guest init).- **Business entrypoint and envs** are baked in: an empty entrypoint defaults to a keep-alive; envs are injected literally into the guest (no runtime indirection).- **Runtime shape is declared**: the template names the Firecracker guest kernel and reference machine; readiness defines when the guest counts as up.- **Output is content-addressed**: the build publishes artifacts to the store and records a manifest reference plus artifact digest in the CR status — builds are immutable and verifiable, never mutated in place.diff --git a/server/configuration.md b/server/configuration.mdindex b5540dcb9..fb90185e8 100644--- a/server/configuration.md+++ b/server/configuration.md@@ -99,7 +99,7 @@ Example files: [`example.config.toml`](opensandbox_server/examples/example.confi|-----|------|---------|-------------|| `type` | string | — | **`docker`** or **`kubernetes`**. || `execd_image` | string | — | OCI image containing the **execd** binary (in-sandbox bootstrap). |-| `execd_run_as_init` | boolean | `false` | Run execd as sandbox init (OSEP-0018): execd becomes PID 1 (child reaping, container lifecycle, hardening floor). |+| `execd_run_as_init` | boolean | `false` | Run execd as sandbox init (OSEP-0018): execd becomes PID 1 (child reaping, container lifecycle, hardening floor). fsb template builds bake `EXECD_INIT=1` into the golden image instead: execd runs as a subreaper under the fsb guest init, so reaping, signal forwarding, and the hardening floor still apply but the PID 1 signal shield does not. |---diff --git a/server/opensandbox_server/services/templates/template_service.py b/server/opensandbox_server/services/templates/template_service.pyindex 77d64d7aa..058d3c22a 100644--- a/server/opensandbox_server/services/templates/template_service.py+++ b/server/opensandbox_server/services/templates/template_service.py@@ -61,6 +61,14 @@ PLURAL = "sandboxtemplates"# exist in the sandboxtemplate-builder image under this name (builder# default); execd comes from runtime.execd_image.TEMPLATE_KERNEL = "vmlinux.bin"+# OSEP-0018 on fsb: the golden image's guest init sources the baked envs and+# launches /opt/opensandbox/bootstrap.sh, so a baked EXECD_INIT=1 makes+# bootstrap.sh exec into `execd --init` and execd becomes the root of the+# workload tree — a subreaper, since the fsb guest init stays PID 1 (no+# PID 1 signal shield, same tier as the Kubernetes Pool path). Injected at+# CRD projection from runtime.execd_run_as_init; the server value wins over+# a client-provided env of the same name.+EXECD_INIT_ENV = "EXECD_INIT"DEFAULT_VCPU = "1"DEFAULT_MEMORY = "512Mi"# Guest rootfs logical size when the client omits resourceLimits.disk. The@@ -163,6 +171,7 @@ class FastSandboxTemplateService:):self._config = configself._execd_image = config.runtime.execd_image+ self._execd_run_as_init = bool(config.runtime.execd_run_as_init)self._repository = repositoryself._k8s_client = k8s_clientself._k8s_config = config.kubernetes or KubernetesRuntimeConfig()@@ -517,6 +526,10 @@ class FastSandboxTemplateService:},}env = record.spec.get("env") or {}+ if self._execd_run_as_init:+ # Copy first: the stored row keeps the client env untouched, and+ # the server value wins over a client-provided EXECD_INIT.+ env = {**env, EXECD_INIT_ENV: "1"}if env:spec["envs"] = [{"name": name, "value": value} for name, value in env.items()]# OSEP-0022 CA wiring: bake the pinned MITM CA Secret's certificatediff --git a/server/tests/test_templates.py b/server/tests/test_templates.pyindex 33ef6a237..80eb5b953 100644--- a/server/tests/test_templates.py+++ b/server/tests/test_templates.py@@ -399,6 +399,42 @@ def test_create_projects_env_to_crd(service, crs):assert "envs" not in crs.created[-1]["spec"]+def execd_init_service(repo, crs, monkeypatch):+ monkeypatch.setattr(WorkloadInformer, "start", lambda self: None)+ with patch.object(K8sClient, "_load_config"):+ k8s = K8sClient(KubernetesRuntimeConfig())+ crs.install(k8s)+ config = _config()+ config.runtime.execd_run_as_init = True+ svc = FastSandboxTemplateService(config, repository=repo, k8s_client=k8s)+ yield svc+ svc.close()+++def test_create_injects_execd_init_env_when_enabled(execd_init_service, crs):+ # A client-provided EXECD_INIT must not win over the server switch.+ record = execd_init_service.create_template(+ _create_request(env={"EXECD_INIT": "0", "LOG_LEVEL": "info"})+ )+ envs = {e["name"]: e["value"] for e in crs.created[-1]["spec"]["envs"]}+ assert envs == {"EXECD_INIT": "1", "LOG_LEVEL": "info"}+ # The stored row keeps the client env; injection is projection-only.+ assert record.spec["env"] == {"EXECD_INIT": "0", "LOG_LEVEL": "info"}++ execd_init_service.create_template(_create_request())+ assert crs.created[-1]["spec"]["envs"] == [{"name": "EXECD_INIT", "value": "1"}]+++def test_create_does_not_inject_execd_init_by_default(service, crs):+ service.create_template(_create_request(env={"LOG_LEVEL": "info"}))+ envs = {e["name"]: e["value"] for e in crs.created[-1]["spec"]["envs"]}+ assert envs == {"LOG_LEVEL": "info"}++ service.create_template(_create_request())+ assert "envs" not in crs.created[-1]["spec"]++def test_create_rejects_invalid_env_names(service):from fastapi import HTTPException