Skip to content

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.md
index b979719c6..18a43000e 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -202,7 +202,8 @@ osb sandbox create -f sandbox-request.json -o json
Templates 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 json
osb template get <template-id> -o json
osb template list -o json
osb 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 snapshots
Snapshots 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.py
index 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.md
index 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 th
Templates 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 json
osb template create -f template-request.json -o json
osb template get <template-id> -o json
osb template list -o json
@@ -149,6 +150,8 @@ osb template delete <template-id> -o json
Useful `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 json
Build 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 json
osb template get <template-id> -o json
osb sandbox create --template <template-id> --timeout 30m -o json
osb sandbox health <sandbox-id> -o json
diff --git a/cli/tests/test_cli_help.py b/cli/tests/test_cli_help.py
index 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.py
index 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.mts
index 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.md
index 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 templates
Sandbox 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.md
index 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 json
Templates 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 json
osb template get <template-id> -o json
osb template list -o json
osb 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 snapshots
Snapshots capture a sandbox's state and can back new sandboxes.
diff --git a/docs/guides/oci-templates.md b/docs/guides/oci-templates.md
new file mode 100644
index 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.cs
index 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 TemplateStatus
public 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 CreateTemplateRequest
public 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 TemplateInfo
public 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.go
index 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 when
diff --git a/sdks/sandbox/javascript/src/api/lifecycle.ts b/sdks/sandbox/javascript/src/api/lifecycle.ts
index 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.ts
index 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.kt
index 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 created
diff --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.py
index 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 Kubernetes
resource 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.py
index 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.py
index 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.py
index 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.md
index 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.py
index 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 None
if 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, entrypoint
manifest_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.py
index 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" * 64
crs.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.text
body = 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 == 200
assert detail.json()["status"]["phase"] == "Succeeded"
- assert detail.json()["status"]["manifestRef"] == "s3://b/m"
+ assert detail.json()["status"]["manifestRef"] == manifest_ref
assert 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 asyncio
from 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.yml
index d9c1a142a..ed6b6896e 100644
--- a/specs/sandbox-lifecycle.yml
+++ b/specs/sandbox-lifecycle.yml
@@ -3184,8 +3184,10 @@ components:
type: string
minLength: 1
description: |
- 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: string
enum: [native, overlaybd]
@@ -3205,8 +3207,8 @@ components:
manifestRef:
type: string
description: |
- 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: string
description: 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: string
enum: [native, overlaybd]