Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(templates): validate OCI publication and restore references
贾岛46a00aa28480
diff --git a/cli/README.md b/cli/README.mdindex b979719c6..18a43000e 100644--- a/cli/README.md+++ b/cli/README.md@@ -202,7 +202,8 @@ osb sandbox create -f sandbox-request.json -o jsonTemplates are golden-image builds; the build runs asynchronously, so poll `template get` until the status phase is `Succeeded`. Template management requires a Kubernetes-backed runtime.```bash-osb template create --image python:3.12 --publish s3://bucket/publish -o json+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json+osb template create --image python:3.12 --publish oci://registry.example.com/sandbox/templates --format overlaybd -o jsonosb template get <template-id> -o jsonosb template list -o jsonosb template delete <template-id> -o json@@ -218,11 +219,14 @@ osb template create -f template-request.json -o json{"image": "python:3.12","publish": "s3://bucket/publish",+ "format": "native","resourceLimits": { "cpu": "1", "memory": "512Mi" },"readiness": { "probe": "tcp://127.0.0.1:44772", "warmupSeconds": 60 }}```+OCI targets must name a repository without a tag or digest. Use `overlaybd` (the default) for OCI and explicitly select `native` for S3. The builder returns an immutable OCI reference in `status.manifestRef`; `sandbox create --template` uses that reference automatically. See [OCI template setup](../docs/guides/oci-templates.md) for Registry Secrets and runtime prerequisites.+### Manage snapshotsSnapshots capture a sandbox's state and can back new sandboxes.diff --git a/cli/src/opensandbox_cli/commands/template.py b/cli/src/opensandbox_cli/commands/template.pyindex 8505b4464..cb578f614 100644--- a/cli/src/opensandbox_cli/commands/template.py+++ b/cli/src/opensandbox_cli/commands/template.py@@ -55,7 +55,7 @@ def template_group(ctx: click.Context) -> None:"--publish","-p",default=None,- help="S3-compatible publish target for the built artifacts (e.g. s3://bucket/publish). Required unless --file is used.",+ help="Publish target: s3://bucket/publish (native) or oci://registry/repository (overlaybd, no tag or digest). Required unless --file is used.",)@click.option("--file",diff --git a/cli/src/opensandbox_cli/skills/opensandbox-sandbox-lifecycle.md b/cli/src/opensandbox_cli/skills/opensandbox-sandbox-lifecycle.mdindex 91ac14e29..0adfd612c 100644--- a/cli/src/opensandbox_cli/skills/opensandbox-sandbox-lifecycle.md+++ b/cli/src/opensandbox_cli/skills/opensandbox-sandbox-lifecycle.md@@ -140,7 +140,8 @@ If the user does not specify an image, recommend one that matches the runtime thTemplates are golden-image builds. The build is asynchronous: `template create` returns a template in `Pending`; poll `template get` until the phase is `Succeeded` (or `Failed`).```bash-osb template create --image python:3.12 --publish s3://bucket/publish -o json+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json+osb template create --image python:3.12 --publish oci://registry.example.com/sandbox/templates --format overlaybd -o jsonosb template create -f template-request.json -o jsonosb template get <template-id> -o jsonosb template list -o json@@ -149,6 +150,8 @@ osb template delete <template-id> -o jsonUseful `template create` options: `--resource cpu=1 memory=512Mi disk=2Gi`, `--entrypoint` (repeat per argv item), `--env KEY=VALUE`, `--metadata KEY=VALUE`, `--format native|overlaybd`, `--readiness-probe tcp://127.0.0.1:44772`, `--warmup-seconds 60`. `-f <request-file>` reads the full request as public `CreateTemplateRequest` JSON (camelCase: `image`, `publish`, `resourceLimits`, `entrypoint`, `env`, `metadata`, `format`, `readiness.probe`, `readiness.warmupSeconds`), mutually exclusive with those flags.+OCI publication requires a repository-only target without a tag or digest, `overlaybd` format, and a server-configured `.dockerconfigjson` Secret (`kubernetes.template_oci_publish_secret`). Sandbox creation also requires an OCI-enabled Fast Sandbox pool and the OverlayBD node daemon. S3 publication uses `native`. Wait for `Succeeded` before creating a sandbox; the server uses the immutable OCI manifest reference for OCI templates.+Create a sandbox from a succeeded template:```bash@@ -320,7 +323,7 @@ osb sandbox health <sandbox-id> -o jsonBuild a template, wait for it, and create from it:```bash-osb template create --image python:3.12 --publish s3://bucket/publish -o json+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o jsonosb template get <template-id> -o jsonosb sandbox create --template <template-id> --timeout 30m -o jsonosb sandbox health <sandbox-id> -o jsondiff --git a/cli/tests/test_cli_help.py b/cli/tests/test_cli_help.pyindex aadd50588..b205b0397 100644--- a/cli/tests/test_cli_help.py+++ b/cli/tests/test_cli_help.py@@ -65,6 +65,12 @@ class TestSandboxHelp:class TestTemplateAndSnapshotHelp:+ def test_template_create_help_describes_oci_destination(self, runner: CliRunner) -> None:+ result = runner.invoke(cli, ["template", "create", "--help"])+ assert result.exit_code == 0+ assert "oci://registry/repository" in result.output+ assert "no tag or digest" in " ".join(result.output.split())+@pytest.mark.parametrize("group", ["template", "snapshot"])def test_group_help_lists_subcommands(self, runner: CliRunner, group: str) -> None:result = runner.invoke(cli, [group, "--help"])diff --git a/cli/tests/test_commands.py b/cli/tests/test_commands.pyindex 48c0b8a08..39f11309c 100644--- a/cli/tests/test_commands.py+++ b/cli/tests/test_commands.py@@ -1089,7 +1089,8 @@ def _make_template_info(phase: str = "Pending") -> TemplateInfo:class TestTemplateCommands:- def test_create_builds_request(self, runner: CliRunner) -> None:+ @pytest.mark.parametrize("publish", ["s3://bucket/publish", "oci://registry.example.com/team/templates"])+ def test_create_builds_request(self, runner: CliRunner, publish: str) -> None:mock_mgr = MagicMock()mock_mgr.create_template.return_value = _make_template_info()@@ -1101,7 +1102,9 @@ class TestTemplateCommands:"--image","python:3.12","--publish",- "s3://bucket/publish",+ publish,+ "--format",+ "overlaybd" if publish.startswith("oci://") else "native","--resource","cpu=1","--entrypoint",@@ -1122,7 +1125,8 @@ class TestTemplateCommands:req = mock_mgr.create_template.call_args.args[0]assert isinstance(req, CreateTemplateRequest)assert req.image == "python:3.12"- assert req.publish == "s3://bucket/publish"+ assert req.publish == publish+ assert req.format == ("overlaybd" if publish.startswith("oci://") else "native")assert req.resource_limits == {"cpu": "1"}assert req.entrypoint == ["python"]assert req.env == {"FOO": "bar"}@@ -1132,15 +1136,17 @@ class TestTemplateCommands:data = json.loads(result.output)assert data["template_id"] == "tpl_abc"+ @pytest.mark.parametrize("publish", ["s3://bucket/publish", "oci://registry.example.com/team/templates"])def test_create_from_file_builds_request(- self, runner: CliRunner, tmp_path: Path+ self, runner: CliRunner, tmp_path: Path, publish: str) -> None:mock_mgr = MagicMock()mock_mgr.create_template.return_value = _make_template_info()request_path = tmp_path / "template-request.json"request_path.write_text(json.dumps({"image": "python:3.12",- "publish": "s3://bucket/publish",+ "publish": publish,+ "format": "overlaybd" if publish.startswith("oci://") else "native","resourceLimits": {"cpu": "1", "memory": "512Mi"},"entrypoint": ["python", "-m", "http.server"],"env": {"FOO": "bar"},@@ -1158,7 +1164,8 @@ class TestTemplateCommands:req = mock_mgr.create_template.call_args.args[0]assert isinstance(req, CreateTemplateRequest)assert req.image == "python:3.12"- assert req.publish == "s3://bucket/publish"+ assert req.publish == publish+ assert req.format == ("overlaybd" if publish.startswith("oci://") else "native")assert req.resource_limits == {"cpu": "1", "memory": "512Mi"}assert req.entrypoint == ["python", "-m", "http.server"]assert req.env == {"FOO": "bar"}diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex 226c0c236..85b59b956 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -226,6 +226,7 @@ export default defineConfig({{ text: "Multi-Tenancy", link: "/guides/multi-tenancy" },{ text: "Isolation Sessions", link: "/guides/isolation-sessions" },{ text: "Pause & Resume", link: "/guides/pause-resume" },+ { text: "OCI Templates", link: "/guides/oci-templates" },{text: "Auto-Pause & Wake-on-Access",link: "/guides/auto-pause-wake",diff --git a/docs/architecture/fast-sandbox/templates.md b/docs/architecture/fast-sandbox/templates.mdindex e26d413ad..6a57b7f4d 100644--- a/docs/architecture/fast-sandbox/templates.md+++ b/docs/architecture/fast-sandbox/templates.md@@ -25,6 +25,8 @@ A `SandboxTemplate` describes a conversion, not just a copy: an ordinary OCI ima- **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.+Native templates publish to S3-compatible storage and resolve through the per-template image index. OverlayBD templates publish paired rootfs and snapshot images to an OCI registry; the catalog records the immutable OCI manifest reference, which becomes the runtime image at sandbox creation. Build credentials are selected by destination through server configuration. See [OCI template setup](/guides/oci-templates) for deployment and usage.+## Using templatesSandbox creation with a `templateId` resolves to the recorded artifact; capacity comes from the referenced pool, not from the template. Because the template pins the workload, per-sandbox behavior is limited to intent: identity, TTL, metadata, network policy, and an optional pool reference (see [Scheduling](/architecture/fast-sandbox/scheduling)). Updating a template rebuilds the artifact and yields a new digest — existing sandboxes keep running their admitted revision; new creations pick up the new build.diff --git a/docs/cli/index.md b/docs/cli/index.mdindex 61281b467..fce7690ba 100644--- a/docs/cli/index.md+++ b/docs/cli/index.md@@ -185,7 +185,8 @@ osb sandbox create --snapshot-id <snapshot-id> --timeout 30m -o jsonTemplates are golden-image builds; the build runs asynchronously, so poll `template get` until the status phase is `Succeeded`. Template management requires a Kubernetes-backed runtime.```bash-osb template create --image python:3.12 --publish s3://bucket/publish -o json+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json+osb template create --image python:3.12 --publish oci://registry.example.com/sandbox/templates --format overlaybd -o jsonosb template get <template-id> -o jsonosb template list -o jsonosb template delete <template-id> -o json@@ -193,6 +194,8 @@ osb template delete <template-id> -o json`template create` also accepts `--resource cpu=1 memory=512Mi disk=2Gi`, `--entrypoint` (repeat per argv item), `--env KEY=VALUE`, `--metadata KEY=VALUE`, `--format native|overlaybd`, `--readiness-probe`, and `--warmup-seconds`.+OCI publishing requires a repository-only target without a tag or digest. The builder generates unique tags and returns an immutable `oci://...@sha256:...` in `status.manifestRef`. Use `overlaybd` (the default) for OCI and explicitly select `native` for S3. Configure the builder's Registry Secret and an OCI-enabled Fast Sandbox pool before building; see [OCI template setup](/guides/oci-templates).+### Manage snapshotsSnapshots capture a sandbox's state and can back new sandboxes.diff --git a/docs/guides/oci-templates.md b/docs/guides/oci-templates.mdnew file mode 100644index 000000000..442a39863--- /dev/null+++ b/docs/guides/oci-templates.md@@ -0,0 +1,60 @@+---+title: Publish Templates to an OCI Registry+description: Build Golden Image templates in an OCI registry and create Fast Sandbox instances from immutable artifacts.+---++# Publish templates to an OCI registry++`osb template create` can publish Golden Image artifacts to an OCI registry. Set `--publish` to a repository-only address such as `oci://registry.example.com/sandbox/templates`; omit tags and digests. The builder generates a UUID for each build and publishes paired rootfs and snapshot images. Once the build succeeds, `status.manifestRef` contains the immutable `oci://registry.example.com/sandbox/templates@sha256:...` reference used to restore that build.++## Prepare the runtime++Use the fast-sandbox companion images built from the source pinned in `manifests/third-party/fast-sandbox.commit`. OCI templates require the OverlayBD node daemon, shared state and device mounts, and `FAST_SANDBOX_OCI_ENABLED=true` on the runtime agent, node daemon, and Fastlet pool. Enable `runtime.oci.enabled` in the fast-sandbox Helm chart to install the node OCI stack. Follow the upstream [OverlayBD OCI deployment guide](https://github.com/opensandbox-group/fast-sandbox/blob/4c389ae1b0e3823d59eee2ade4fba36682984590/docs/guides/overlaybd-oci-sandboxes.md) to configure the pool and its registry credentials.++## Configure build credentials++Create a Docker Registry Secret in each template namespace. Set `REGISTRY_USER` and `REGISTRY_PASSWORD` to an account with push and pull access:++```bash+kubectl -n <template-namespace> create secret docker-registry sandbox-registry-credentials \+ --docker-server=registry.example.com \+ --docker-username="$REGISTRY_USER" \+ --docker-password="$REGISTRY_PASSWORD"+```++Configure the server to use this Secret; OCI publication requires an explicit Secret name:++```toml+[kubernetes]+template_oci_publish_secret = "sandbox-registry-credentials"+```++The Secret must contain `.dockerconfigjson`, including credentials for private source and execd images when needed. Anonymous access can use a Secret containing `{"auths":{}}`. Registry authentication supports anonymous or username/password credentials; identity-token-only credentials are unsupported. Configure the pool's registry credentials separately as described in the upstream deployment guide; the build Secret is not copied into running sandboxes.++## Build and use a template++```bash+osb template create \+ --image python:3.12 \+ --publish oci://registry.example.com/sandbox/templates \+ --format overlaybd \+ -o json++osb template get <template-id> -o json+```++Wait for `status.phase` to become `Succeeded`, then create a sandbox:++```bash+osb sandbox create --template <template-id> --timeout 30m -o json+```++The server resolves the template ID to the recorded immutable OCI reference, so builds from the same source image remain independent. A repository-only publish target is a build destination; it is not a runnable artifact reference.++OCI publishing requires `overlaybd`, which remains the default format. For S3-compatible publication, explicitly select `native`:++```bash+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json+```++Deleting a template removes its catalog entry and Kubernetes build resource. Registry artifacts remain subject to the registry's retention and garbage collection policies.diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Models/Templates.cs b/sdks/sandbox/csharp/src/OpenSandbox/Models/Templates.csindex d56c122e7..04ca96a33 100644--- a/sdks/sandbox/csharp/src/OpenSandbox/Models/Templates.cs+++ b/sdks/sandbox/csharp/src/OpenSandbox/Models/Templates.cs@@ -77,7 +77,7 @@ public class TemplateStatuspublic required string Phase { get; set; }/// <summary>- /// Gets or sets the S3 manifest reference of the published artifacts;+ /// Gets or sets the published S3 manifest reference or immutable OCI reference;/// present when the phase is Succeeded./// </summary>[JsonPropertyName("manifestRef")]@@ -108,8 +108,8 @@ public class CreateTemplateRequestpublic required string Image { get; set; }/// <summary>- /// Gets or sets the S3-compatible publish target for the built artifacts,- /// e.g. "s3://bucket/publish".+ /// Gets or sets s3://bucket/publish (native) or oci://registry/repository+ /// (overlaybd, without a tag or digest)./// </summary>[JsonPropertyName("publish")]public required string Publish { get; set; }@@ -175,7 +175,7 @@ public class TemplateInfopublic required string Image { get; set; }/// <summary>- /// Gets or sets the S3-compatible publish target.+ /// Gets or sets the S3-compatible or repository-only OCI publish target./// </summary>[JsonPropertyName("publish")]public required string Publish { get; set; }diff --git a/sdks/sandbox/go/types.go b/sdks/sandbox/go/types.goindex 6ea15677c..06b8bb554 100644--- a/sdks/sandbox/go/types.go+++ b/sdks/sandbox/go/types.go@@ -552,7 +552,7 @@ type TemplateReadiness struct {// TemplateStatus is the build status of a fsb template.type TemplateStatus struct {Phase TemplatePhase `json:"phase"`- // ManifestRef is the S3 manifest reference of the published artifacts;+ // ManifestRef is the published S3 manifest reference or immutable OCI reference;// present when the phase is Succeeded.ManifestRef string `json:"manifestRef,omitempty"`// Message is the failure reason when the phase is Failed.@@ -569,8 +569,8 @@ type TemplateStatus struct {type CreateTemplateRequest struct {// Image is the source OCI image reference the golden image is built from.Image string `json:"image"`- // Publish is the S3-compatible publish target for the built artifacts,- // e.g. "s3://bucket/publish".+ // Publish is s3://bucket/publish (native) or oci://registry/repository+ // (overlaybd, without a tag or digest).Publish string `json:"publish"`// ResourceLimits is the guest machine sizing, e.g.// {"cpu": "1", "memory": "512Mi", "disk": "2Gi"}. Server defaults whendiff --git a/sdks/sandbox/javascript/src/api/lifecycle.ts b/sdks/sandbox/javascript/src/api/lifecycle.tsindex dfda68d27..8a992dae4 100644--- a/sdks/sandbox/javascript/src/api/lifecycle.ts+++ b/sdks/sandbox/javascript/src/api/lifecycle.ts@@ -2287,8 +2287,10 @@ export interface components {};readiness?: components["schemas"]["FsbTemplateReadiness"];/**- * @description S3-compatible publish target for the built artifacts,- * e.g. `s3://bucket/publish`.+ * @description Publish destination: `s3://bucket/publish` for native artifacts or+ * `oci://registry/repository` for overlaybd artifacts. OCI targets+ * must not contain a tag or digest; the builder generates unique+ * tags per build. Registry credentials are configured on the server.*/publish: string;/**@@ -2306,8 +2308,8 @@ export interface components {*/phase: "Pending" | "Building" | "Succeeded" | "Failed";/**- * @description S3 manifest reference of the published artifacts; present when- * Succeeded.+ * @description Published S3 manifest reference or immutable OCI reference+ * (`oci://registry/repository@sha256:...`); present when Succeeded.*/manifestRef?: string;/** @description Failure reason when phase is Failed. */@@ -2334,7 +2336,7 @@ export interface components {[key: string]: string;};readiness?: components["schemas"]["FsbTemplateReadiness"];- /** @description S3-compatible publish target. */+ /** @description S3-compatible or repository-only OCI publish target. */publish: string;/*** @description Snapshot storage encoding.diff --git a/sdks/sandbox/javascript/src/models/templates.ts b/sdks/sandbox/javascript/src/models/templates.tsindex 46d436988..2df6550a9 100644--- a/sdks/sandbox/javascript/src/models/templates.ts+++ b/sdks/sandbox/javascript/src/models/templates.ts@@ -53,7 +53,7 @@ export interface TemplateStatus extends Record<string, unknown> {*/phase: TemplatePhase;/**- * S3 manifest reference of the published artifacts; present when the phase is `Succeeded`.+ * Published S3 manifest reference or immutable OCI reference; present when the phase is `Succeeded`.*/manifestRef?: string;/**@@ -68,7 +68,7 @@ export interface CreateTemplateRequest extends Record<string, unknown> {*/image: string;/**- * S3-compatible publish target for the built artifacts, e.g. `s3://bucket/publish`.+ * Publish destination: `s3://bucket/publish` (native) or `oci://registry/repository` (overlaybd, no tag or digest).*/publish: string;/**@@ -111,7 +111,7 @@ export interface TemplateInfo extends Record<string, unknown> {*/image: string;/**- * S3-compatible publish target.+ * S3-compatible or repository-only OCI publish target.*/publish: string;/**diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/TemplateModels.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/TemplateModels.ktindex a67e6e6b3..345a3b258 100644--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/TemplateModels.kt+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/TemplateModels.kt@@ -125,7 +125,7 @@ class TemplateStatus(* reaches [TemplatePhase.SUCCEEDED] or [TemplatePhase.FAILED].** @property image Source OCI image reference- * @property publish S3-compatible publish target (e.g. `s3://bucket/publish`)+ * @property publish `s3://bucket/publish` (native) or `oci://registry/repository` (overlaybd, without a tag or digest)* @property resourceLimits Runtime resource constraints (e.g. cpu/memory/disk)* @property entrypoint Guest business command (argv); defaults server-side when omitted* @property env Environment variables baked into the golden image (literal values only;@@ -256,7 +256,7 @@ class CreateTemplateRequest private constructor(** @property templateId Server-generated template ID (`tpl_<uuid>`)* @property image Source OCI image reference- * @property publish S3-compatible publish target+ * @property publish S3-compatible or repository-only OCI publish target* @property format Snapshot storage encoding* @property status Current build status* @property createdAt Timestamp when the template was createddiff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_fsb_template_request.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_fsb_template_request.pyindex d4f1e7816..a8a71104b 100644--- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_fsb_template_request.py+++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/create_fsb_template_request.py@@ -44,8 +44,10 @@ class CreateFsbTemplateRequest:Attributes:image (str): Source OCI image reference the golden image is built from.- publish (str): S3-compatible publish target for the built artifacts,- e.g. `s3://bucket/publish`.+ publish (str): Publish destination: `s3://bucket/publish` for native artifacts or+ `oci://registry/repository` for overlaybd artifacts. OCI targets+ must not contain a tag or digest; the builder generates unique+ tags per build. Registry credentials are configured on the server.resource_limits (ResourceLimits | Unset): Runtime resource constraints as key-value pairs. Similar to Kubernetesresource specifications,allows flexible definition of resource limits. Common resource types include:diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template.pyindex 81117ada1..8a59e882c 100644--- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template.py+++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template.py@@ -45,7 +45,7 @@ class FsbTemplate:Attributes:template_id (str): Server-generated template ID (`tpl_<uuid>`).image (str): Source OCI image reference.- publish (str): S3-compatible publish target.+ publish (str): S3-compatible or repository-only OCI publish target.format_ (FsbTemplateFormat): Snapshot storage encoding.status (FsbTemplateStatus): Status of a fsb template build.created_at (datetime.datetime): Creation timestamp (RFC 3339 UTC).diff --git a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template_status.py b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template_status.pyindex 8dadcd43c..1dc4b4bef 100644--- a/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template_status.py+++ b/sdks/sandbox/python/src/opensandbox/api/lifecycle/models/fsb_template_status.py@@ -33,8 +33,8 @@ class FsbTemplateStatus:Attributes:phase (FsbTemplateStatusPhase): Build lifecycle phase.- manifest_ref (str | Unset): S3 manifest reference of the published artifacts; present when- Succeeded.+ manifest_ref (str | Unset): Published S3 manifest reference or immutable OCI reference+ (`oci://registry/repository@sha256:...`); present when Succeeded.message (str | Unset): Failure reason when phase is Failed."""diff --git a/sdks/sandbox/python/src/opensandbox/models/templates.py b/sdks/sandbox/python/src/opensandbox/models/templates.pyindex 73ba989b3..41940dffa 100644--- a/sdks/sandbox/python/src/opensandbox/models/templates.py+++ b/sdks/sandbox/python/src/opensandbox/models/templates.py@@ -83,7 +83,7 @@ class TemplateStatus(BaseModel):default=None,alias="manifestRef",description=(- "S3 manifest reference of the published artifacts; "+ "Published S3 manifest reference or immutable OCI reference; ""present when the phase is Succeeded."),)@@ -110,8 +110,8 @@ class CreateTemplateRequest(BaseModel):)publish: str = Field(description=(- "S3-compatible publish target for the built artifacts, "- "e.g. 's3://bucket/publish'."+ "Publish destination: s3://bucket/publish (native) or "+ "oci://registry/repository (overlaybd, no tag or digest)."))resource_limits: dict[str, str] | None = Field(@@ -174,7 +174,7 @@ class TemplateInfo(BaseModel):alias="templateId",)image: str = Field(description="Source OCI image reference.")- publish: str = Field(description="S3-compatible publish target.")+ publish: str = Field(description="S3-compatible or repository-only OCI publish target.")format: Literal["native", "overlaybd"] = Field(description="Snapshot storage encoding.")diff --git a/server/configuration.md b/server/configuration.mdindex fa73ec86e..b5540dcb9 100644--- a/server/configuration.md+++ b/server/configuration.md@@ -167,7 +167,7 @@ The kubernetes runtime also serves fsb (`fsb-`) sandboxes side by side; these fi| `fastpath_wait_ready_seconds` | number | `30.0` | Bounded readiness wait for DataPlaneReady after Create. || `fastpath_resource_pool` | string | `"default-pool"` | SandboxPool when `extensions.poolRef` is unset. || `template_s3_publish_secret` | string | `"sandbox-oss-credentials"` | Object-store credentials secret for server-created SandboxTemplates (`format: native`). |-| `template_oci_publish_secret` | string \| omitted | `null` | 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 `template_s3_publish_secret`. |+| `template_oci_publish_secret` | string \| omitted | `null` | 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 `template_s3_publish_secret`. See [OCI templates](../docs/guides/oci-templates.md) for setup. || `template_mitm_ca_secret` | string \| omitted | `null` | Secret holding the pinned cluster MITM CA certificate (OSEP-0022). When set, server-created SandboxTemplates bake `spec.egressMitmCertificate` from it (certificate entry only, never the private key); unset keeps templates CA-free. The Secret must exist in each template's namespace (ops-runbook distribution); a missed copy fails the build observably. || `template_mitm_ca_secret_key` | string | `"ca.crt"` | Secret entry holding the CA certificate when `template_mitm_ca_secret` is set. |diff --git a/server/opensandbox_server/services/templates/template_service.py b/server/opensandbox_server/services/templates/template_service.pyindex 57a8cb171..77d64d7aa 100644--- a/server/opensandbox_server/services/templates/template_service.py+++ b/server/opensandbox_server/services/templates/template_service.py@@ -127,6 +127,12 @@ def _publish_validation_error(format: str, publish: str) -> Optional[str]:"publish must be 'oci://registry/repository' without a ""trailing slash.")+ path_component = r"[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*"+ if (+ not re.fullmatch(r"(?:[a-zA-Z0-9.-]+|\[[0-9a-fA-F:]+\])(?::[0-9]+)?", host)+ or not re.fullmatch(rf"{path_component}(?:/{path_component})*", repository)+ ):+ return "publish must be a valid oci://registry/repository without a tag or digest."return Noneif format == "native":if not publish.startswith("s3://"):@@ -453,7 +459,7 @@ class FastSandboxTemplateService:if str(record.spec.get("format") or "overlaybd") != "overlaybd":return record.template_id, entrypointmanifest_ref = record.manifest_ref or ""- if not manifest_ref.startswith("oci://"):+ if not re.fullmatch(re.escape(record.publish) + r"@sha256:[0-9a-f]{64}", manifest_ref):# Transient (status not landed) or a legacy overlaybd+S3 row# (rejected upstream). Both 404; the legacy message is# actionable for the owner.@@ -463,7 +469,7 @@ class FastSandboxTemplateService:"code": SandboxErrorCodes.FSB_TEMPLATE_NOT_FOUND,"message": ("Template artifact is not runnable: overlaybd "- "templates require an OCI manifestRef from a build "+ "templates require an immutable OCI manifestRef in the publish repository from a build ""against the current fast-sandbox contract; rebuild ""the template."),@@ -491,12 +497,13 @@ class FastSandboxTemplateService:fmt = str(record.spec.get("format") or "overlaybd")spec: dict = {"image": record.source_image,- # Per-template artifact identity: the builder publishes the image+ # Native artifact identity: the builder publishes the image# index under BOTH this key (exact, immutable per template) and# the legacy sha256(source-image) key (last-writer-wins, kept for# warmImages and older clients). Sandbox creates carry the# template key, so two templates of the same source image resolve- # to their own artifact sets and caches.+ # to their own artifact sets and caches. OCI creates instead use+ # the immutable manifestRef recorded after publication."indexKey": record.template_id,"entrypoint": list(record.spec.get("entrypoint") or DEFAULT_ENTRYPOINT),"execd": self._execd_image,diff --git a/server/tests/test_templates.py b/server/tests/test_templates.pyindex 6b438d56f..33ef6a237 100644--- a/server/tests/test_templates.py+++ b/server/tests/test_templates.py@@ -252,6 +252,94 @@ def test_create_projects_crd_with_server_side_inputs(service, crs):assert "egressMitmCertificate" not in spec[email protected]("secret", ["sandbox-registry-credentials", "custom-registry"])+def test_create_oci_projects_registry_secret(service, crs, secret):+ service._k8s_config.template_oci_publish_secret = secret+ record = service.create_template(+ _create_request(publish="oci://registry.example.com/team/templates", format="overlaybd")+ )+ output = crs.created[-1]["spec"]["output"]+ assert output["publish"] == record.publish == "oci://registry.example.com/team/templates"+ assert output["format"] == "overlaybd"+ assert output["publishSecretRef"] == {"name": secret}++[email protected]("publish", [+ "oci://registry.example.com/team/templates:latest",+ "oci://registry.example.com/team/templates@sha256:" + "a" * 64,+ "oci://registry.example.com/team/templates:",+ "oci://registry.example.com/team/templates@",+ "oci://registry.example.com/",+ "oci://registry.example.com",+ "oci://user:[email protected]/team/templates",+ "oci://registry.example.com/UPPER",+ "oci://registry.example.com/team//templates",+ "oci://registry.example.com/team/templates?x=1",+ "oci://registry.example.com/team/templates#fragment",+])+def test_create_rejects_invalid_oci_destination_before_side_effects(service, crs, repo, publish):+ with pytest.raises(HTTPException) as excinfo:+ service.create_template(_create_request(publish=publish, format="overlaybd"))+ assert excinfo.value.status_code == 400+ assert excinfo.value.detail["code"] == "SANDBOX::INVALID_PARAMETER"+ assert not crs.created+ assert repo.list(FastSandboxTemplateListQuery(namespace="ns-1")).total_items == 0++[email protected]("publish", [+ "oci://localhost:5000/team/templates",+ "oci://[::1]:5000/team/templates",+ "oci://registry.example.com/team/my__templates-v1",+])+def test_create_accepts_oci_repositories(overlaybd_service, crs, publish):+ overlaybd_service.create_template(_create_request(publish=publish, format="overlaybd"))+ assert crs.created[-1]["spec"]["output"]["publish"] == publish+++def test_create_rejects_native_oci_before_side_effects(service, crs):+ with pytest.raises(HTTPException) as excinfo:+ service.create_template(_create_request(publish="oci://registry.example.com/team/templates"))+ assert excinfo.value.status_code == 400+ assert "S3-compatible" in excinfo.value.detail["message"]+ assert not crs.created++[email protected]("manifest_ref", [+ None,+ "oci://registry.example.com/team/templates:latest",+ "oci://registry.example.com/team/templates@sha256:bad",+ "oci://registry.example.com/other/templates@sha256:" + "a" * 64,+ "s3://bucket/manifest.json",+])+def test_resolve_oci_requires_immutable_manifest_in_publish_repository(+ overlaybd_service, crs, manifest_ref+):+ service = overlaybd_service+ record = service.create_template(+ _create_request(publish="oci://registry.example.com/team/templates", format="overlaybd")+ )+ crs.set_status("ns-1", record.crd_name, {"phase": "Succeeded", "manifestRef": manifest_ref})+ _converge(service, crs, "ns-1", record.crd_name)+ with pytest.raises(HTTPException) as excinfo:+ service.resolve_template_artifact(record.template_id)+ assert excinfo.value.status_code == 404+++def test_oci_builds_from_same_source_resolve_independently(overlaybd_service, crs):+ service = overlaybd_service+ records = [service.create_template(_create_request(+ publish="oci://registry.example.com/team/templates", format="overlaybd",+ )) for _ in range(2)]+ manifests = []+ for record, digit in zip(records, ["a", "b"]):+ manifest_ref = record.publish + "@sha256:" + digit * 64+ manifests.append(manifest_ref)+ crs.set_status("ns-1", record.crd_name, {"phase": "Succeeded", "manifestRef": manifest_ref})+ _converge(service, crs, "ns-1", record.crd_name)+ assert records[0].source_image == records[1].source_image+ assert [service.resolve_template_artifact(record.template_id)[0] for record in records] == manifests++def test_create_bakes_configured_mitm_ca(repo, crs, monkeypatch):monkeypatch.setattr(WorkloadInformer, "start", lambda self: None)with patch.object(K8sClient, "_load_config"):@@ -520,7 +608,7 @@ def test_create_overlaybd_projects_oci_output(overlaybd_service, crs):def test_resolve_overlaybd_returns_manifest_ref(overlaybd_service, crs):record = overlaybd_service.create_template(_overlaybd_request(entrypoint=["sleep", "1"]))- manifest_ref = "oci://registry.example.com/sandbox/templates@sha256:abc123"+ manifest_ref = "oci://registry.example.com/sandbox/templates@sha256:" + "a" * 64crs.set_status("ns-1", record.crd_name, {"phase": "Succeeded", "manifestRef": manifest_ref})_converge(overlaybd_service, crs, "ns-1", record.crd_name)artifact_ref, entrypoint = overlaybd_service.resolve_template_artifact(record.template_id)@@ -618,13 +706,20 @@ def client(service, monkeypatch):yield test_client-def test_routes_template_lifecycle(client, crs, service):[email protected]("oci", [False, True])+def test_routes_template_lifecycle(client, crs, service, oci):+ if oci:+ service._k8s_config.template_oci_publish_secret = "registry-credentials"+ publish = "oci://registry.example.com/team/templates" if oci else "s3://sandbox-images/publish"+ manifest_ref = publish + "@sha256:" + "a" * 64 if oci else "s3://b/m"+ # Omit format for OCI to exercise the public API's overlaybd default.+ format_fields = {} if oci else {"format": "native"}response = client.post("/v1/templates",json={"image": "alpine:3.19",- "publish": "s3://sandbox-images/publish",- "format": "native",+ "publish": publish,+ **format_fields,"env": {"LOG_LEVEL": "info"},"metadata": {"origin": "test"},},@@ -632,16 +727,18 @@ def test_routes_template_lifecycle(client, crs, service):assert response.status_code == 201, response.textbody = response.json()assert body["status"]["phase"] == "Pending"+ assert body["publish"] == publish+ assert body["format"] == ("overlaybd" if oci else "native")assert body["env"] == {"LOG_LEVEL": "info"}template_id = body["templateId"]- crs.set_status("ns-1", template_id, {"phase": "Succeeded", "manifestRef": "s3://b/m"})+ crs.set_status("ns-1", template_id, {"phase": "Succeeded", "manifestRef": manifest_ref})_converge(service, crs, "ns-1", template_id)detail = client.get(f"/v1/templates/{template_id}")assert detail.status_code == 200assert detail.json()["status"]["phase"] == "Succeeded"- assert detail.json()["status"]["manifestRef"] == "s3://b/m"+ assert detail.json()["status"]["manifestRef"] == manifest_refassert detail.json()["env"] == {"LOG_LEVEL": "info"}listing = client.get("/v1/templates", params={"metadata": "origin=test"})@@ -737,13 +834,21 @@ class _StubFastPath:return None-def test_template_mode_create_maps_artifact_and_entrypoint(service, crs):[email protected]("oci", [False, True])+def test_template_mode_create_maps_artifact_and_entrypoint(service, crs, oci):import asynciofrom opensandbox_server.services.fast_sandbox.service import FastSandboxService- record = service.create_template(_create_request(entrypoint=["python", "app.py"]))- crs.set_status("ns-1", record.crd_name, {"phase": "Succeeded", "manifestRef": "s3://b/m"})+ if oci:+ service._k8s_config.template_oci_publish_secret = "registry-credentials"+ publish = "oci://registry.example.com/team/templates" if oci else "s3://b/p"+ manifest_ref = publish + "@sha256:" + "a" * 64 if oci else "s3://b/m"+ record = service.create_template(_create_request(+ entrypoint=["python", "app.py"], publish=publish,+ format="overlaybd" if oci else "native",+ ))+ crs.set_status("ns-1", record.crd_name, {"phase": "Succeeded", "manifestRef": manifest_ref})_converge(service, crs, "ns-1", record.crd_name)with patch.object(K8sClient, "_load_config"):@@ -760,7 +865,7 @@ def test_template_mode_create_maps_artifact_and_entrypoint(service, crs):finally:sandbox_service.close()- assert stub.last_create.image == record.template_id+ assert stub.last_create.image == (manifest_ref if oci else record.template_id)assert list(stub.last_create.command) == ["python", "app.py"]assert stub.last_create.pool_ref == "default-pool"assert response.id.startswith("fsb-")diff --git a/specs/sandbox-lifecycle.yml b/specs/sandbox-lifecycle.ymlindex d9c1a142a..ed6b6896e 100644--- a/specs/sandbox-lifecycle.yml+++ b/specs/sandbox-lifecycle.yml@@ -3184,8 +3184,10 @@ components:type: stringminLength: 1description: |- S3-compatible publish target for the built artifacts,- e.g. `s3://bucket/publish`.+ Publish destination: `s3://bucket/publish` for native artifacts or+ `oci://registry/repository` for overlaybd artifacts. OCI targets+ must not contain a tag or digest; the builder generates unique+ tags per build. Registry credentials are configured on the server.format:type: stringenum: [native, overlaybd]@@ -3205,8 +3207,8 @@ components:manifestRef:type: stringdescription: |- S3 manifest reference of the published artifacts; present when- Succeeded.+ Published S3 manifest reference or immutable OCI reference+ (`oci://registry/repository@sha256:...`); present when Succeeded.message:type: stringdescription: Failure reason when phase is Failed.@@ -3246,7 +3248,7 @@ components:$ref: '#/components/schemas/FsbTemplateReadiness'publish:type: string- description: S3-compatible publish target.+ description: S3-compatible or repository-only OCI publish target.format:type: stringenum: [native, overlaybd]