Secure, Fast, and Extensible Sandbox runtime for AI agents.
docs: trim comments across the overlaybd PR to the load-bearing parts
高然4a4a459037be
diff --git a/.github/workflows/fast-sandbox-test.yml b/.github/workflows/fast-sandbox-test.ymlindex 5a3b75df2..f8ad406ad 100644--- a/.github/workflows/fast-sandbox-test.yml+++ b/.github/workflows/fast-sandbox-test.yml@@ -34,9 +34,7 @@ jobs:needs: changesif: needs.changes.outputs.relevant == 'true'runs-on: kvm- # The verify matrix runs twice when OCI_STACK=1 (default): once native,- # once against the overlaybd template (on-demand boot path), plus two- # golden-image builds.+ # The verify matrix runs twice when OCI_STACK=1 (native + overlaybd).timeout-minutes: 240env:# Full-stack profile (single round while scenarios stabilize).@@ -83,9 +81,7 @@ jobs:run: sudo -E env "PATH=$PATH" ./scripts/fast-sandbox-env/integration-env.sh up --auto-clean- name: Run base SDK e2e- # The suite runs once per template (native + overlaybd when- # OCI_STACK=1), so the step needs roughly double the single-pass- # budget.+ # Runs once per template (native + overlaybd).timeout-minutes: 60run: sudo -E env "PATH=$PATH" ./scripts/fast-sandbox-env/integration-env.sh sdk-e2ediff --git a/manifests/charts/fast-sandbox/README.md b/manifests/charts/fast-sandbox/README.mdindex 95e44eed7..5947e9e85 100644--- a/manifests/charts/fast-sandbox/README.md+++ b/manifests/charts/fast-sandbox/README.md@@ -85,8 +85,8 @@ The following table lists the configurable parameters of the chart and their def| runtime.image.repository | string | `"opensandbox/fsb-firecracker-runtime"` | Runtime image repository (built by manifests/release/build-fast-sandbox.sh) || runtime.image.tag | string | `""` | Image tag. Empty uses the release-<appVersion> companion image tag. || runtime.nodeSelector | object | `{}` | Node selector. Empty by default: the runtime applies the firecracker scheduling labels itself, so it must run on every candidate node. Pin it with your own coarse selector only if the cluster hosts unrelated node pools. |-| runtime.oci | object | `{"cacheSizeGB":16,"enabled":false}` | OverlayBD OCI on-demand loading (fast-sandbox PR #127 contract). Enabling installs the fsb-vm + OverlayBD tools bundle under /opt/fast-sandbox/oci (init container), sets FAST_SANDBOX_OCI_ENABLED on the agent (relaxing the XFS/reflink readiness requirement), and runs one overlaybd-ublkd sidecar per node serving the shared ublk daemon socket. Nodes need KVM plus kernel ublk support (CONFIG_BLK_DEV_UBLK, /dev/ublkc*). The SandboxPool's fastlet containers need FAST_SANDBOX_OCI_ENABLED=true separately — pools are not managed by this chart. |-| runtime.oci.cacheSizeGB | int | `16` | Node cache capacity for the shared overlaybd block cache (OVERLAYBD_CACHE_SIZE_GB); independent of VM upper layers. |+| runtime.oci | object | `{"cacheSizeGB":16,"enabled":false}` | OverlayBD OCI on-demand loading: installs the fsb-vm + OverlayBD tools bundle (init container), sets FAST_SANDBOX_OCI_ENABLED on the agent, and runs one overlaybd-ublkd sidecar per node. Nodes need KVM plus kernel ublk support. Pool fastlets set the flag separately (pools are not managed by this chart). |+| runtime.oci.cacheSizeGB | int | `16` | Shared overlaybd block cache capacity (OVERLAYBD_CACHE_SIZE_GB). || runtime.oci.enabled | bool | `false` | Whether the node OCI stack (tools init + overlaybd-ublkd sidecar + agent flag + janitor oci-state-root) is installed || runtime.registrySecret | string | `"fast-sandbox-agent-registry"` | Secret carrying the compiled agent registry configuration (registry.json key with artifact-store pull credentials); must be provisioned by the operator. || runtime.resources | object | `{"agent":{},"janitor":{},"ublkd":{}}` | Container resources for the DaemonSet. Setting requests matters more than limits here: without them the pod is BestEffort and is evicted first under node pressure, taking down the management API for every fastlet on the node. Limits stay off by default so artifact pulls and the readiness loop are not throttled or OOM-killed at their spikes. |diff --git a/manifests/charts/fast-sandbox/templates/runtime-daemonset.yaml b/manifests/charts/fast-sandbox/templates/runtime-daemonset.yamlindex b457170b3..33aa85fac 100644--- a/manifests/charts/fast-sandbox/templates/runtime-daemonset.yaml+++ b/manifests/charts/fast-sandbox/templates/runtime-daemonset.yaml@@ -185,9 +185,8 @@ spec:# child needs the cluster DNS to resolve the headless Service peers,# and a regular Pod identity for the stable HRW node hostname file.{{- if .Values.runtime.oci.enabled }}- # OCI tools bundle (fsb-vm, OverlayBD tools, convertor) installed- # once under the shared node hostPath; the agent, the overlaybd-ublkd- # sidecar, the janitor and Fastlet Pods all consume it read-only.+ # Installs the OCI tools bundle under the shared node hostPath;+ # agent, overlaybd-ublkd, janitor and Fastlet Pods consume it read-only.initContainers:- name: install-oci-toolsimage: {{ include "fast-sandbox.image" (dict "repository" .Values.runtime.image.repository "tag" .Values.runtime.image.tag "appVersion" .Chart.AppVersion) }}@@ -203,9 +202,7 @@ spec:imagePullPolicy: {{ .Values.runtime.image.pullPolicy }}{{- if .Values.runtime.oci.enabled }}# The first host-readiness pass pings the node ublkd socket once;- # without this gate it races the sidecar's startup by a few hundred- # milliseconds, fails, and the node stays unlabeled until the next- # 5-minute recheck. Wait (bounded) for the socket, then start.+ # gate on it so the check doesn't race the sidecar's startup.command: ["/bin/sh", "-ec"]args:- |-@@ -223,8 +220,7 @@ spec:fieldRef:fieldPath: metadata.uid{{- if .Values.runtime.oci.enabled }}- # Relaxes the XFS/reflink node readiness requirement; native- # templates stay usable (rootfs copies just take longer).+ # Relaxes the XFS/reflink node readiness requirement.- name: FAST_SANDBOX_OCI_ENABLEDvalue: "true"{{- end }}@@ -291,11 +287,8 @@ spec:mountPath: /run/fast-sandbox/overlaybd{{- end }}{{- if .Values.runtime.oci.enabled }}- # One shared overlaybd-ublkd per node: hosts every sandbox's ublk- # devices behind /run/fast-sandbox/overlaybd/ublkd.sock (fsb-vm- # connects directly; the agent does not proxy device ops). Shares the- # agent's StateRoot at the same absolute path and the host /dev so- # devices created here are visible to the VMs.+ # One shared ublkd per node: fsb-vm connects directly over the socket;+ # StateRoot and host /dev must match the agent's view.- name: overlaybd-ublkdimage: {{ include "fast-sandbox.image" (dict "repository" .Values.runtime.image.repository "tag" .Values.runtime.image.tag "appVersion" .Chart.AppVersion) }}imagePullPolicy: {{ .Values.runtime.image.pullPolicy }}@@ -393,9 +386,7 @@ spec:mountPath: /etc/fast-sandbox/runtime-environmentsreadOnly: true{{- if .Values.runtime.oci.enabled }}- # fsb-vm cleanup of retained ublk devices and checkpoint pack- # resources left by deleted Pods (revalidated against Sandbox- # absence first).+ # fsb-vm cleanup of devices and checkpoint packs left by deleted Pods.- name: oci-toolsmountPath: /opt/fast-sandbox/ocireadOnly: true@@ -464,21 +455,16 @@ spec:# disabled via --containerd-socket= anyway).optional: true{{- if .Values.runtime.oci.enabled }}- # Immutable OCI tools release installed by the init container and- # atomically switched under current/; shared read-only with the- # overlaybd-ublkd sidecar, the janitor, and Fastlet Pods.- name: oci-toolshostPath:path: /opt/fast-sandbox/ocitype: DirectoryOrCreate- # Root-only ublkd control socket + credential directory shared with- # Fastlet Pods (fast-sandbox-registry ConfigMap supplies credentials).+ # Root-only ublkd control socket shared with Fastlet Pods.- name: oci-sockethostPath:path: /run/fast-sandbox/overlaybdtype: DirectoryOrCreate- # Host device tree: ublk devices created by the sidecar must be- # visible to the Firecracker VMs.+ # Host device tree: ublk devices must be visible to the VMs.- name: host-devhostPath:path: /devdiff --git a/manifests/charts/fast-sandbox/values.yaml b/manifests/charts/fast-sandbox/values.yamlindex b519505f2..50f789155 100644--- a/manifests/charts/fast-sandbox/values.yaml+++ b/manifests/charts/fast-sandbox/values.yaml@@ -234,19 +234,14 @@ runtime:# startup-only; the nodeReadiness section (fcVersion, interval,# minFree, minMemory) hot-reloads on every readiness pass.config: ""- # -- OverlayBD OCI on-demand loading (fast-sandbox PR #127 contract).- # Enabling installs the fsb-vm + OverlayBD tools bundle under- # /opt/fast-sandbox/oci (init container), sets FAST_SANDBOX_OCI_ENABLED- # on the agent (relaxing the XFS/reflink readiness requirement), and- # runs one overlaybd-ublkd sidecar per node serving the shared ublk- # daemon socket. Nodes need KVM plus kernel ublk support- # (CONFIG_BLK_DEV_UBLK, /dev/ublkc*). The SandboxPool's fastlet- # containers need FAST_SANDBOX_OCI_ENABLED=true separately — pools are- # not managed by this chart.+ # -- OverlayBD OCI on-demand loading: installs the fsb-vm + OverlayBD+ # tools bundle (init container), sets FAST_SANDBOX_OCI_ENABLED on the+ # agent, and runs one overlaybd-ublkd sidecar per node. Nodes need KVM+ # plus kernel ublk support. Pool fastlets set the flag separately+ # (pools are not managed by this chart).oci:- # -- Whether the node OCI stack (tools init + overlaybd-ublkd- # sidecar + agent flag + janitor oci-state-root) is installed+ # -- Whether the node OCI stack (tools init + overlaybd-ublkd sidecar+ # + agent flag + janitor oci-state-root) is installedenabled: false- # -- Node cache capacity for the shared overlaybd block cache- # (OVERLAYBD_CACHE_SIZE_GB); independent of VM upper layers.+ # -- Shared overlaybd block cache capacity (OVERLAYBD_CACHE_SIZE_GB).cacheSizeGB: 16diff --git a/scripts/fast-sandbox-env/README.md b/scripts/fast-sandbox-env/README.mdindex 89c48f359..d63c7d16b 100644--- a/scripts/fast-sandbox-env/README.md+++ b/scripts/fast-sandbox-env/README.md@@ -25,7 +25,7 @@ Requires a bare-metal Linux host with KVM (`/dev/kvm`), Docker, Go ≥ 1.25, cgr### OverlayBD OCI profile (default on)-`OCI_STACK` defaults to 1: the environment brings up ONE cluster where the OverlayBD on-demand loading stack runs beside native. It generates a local CA + TLS certificate, deploys an in-cluster `registry:2` (fsb-vm and overlaybd require HTTPS — there is no upstream plain-http escape hatch), bakes the CA into the `fsb-fastlet`, `fsb-firecracker-runtime` and sandboxtemplate-builder images, installs the `fast-sandbox` chart's `runtime.oci` node stack (tools init container + one `overlaybd-ublkd` sidecar per node), adds the registry credentials plus the server's `template_oci_publish_secret`, and renders the pool fastlet with `FAST_SANDBOX_OCI_ENABLED=true` plus the shared tools/socket//dev mounts. A second template (`format: overlaybd`, published `oci://` to the in-cluster registry) is built beside the native one, and a dedicated verify stage round-trips it: template-mode create (the server resolves `status.manifestRef` as the create image) → ublk on-demand boot → snapshot (OCI publication) → restore through the server's manifest_ref branch. Native templates keep working throughout (the agent skips the XFS/reflink requirement when OCI is enabled, so native rootfs copies lose reflink acceleration). Nodes need kernel ublk support (`CONFIG_BLK_DEV_UBLK`, `/dev/ublkc*`; `modprobe ublk_drv` when built as a module). `OCI_STACK=0` restores the previous native-only environment.+`OCI_STACK` defaults to 1: one cluster serves both template paths. The env generates a local CA + TLS certificate and deploys an in-cluster `registry:2` (fsb-vm and overlaybd require HTTPS), bakes the CA into the `fsb-fastlet`, `fsb-firecracker-runtime` and sandboxtemplate-builder images, installs the `fast-sandbox` chart's `runtime.oci` node stack, wires the registry credentials and the server's `template_oci_publish_secret`, and renders the pool fastlet with `FAST_SANDBOX_OCI_ENABLED=true` plus the shared tools/socket//dev mounts. An overlaybd template is built beside the native one and the whole verify matrix runs twice — once per template (on the overlaybd pass, template-mode create resolves `status.manifestRef`, boot is ublk on-demand, and snapshots publish/restore via `oci://` manifests). Nodes need kernel ublk support (`CONFIG_BLK_DEV_UBLK`; `modprobe ublk_drv` when built as a module). `OCI_STACK=0` restores the native-only environment.After `up`, point any OpenSandbox SDK at `http://127.0.0.1:18080` with the `OPEN-SANDBOX-API-KEY: fast-sandbox-env` header; sandbox endpoints are signed `f1.*` header routes served by the gateway at `http://127.0.0.1:18081`. The installed CLI works against the same stack, e.g. `OPEN_SANDBOX_DOMAIN=127.0.0.1:18080 OPEN_SANDBOX_API_KEY=fast-sandbox-env osb sandbox list`.diff --git a/scripts/fast-sandbox-env/integration-env.sh b/scripts/fast-sandbox-env/integration-env.shindex 00513745b..aa2eaf95a 100755--- a/scripts/fast-sandbox-env/integration-env.sh+++ b/scripts/fast-sandbox-env/integration-env.sh@@ -64,13 +64,10 @@# IDLE_PAUSE_PARK_BUDGET gateway wake park budget (default 5s; set e.g. 100ms to# force every wake through the marked-503 + client-retry path)# REDIS_IMAGE Redis image for the idle-pause profile (default redis:7-alpine)-# OCI_STACK OverlayBD OCI profile, default 1: in-cluster TLS registry-# (its CA is baked into the fsb images), the chart's-# runtime.oci node stack (tools init + overlaybd-ublkd-# sidecar), an overlaybd template beside the native one,-# and an overlaybd sandbox + snapshot round trip. Native-# keeps running beside it (nodes need ublk: kernel-# CONFIG_BLK_DEV_UBLK, /dev/ublkc*). 0 = native-only.+# OCI_STACK OverlayBD OCI profile, default 1: in-cluster TLS+# registry (CA baked into the fsb images), the chart's+# runtime.oci node stack, and a full overlaybd verify+# pass beside native. Nodes need ublk support. 0 = native-only.## Every stage logs to $WORK/logs/; failures dump component logs to# logs/failure-<task>-<ts>.txt before exiting (never silently).@@ -154,21 +151,11 @@ IMG_OCI_TOOLS="${IMAGE_OCI_TOOLS:-opensandbox/oci-tools:dev}"IMG_RUNTIME="${IMAGE_RUNTIME:-opensandbox/fsb-firecracker-runtime:dev}"IMG_EGRESS="${EGRESS_IMAGE:-docker.io/opensandbox/egress:latest}"-# OverlayBD OCI stack — single-cluster shape: the OCI on-demand loading-# stack runs beside native, and both template paths are verified in one-# environment. Requires node ublk support (CONFIG_BLK_DEV_UBLK;-# `modprobe ublk_drv` when built as a module). When enabled the env:-# - generates a local CA + TLS serving cert and runs an in-cluster-# registry (fsb-vm and overlaybd require HTTPS; no plain-http escape-# hatch exists upstream), baking the CA into the fsb-fastlet,-# fsb-firecracker-runtime and sandboxtemplate-builder images;-# - installs the chart's runtime.oci node stack (tools init +-# overlaybd-ublkd sidecar + agent flag);-# - adds the registry credentials, the server's-# template_oci_publish_secret, and the pool fastlet OCI mounts;-# - builds an overlaybd template beside the native one and verifies a-# sandbox + snapshot round trip from it.-# OCI_STACK=0 keeps the previous native-only environment.+# OverlayBD OCI stack, default on: one cluster serves both template paths.+# Requires node ublk support (CONFIG_BLK_DEV_UBLK). Enables the in-cluster+# TLS registry (CA baked into the fsb images), the chart's runtime.oci node+# stack, the registry credentials/server setting, and the overlaybd verify+# pass. OCI_STACK=0 is the native-only escape hatch.OCI_STACK="${OCI_STACK:-1}"OCI_REGISTRY_IMAGE="${OCI_REGISTRY_IMAGE:-registry:2}"OCI_HTPASSWD_IMAGE="${OCI_HTPASSWD_IMAGE:-httpd:2.4-alpine}"@@ -1215,11 +1202,8 @@ template_up() {return 0}-# Same build inputs as the native template, published through the in-cluster-# OCI registry (format=overlaybd): the server projects it onto a-# SandboxTemplate CR whose builder runs fsb-vm build + push, and the-# resulting status.manifestRef (oci://host/repo@sha256:...) is the runnable-# artifact the server hands to FastPath on template-mode creates.+# An overlaybd template beside the native one: same inputs, published to+# the in-cluster registry. status.manifestRef is the runnable artifact.OCI_TEMPLATE_ID=""_overlaybd_template_phase() {@@ -1259,9 +1243,7 @@ template_up_overlaybd() {fail "overlaybd template entered Failed"fiattempts=$((attempts + 1))- # OCI builds run the full convertor + Firecracker cold boot in the- # builder Pod; give them more room than native (which reuses the- # same bound but uploads less).+ # OCI builds run the convertor + a Firecracker cold boot.[[ "$attempts" -ge 450 ]] && { failure_dump "overlaybd-template-timeout"; fail "overlaybd template not Succeeded after 450 attempts"; }sleep 2done@@ -1278,11 +1260,9 @@ _overlaybd_template_phase_is_succeeded() {# --- stage: OverlayBD OCI registry (CA, image CA-bake, in-cluster registry) ----# bake_registry_ca retags an already-built image with the registry CA-# trusted (update-ca-certificates). The upstream Dockerfiles take no CA-# input, so the env applies a one-layer overlay image; the fastlet (fsb-vm-# manifest reads), the firecracker-runtime (ublkd block reads via libcurl)-# and the sandboxtemplate-builder (fsb-vm push) all consume it.+# bake_registry_ca retags a built image with the registry CA trusted; the+# upstream Dockerfiles take no CA input. Consumers: fastlet (fsb-vm), the+# firecracker-runtime (ublkd), the sandboxtemplate-builder (push).bake_registry_ca() { # <image>local image="$1"docker image inspect "$image" >/dev/null 2>&1 || die "image $image missing for the registry CA bake"@@ -1299,16 +1279,11 @@ registry_ca_up() {}command -v openssl >/dev/null 2>&1 || die "openssl is required for the OCI registry certificates"mkdir -p "$CA_DIR"- # The CA persists in $WORK and is reused across runs; the serving- # certificate is re-issued every run (cheap, and the Service DNS name- # is fixed while the key material rotates).- # The CA must carry a subjectKeyIdentifier AND no duplicate extensions:- # the leaf's authorityKeyIdentifier=keyid is derived from the CA's SKI at- # signing time (an openssl-1.1.1 `req -x509` adds no SKI), and a CA whose- # extensions were stacked twice (host v3_ca section + -addext) poisons- # the WHOLE chain — OpenSSL 3 clients cache every chain member and fail- # at ossl_x509v3_cache_extensions:reason(158) even though the leaf text- # looks sane. Regenerate on either defect.+ # The CA persists in $WORK; the serving cert is re-issued per run.+ # The CA needs a subjectKeyIdentifier (1.1.1 `req -x509` adds none) and+ # no duplicate extensions (host v3_ca section + -addext stacks them);+ # either defect makes OpenSSL 3 clients fail chain validation+ # (cache_extensions reason(158)). Regenerate on either.if [[ ! -s "$CA_DIR/ca.crt" || ! -s "$CA_DIR/ca.key" ]] \|| ! openssl x509 -in "$CA_DIR/ca.crt" -noout -text 2>/dev/null | grep -q "Subject Key Identifier" \|| [[ "$(openssl x509 -in "$CA_DIR/ca.crt" -noout -text 2>/dev/null | grep -c 'X509v3 Basic Constraints')" -gt 1 ]]; then@@ -1378,9 +1353,7 @@ registry_up() {kind load docker-image "$OCI_REGISTRY_IMAGE" --name "$KIND_CLUSTER" >/dev/null# Namespace is also ensured by credentials_up; keep this stage self-contained.kubectl create namespace "$RESOURCE_NS" --dry-run=client -o yaml | kubectl apply -f - >/dev/null- # Registry credentials (one account with push+pull, shared by the- # builder publication and the node range reads — the upstream ublkd has- # a service-wide credential context anyway).+ # One push+pull account: the node ublkd credential context is service-wide.docker run --rm --entrypoint htpasswd "$OCI_HTPASSWD_IMAGE" \-Bbn "$OCI_REGISTRY_USER" "$OCI_REGISTRY_PASSWORD" > "$WORK/registry-htpasswd" \|| die "htpasswd generation failed"@@ -1462,12 +1435,9 @@ YAMLpass "in-cluster OCI registry up (https://$OCI_REGISTRY_HOST)"}-# probe_registry_tls observes the registry from INSIDE a pod using the exact-# builder image: what certificate the wire actually carries (issuer +-# fingerprint) and whether the system bundle (the same one Go's fsb-vm reads)-# validates it. Trust material can be perfect in the Secret and the image and-# still diverge from what the pod sees — this closes that gap with ground-# truth instead of another generic TLS failure one build later.+# probe_registry_tls observes the registry from inside a pod running the+# builder image: the served certificate and whether the system bundle+# validates it.probe_registry_tls() {local outout="$(kubectl run registry-tls-probe -n "$RESOURCE_NS" \@@ -1484,11 +1454,8 @@ cert_fingerprint() { # <pem>openssl x509 -in "$1" -noout -fingerprint -sha256 | cut -d= -f2}-# verify_registry_trust proves the SERVING secret carries exactly the-# certificate registry_ca_up signed for this run (leaf-to-leaf comparison —-# the leaf's fingerprint differs from the CA's by design). A silent mismatch-# here costs a full build cycle to discover as "x509: certificate signed by-# unknown authority" at push time.+# verify_registry_trust checks the serving Secret carries exactly the+# certificate signed this run (leaf-to-leaf fingerprints).verify_registry_trust() {local signed_fp served_fpsigned_fp="$(cert_fingerprint "$CA_DIR/server.crt")"@@ -1501,8 +1468,8 @@ verify_registry_trust() {pass "registry serving cert matches the env-signed certificate ($signed_fp)"}-# verify_image_ca_bake proves the CA is present AND merged into the image's-# system bundle (update-ca-certificates ran over it).+# verify_image_ca_bake checks the CA landed in the image and was merged+# into its system bundle.verify_image_ca_bake() { # <image>local ca_fp bodyca_fp="$(cert_fingerprint "$CA_DIR/ca.crt")"@@ -1522,8 +1489,6 @@ verify_image_ca_bake() { # <image>pass "CA baked + merged in $1 ($ca_fp)"}-# bake_registry_ca_into_images retags the fsb images with the registry CA-# right after they are built (OCI_STACK=1 only).bake_registry_ca_into_images() {[[ "$OCI_STACK" == 1 ]] || return 0log "baking the registry CA into the fsb images"@@ -1806,9 +1771,7 @@ render_server_config() { # > $GEN_DIR/osb-server-config.toml-v fastpath="$FASTPATH_ENDPOINT" -v fsb_ns="$RESOURCE_NS" -v pool="$POOL_NAME" \-v execd="$EXECD" -v oci_secret="$OCI_REGISTRY_SECRET" -v oci_stack="$OCI_STACK" '{ if ($0 == "# @OCI_PUBLISH_SECRET@") {- # OverlayBD templates publish through the in-cluster registry; the- # server bakes this Secret name as output.publishSecretRef. Emitted- # in-place so the key stays inside the [kubernetes] table.+ # emitted in-place so the key stays inside [kubernetes].if (oci_stack == "1")printf "template_oci_publish_secret = \"%s\"\n", oci_secretnext }diff --git a/scripts/fast-sandbox-env/manifests/cluster/kind-cluster.yaml b/scripts/fast-sandbox-env/manifests/cluster/kind-cluster.yamlindex 43134ea33..d7d45dd56 100644--- a/scripts/fast-sandbox-env/manifests/cluster/kind-cluster.yaml+++ b/scripts/fast-sandbox-env/manifests/cluster/kind-cluster.yaml@@ -15,19 +15,11 @@# /var/lib/fast-sandbox StateRoot; prepared by integration-env.sh up# (XFS loop image when XFS_STATEROOT=1 so# per-sandbox rootfs copies are CoW reflinks)-# # @UBLK_DEV_MOUNT@ when OCI_STACK=1, rendered FIRST: a full bind of the-# host /dev. OverlayBD's ublk devices are created by-# the host kernel at add time (the control misc node-# /dev/ublk-control, the queue char nodes-# /dev/ublkc<N> under the ublk-char major, and-# per-dynamic-major block nodes /dev/ublkb<N> — this-# kernel registers no block major). A kind node's-# /dev is a private tmpfs, so no static mount or-# mknod can track them; binding the host devtmpfs-# lets the builder Pods, the node ublkd sidecar and-# fastlets see every node as the kernel creates it.-# It stays the FIRST extraMount so the private-# /dev/shm bind below shadows the host shm again.+# # @UBLK_DEV_MOUNT@ when OCI_STACK=1, rendered FIRST: a full bind of+# the host /dev, so ublk device nodes (created by+# the kernel at add time, block majors dynamic)+# are visible inside the node. FIRST so the+# private /dev/shm bind below shadows it back.## Node state roots are PRIVATE per node: each node container binds its# own host subdirectory (control-plane/ or worker/) at the samediff --git a/scripts/fast-sandbox-env/manifests/pool/firecracker-egress-pool.yaml b/scripts/fast-sandbox-env/manifests/pool/firecracker-egress-pool.yamlindex fc62f2377..4bcb5b549 100644--- a/scripts/fast-sandbox-env/manifests/pool/firecracker-egress-pool.yaml+++ b/scripts/fast-sandbox-env/manifests/pool/firecracker-egress-pool.yaml@@ -32,10 +32,8 @@# "@FASTLET_IMAGE@" "@EGRESS_IMAGE@" "@POOL_MIN@" "@POOL_MAX@"# # @WARM_IMAGES@ -> warmImages block when WARM_IMAGES=1# # @OCI_FASTLET_ENV@ / # @OCI_FASTLET_MOUNTS@ / # @OCI_FASTLET_VOLUMES@-# -> the fastlet OCI env item, its oci-tools/oci-socket/host-dev mounts-# and their volumes when OCI_STACK=1 (OverlayBD on-demand loading; the-# registry config itself is compiled into Fastlets by the pool-# controller from the fast-sandbox-registry ConfigMap)+# -> the fastlet OCI env item + shared mounts/volumes when OCI_STACK=1+# (registry config is compiled into Fastlets by the pool controller)# (quoted in the template so the file stays valid YAML; the render step# substitutes the token including its quotes)#diff --git a/server/opensandbox_server/api/schema.py b/server/opensandbox_server/api/schema.pyindex e00ca3fa4..39ce31cc9 100644--- a/server/opensandbox_server/api/schema.py+++ b/server/opensandbox_server/api/schema.py@@ -1698,12 +1698,9 @@ class CreateFsbTemplateRequest(BaseModel):...,min_length=1,description=(- "Artifact publish destination for the built snapshot set. "- "format=overlaybd (default) requires a repository-only OCI "- "target, e.g. 'oci://registry.example.com/sandbox/templates' "- "(tags and digests are rejected; the system generates an "- "immutable per-build tag pair). format=native requires an "- "S3-compatible target, e.g. 's3://bucket/publish'."+ "Publish destination for the built snapshot set: "+ "'oci://registry/repository' for format=overlaybd (default), "+ "'s3://bucket/prefix' for format=native."),)format: Literal["native", "overlaybd"] = Field(@@ -1728,10 +1725,8 @@ class FsbTemplateStatus(BaseModel):None,alias="manifestRef",description=(- "Artifact reference of the published snapshot set — "- "s3://.../manifest.json for format=native, or the immutable "- "oci://registry/repo@sha256:... manifest for format=overlaybd "- "(the runnable reference for template-mode creates); present "+ "Published artifact reference — oci://...@sha256 for "+ "format=overlaybd, s3://.../manifest.json for native; present ""when Succeeded"),)diff --git a/server/opensandbox_server/config.py b/server/opensandbox_server/config.pyindex 8e952f07c..24bb6b0b6 100644--- a/server/opensandbox_server/config.py+++ b/server/opensandbox_server/config.py@@ -816,12 +816,9 @@ class KubernetesRuntimeConfig(BaseModel):default=None,min_length=1,description=(- "Name of a kubernetes.io/dockerconfigjson Secret in each "- "template's namespace, used as output.publishSecretRef for "- "format: overlaybd SandboxTemplate builds (fast-sandbox OCI "- "publication). Required when creating overlaybd templates; "- "native templates keep using "- "kubernetes.template_s3_publish_secret."+ "dockerconfigjson Secret used as output.publishSecretRef for "+ "format: overlaybd SandboxTemplate builds. Required when "+ "creating overlaybd templates."),)template_mitm_ca_secret: Optional[str] = Field(diff --git a/server/opensandbox_server/services/fast_sandbox/snapshot_runtime.py b/server/opensandbox_server/services/fast_sandbox/snapshot_runtime.pyindex a192b55a9..23c25f75d 100644--- a/server/opensandbox_server/services/fast_sandbox/snapshot_runtime.py+++ b/server/opensandbox_server/services/fast_sandbox/snapshot_runtime.py@@ -154,9 +154,8 @@ class FastSandboxSnapshotRuntime:source_image = self._source_sandbox_image(ns, sandbox_id)if source_image is None:- # The artifact encoding decides template_name semantics: native- # requires it, OCI must omit it. Without the source image the- # wrong branch is a guaranteed upstream rejection, so fail here.+ # The encoding decides template_name semantics; guessing wrong is+ # a guaranteed upstream rejection.return SnapshotRuntimeStatus(state=SnapshotState.FAILED,reason="snapshot_runtime_create_failed",@@ -172,10 +171,8 @@ class FastSandboxSnapshotRuntime:sandbox=namespaced_reference(ns, sandbox_id),)if not source_image.startswith(OCI_IMAGE_PREFIX):- # native + S3 snapshots publish under a template-name index key.- # OCI snapshots must omit it: their rootfs/snapfiles tags are- # derived from the Fastlet-assigned random snapshot_id, and the- # restore image is the returned manifest_ref.+ # native publishes under a template-name index key; OCI snapshots+ # omit it and restore from the returned manifest_ref.request.template_name = snapshot_namerequest.metadata[SNAPSHOT_ID_METADATA_KEY] = snapshot_idtry:@@ -211,11 +208,7 @@ class FastSandboxSnapshotRuntime:)def _source_sandbox_image(self, namespace: str, sandbox_id: str) -> Optional[str]:- """Read the source Sandbox CR's image to classify the artifact encoding.-- Returns None when the CR is unreadable (missing or API errors) — the- caller must not guess template_name semantics in that case.- """+ """The source Sandbox CR's image, or None when unreadable."""try:cr = self._k8s_client.get_custom_object(group=GROUP,@@ -224,7 +217,7 @@ class FastSandboxSnapshotRuntime:plural=SANDBOX_PLURAL,name=sandbox_id,)- except Exception as exc: # noqa: BLE001 - any read failure blocks the branch decision+ except Exception as exc: # noqa: BLE001 - unreadable means unclassifiablelogger.warning(f"Failed to read Sandbox CR {namespace}/{sandbox_id} before "f"snapshot: {exc}"@@ -358,12 +351,9 @@ class FastSandboxSnapshotRuntime:template_name = (getattr(info, "template_name", "") or "").strip() or Noneif phase_name in _TERMINAL_READY_PHASES:- # The restore image depends on the publication mode. Native + S3- # snapshots publish under index/<sha256(templateName)>.json (same- # content-addressed layout as template golden images), keyed by- # the snapshot's template name. OCI snapshots omit the template- # name and restore from the returned immutable snapfiles- # manifest reference. A success carrying neither is unpublishable.+ # native restores via the template-name index key, OCI via the+ # returned immutable manifest_ref; a success with neither is+ # unpublishable.if template_name:return SnapshotRuntimeStatus(state=SnapshotState.READY,diff --git a/server/opensandbox_server/services/templates/template_service.py b/server/opensandbox_server/services/templates/template_service.pyindex 8b90b1e86..57a8cb171 100644--- a/server/opensandbox_server/services/templates/template_service.py+++ b/server/opensandbox_server/services/templates/template_service.py@@ -90,16 +90,11 @@ _TEMPLATE_NOT_FOUND = {def _publish_validation_error(format: str, publish: str) -> Optional[str]:- """Return a rejection reason for a format/publish pair, or None.-- Mirrors the SandboxTemplate builder's output validation so an invalid- destination fails as a 400 at creation instead of a failed build Pod.- overlaybd requires ``oci://host/repository``: the host may carry a port- but no userinfo (credentials must come from publishSecretRef, and the- publish value is echoed back by the template API), the repository path- must be non-empty, slash-terminated-free, and free of tag (``:``) or- digest (``@``) suffixes — the system generates the build tags itself.- native requires an ``s3://bucket`` target with a non-empty bucket.+ """Reject format/publish pairs the builder would reject, as a 400 here.++ overlaybd: ``oci://host/repository`` — port allowed, no userinfo+ (credentials live in publishSecretRef), no tag/digest (the system+ generates the build tags). native: ``s3://bucket/prefix``."""if format == "overlaybd":if not publish.startswith("oci://"):@@ -439,23 +434,11 @@ class FastSandboxTemplateService:def resolve_template_artifact(self, template_id: str) -> tuple[str, list[str]]:"""Resolve a Succeeded template to its runnable artifact + entrypoint.- The returned reference depends on the template's output format:-- - ``native``: the TEMPLATE ID (tpl-<uuid>). The builder publishes- the content-addressed index under that key, so the runtime pulls- and caches this template's exact artifact set — two templates of- the same source image never alias each other. The legacy- sha256(image) index stays a last-writer-wins fallback for- warmImages and older clients.- - ``overlaybd``: the template's immutable OCI ``manifest_ref``- (oci://registry/repo@sha256:...) from the CRD status — the- fast-sandbox OCI publication is the only runnable reference;- ``output.publish`` is a build destination, not an image.-- Template-mode Create uses this: unknown, non-Succeeded, or- manifest-less templates all yield 404, so no existence information- leaks. Reads the DB row only; the watch reactor converges build- phase.+ native → the template id (the builder's content-addressed index key);+ overlaybd → the CRD's immutable OCI manifest_ref. Unknown,+ non-Succeeded, or manifest-less templates all yield 404, so no+ existence information leaks. Reads the DB row only; the watch+ reactor converges build phase."""namespace = self._resolve_namespace()record = self._repo().get(template_id, namespace)@@ -471,11 +454,9 @@ class FastSandboxTemplateService:return record.template_id, entrypointmanifest_ref = record.manifest_ref or ""if not manifest_ref.startswith("oci://"):- # Succeeded without a resolvable OCI publication: either the CRD- # status has not landed yet (transient) or the row predates the- # fast-sandbox OCI contract (legacy overlaybd+S3 artifacts are- # rejected upstream and can never become runnable). Both are- # 404s; the legacy case gets an actionable message for the owner.+ # Transient (status not landed) or a legacy overlaybd+S3 row+ # (rejected upstream). Both 404; the legacy message is+ # actionable for the owner.raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,detail={diff --git a/server/tests/test_fsb_snapshot_runtime.py b/server/tests/test_fsb_snapshot_runtime.pyindex aac6490e9..804750865 100644--- a/server/tests/test_fsb_snapshot_runtime.py+++ b/server/tests/test_fsb_snapshot_runtime.py@@ -142,8 +142,7 @@ def _runtime() -> tuple[FastSandboxSnapshotRuntime, FakeFastPathClient, WatchRecordingK8sClient]:fastpath = fastpath or FakeFastPathClient()k8s = k8s or WatchRecordingK8sClient()- # Default the source sandbox to a native image so the create path keeps- # setting template_name; OCI-source tests override the image explicitly.+ # Default source image is native; OCI-source tests override it.for namespace in ("default", "tenant-a"):k8s.sandbox_crs.setdefault((namespace, SANDBOX_ID), _sandbox_cr("alpine:3.19"))runtime = FastSandboxSnapshotRuntime(@@ -294,8 +293,7 @@ def test_inspect_fails_when_succeeded_without_template_name() -> None:def test_inspect_succeeded_oci_manifest_restores_from_manifest_ref() -> None:- """OCI snapshots omit the template name; the immutable snapfiles- manifest reference is the runnable restore image."""+ """OCI snapshots restore from the immutable manifest reference."""fastpath = FakeFastPathClient()manifest_ref = "oci://registry.example.com/sandbox/snapshots@sha256:def456"fastpath.get_by_name[("default", build_public_snapshot_name(SNAPSHOT_ID))] = _Response(diff --git a/server/tests/test_templates.py b/server/tests/test_templates.pyindex 16570bb93..da16679d7 100644--- a/server/tests/test_templates.py+++ b/server/tests/test_templates.py@@ -538,8 +538,7 @@ def test_resolve_overlaybd_without_manifest_ref_404(overlaybd_service, crs):def test_resolve_overlaybd_legacy_s3_manifest_demands_rebuild(overlaybd_service, crs):- """Pre-OCI overlaybd+S3 rows can never become runnable: the resolve gate- says so instead of handing out a dead artifact reference."""+ """Legacy overlaybd+S3 rows are unrunnable: resolve says so."""record = overlaybd_service.create_template(_overlaybd_request())crs.set_status("ns-1", record.crd_name, {"phase": "Succeeded", "manifestRef": "s3://b/legacy/manifest"}diff --git a/tests/python/tests/test_fsb_e2e.py b/tests/python/tests/test_fsb_e2e.pyindex f43f0067e..b79b4f7f1 100644--- a/tests/python/tests/test_fsb_e2e.py+++ b/tests/python/tests/test_fsb_e2e.py@@ -66,9 +66,7 @@ from opensandbox.sandbox import Sandboxlogger = logging.getLogger(__name__)FSB_TEMPLATE_ID = os.getenv("OPENSANDBOX_TEST_FSB_TEMPLATE_ID", "")-# The suite runs once per template in the integration env (native first,-# then the overlaybd one); each carries a different origin metadata value,-# so the catalog assertions key off what the env actually passed in.+# Set per run by the env's sdk-e2e (native + overlaybd templates differ).FSB_TEMPLATE_ORIGIN = os.getenv("OPENSANDBOX_TEST_FSB_TEMPLATE_ORIGIN", "fast-sandbox-env")# alpine ships busybox wget: a real HTTPS request, so egress probes# exercise both gates of the fsb dns+nft chain (DNS resolution and