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 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:

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:

[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

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:

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:

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.