Register a custom image
You're going to register your own image from an OCI reference (for example docker.io/r-base:4.4), wait for ScaiBunker to build and scan it, make it available to your workers, and then create a bunker from it.
Roughly 5 minutes, plus the build time: under a minute for small images, a few minutes for large ones.
How a custom image is built#
You don't upload a disk image, and your workers never pull from a registry. ScaiBunker's build service takes your reference (or your uploaded archive) and:
- pulls the image (linux/amd64 only), or unpacks your archive, and checks every layer against its digest;
- flattens the layers into one root filesystem, dropping anything unsafe (device files, paths that escape the filesystem);
- builds an ext4 disk sized to the content (25% plus 128 MiB headroom);
- boots it in a Firecracker microVM without network to check it starts and has a shell;
- scans it for known vulnerabilities and records a software bill of materials;
- publishes it, after which your workers import the checked image.
The image is refused if:
- it has no
/bin/sh(for example distroless orscratchimages): bunkers need a shell; - the scan finds a critical vulnerability that has a fix available: rebuild it from an updated base;
- it's private and ScaiBunker has no login for its registry (see Private registries), or the login is refused;
- it's larger than 20 GiB once flattened.
Because the scan happens here, on the way in, ScaiBunker doesn't re-scan the image later. A new version of your image is a new registration, with its own build and scan.
1. Decide the image's shape#
Settle these before the API call:
- Source.
{"kind": "oci", "ref": "docker.io/r-base:4.4"}. Pin a tag or a digest (...@sha256:…); the build uses whatever the reference points at when it runs. For an image that isn't in any registry, upload it instead: see Upload an archive. - Defaults.
default_cpu_millicores,default_memory_mb,default_disk_mbare applied when a caller creates a bunker from this image without overriding. Set them to a sensible "this image needs at least this to function" floor. - Scope.
tenant(default) — only this tenant sees it.partner— every tenant under your partner (needs a partner admin).
You need scaibunker:images:manage to register a new image.
2. Register the image#
1 2 3 4 5 6 7 8 9 10 11 12 | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | |
Names are unique per scope; reusing one returns 409 IMAGE_NAME_CONFLICT. Any other source kind returns 422 IMAGE_SOURCE_UNSUPPORTED.
Private registries#
To build from a private registry, store a login for it once. ScaiBunker uses it only when building your images, sends it only to that registry, and never returns it:
1 2 3 4 | |
host is the registry part of your references (ghcr.io, registry.example.com:5000; Docker Hub is docker.io). Use a read-only token. From then on, register images from that registry as usual; the build logs in by itself. Change the token with PATCH /registry-credentials/{id}, remove it with DELETE. A refused login fails the build with registry refused the stored credentials.
Upload an archive#
For an image that isn't in a registry, upload the output of docker save (or an OCI image layout as a tar, optionally gzipped) holding exactly one linux/amd64 image:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
The image is uploading until you call upload/complete, then the build runs as for a reference. Above 5 GiB the response holds upload.multipart instead: send each part_size slice to its part URL and pass the parts' ETags to upload/complete ({"parts": [{"part_number": 1, "etag": "…"}]}). Expired URLs can be renewed with GET /images/{id}/upload. Finish within 24 hours, or the image fails and the upload is deleted; the archive is also deleted once the build ends.
3. Wait for the build#
Poll the image until build_status is ready or failed:
1 2 | |
uploading— waiting for your archive (archives only).queued— waiting for the build service.building— being built.ready— built, scanned and published.failed—build_errorsays why, for exampleimage has no /bin/sh,fixable CRITICAL vulnerabilitiesorpull failed: …. Fix the cause and register again under a new name.
Creating a bunker from an image that isn't ready returns 409 IMAGE_NOT_READY.
Once the image is ready, scan_status shows the result of its build scan within a couple of minutes: passed (no critical or high findings) or failed (high findings, which are reported but don't block the image), with the counts in scan_report.
4. Make it available to your workers#
Images are imported by the workers in the image's availability groups. If your tenant's images don't sit in a group yet, create one and put the image in it:
1 2 3 4 5 6 7 8 9 10 11 | |
A built image in a group is imported automatically. To start or repeat that yourself:
1 2 | |
Then watch one row per worker until every row is ready:
1 2 | |
5. Create a bunker from the new image#
Reference the image by name or id. The scheduler picks a worker that has it.
1 2 3 4 5 6 7 8 | |
If no worker has the image yet, the call fails with NO_SUITABLE_WORKER: wait for step 4 to finish.
6. Deactivate when retiring#
1 2 | |
Deactivation is a soft delete: existing bunkers keep running, but new bunkers can't be created from it. ScaiBunker also removes the image from your workers within a minute; each worker frees the disk once the last bunker on the image ends.
Done#
Your image is built, checked, scanned and ready. To update it, register the new version under a new name; there's no in-place update, so each version keeps its own build and scan.