Uploaded images

Upload a container image — a docker save archive or an OCI image-layout tar — or a WebAssembly module (.wasm) through the console, the API or runr images push, and RunR pushes it into a region's registry. The file travels through RunR to the region, chunk by chunk, so a region that has no route to the internet (or to any registry outside it) gets its images this way. An uploaded image is then used like any other:

• as the image of a CaaS project (the CaaS form offers the region's uploaded images next to a registry reference);
• as the image of a runtime version (upload: in the runtime manifest, Runtimes);
• as the module of a wasm-exec function (wasm.upload, WebAssembly) or of a WebAssembly runtime that ships an interpreter (Q on Wasm, examples/wasm/q-exec).

Uploaded container images go through the supply chain like the images RunR builds: SBOM, vulnerability scan, signature.

• How it works
• Formats
• Upload
• Resume and verification
• Using uploaded images
• Supply chain and data residency
• Quota, replacing and deleting
• Air-gapped regions
• Permissions
• Audit
• API
• Configuration
• Data model
• Testing

How it works#

console / runr images push / API
  └─ POST /api/images/uploads {knative_region_id, filename, size, sha256, name}
       └─ region: Job image-recv-<id> (runr-image-upload serve) + Service, emptyDir /work
  └─ PUT /api/images/uploads/{id}/chunk?offset=N  (raw bytes, 8 MiB)
       └─ RunR API → Kubernetes API server → service proxy → receiver: written at offset N
          (nothing is stored on the RunR API's disk; the region needs no route to RunR)
  └─ POST /api/images/uploads/{id}/complete
       └─ receiver: size + SHA-256 → format → push into the region registry
          <registry>/runr-uploads/<owner>/<repository>:<tag>  →  digest read back from the registry
  └─ CheckImageUploadJob (every 5 s) reads the receiver's status
       └─ uploaded_images row, audit event, supply-chain run, receiver removed

The receiver (runtime/image-upload, image ghcr.io/brf-tech/runr/image-upload) is one static Go binary built on go-containerregistry. Its pod has no Kubernetes API access, runs as a non-root user with a read-only root filesystem and no capabilities, and uses the region's build RuntimeClass — gVisor or Kata where builds are sandboxed, since archive content from users is unpacked there.

The repository in the registry belongs to the owner of the upload: runr-uploads/<tenant id>/… for an organization of a multi-tenant install, runr-uploads/platform/… outside a tenant (single-tenant installs, and platform administrators in the central console). Users see and use their own owner's images only.

Formats#

Multi-platform images. An image index is pushed with every platform. docker save of a multi-platform image may carry the layers of the local platform only; the receiver then pushes the platforms whose blobs are all in the archive — one as that platform's image, several as a new index — and the uploaded image's note says which. To keep every platform, export the index:

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.0 --output type=oci,dest=myapp.tar .
# or, from a registry you can reach:
skopeo copy --all docker://registry.example.com/myapp:1.0 oci-archive:myapp.tar

Archives with several images. A layout or archive holding several images is narrowed to the one named like the upload's tag (org.opencontainers.image.ref.name / io.containerd.image.name, or the RepoTags of a classic archive); otherwise the upload fails asking for one image per file.

Upload#

Console: Settings → Images → Upload image: region, file, name (repository[:tag], from the file name by default) and format (detected). The dialog shows the progress, the verification and the push; unfinished uploads stay listed with Resume and Abort.

CLI (CLI):

docker save myapp:1.0 -o myapp.tar
runr images push myapp.tar --region eu-1 --name myapp:1.0
runr images ls
runr images rm myapp:1.0 --region eu-1

API (any HTTP client; $API is https://<console>/api):

size=$(stat -c %s myapp.tar); sum=$(sha256sum myapp.tar | cut -d' ' -f1)
id=$(curl -sS -X POST "$API/images/uploads" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d "{\"knative_region_id\":\"$REGION\",\"filename\":\"myapp.tar\",\"size\":$size,\"sha256\":\"$sum\",\"name\":\"myapp:1.0\"}" | jq -r .data.id)
# wait until GET $API/images/uploads/$id answers status "ready", then send 8 MiB chunks:
split -b 8388608 -d myapp.tar part.
offset=0
for part in part.*; do
  curl -sS -X PUT "$API/images/uploads/$id/chunk?offset=$offset" -H "Authorization: Bearer $TOKEN" \
    -H 'Accept: application/json' -H 'Content-Type: application/octet-stream' --data-binary @"$part"
  offset=$((offset + $(stat -c %s "$part")))
done
curl -sS -X POST "$API/images/uploads/$id/complete" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'
# poll GET $API/images/uploads/$id until status is "completed" (data.image) or "failed" (data.message)

A WebAssembly module goes the same way: runr images push q.wasm --name q-interpreter:1.0.

Resume and verification#

• Chunks are written at their offset: they may arrive in any order and be sent again. The receiver merges the byte ranges it has; uploaded_bytes is the part from byte 0 without a gap — where a client goes on after a reload or a broken connection (the console and runr images push do this by themselves: push finds the unfinished upload of the same file by name, region, size and SHA-256).
• complete is refused until every byte is there (code: upload_incomplete, with uploaded_bytes).
• The receiver checks the size and the SHA-256 the upload declared. A mismatch reopens the upload with nothing received (status ready, the message names both digests): send the file again.
• The registry checks every blob against its digest when it is pushed, so a damaged layer fails the push; afterwards the receiver reads the tag back and requires the digest of what it pushed.
• An upload not completed within RUNR_IMAGE_UPLOAD_TTL_HOURS (24) is aborted and its receiver removed (hourly).

Using uploaded images#

References into runr-uploads/ of the region registry are checked: a CaaS project may run an uploaded image of its own organization in its own region only, and registering a runtime with an upload: version requires that image in every region the runtime is offered in (platform runtimes name platform uploads, custom runtimes their organization's). A deploy or a build in a region without the image fails with a message naming the region.

Supply chain and data residency#

• Scan and signature. When an upload of a container image finishes, the region's supply-chain pipeline runs on it (report subject uploaded_image, kind uploaded): SBOM, SBOM referrers, vulnerability scan, signature and attestations as the region's settings define — the full pipeline of a build, since the image is in RunR's own registry. Settings → Images shows the scan; re-scans follow the region's interval. A CaaS version that runs an uploaded image gets its own report of the same kind, so the policy gate (and Verify the signature on deploy) applies to it like to a build. The admission policy's runr-signed-images covers <registry>/runr-uploads/**. WebAssembly modules are not scanned (no container filesystem).
• Data residency. Starting an upload checks the organization's residency policy for the region (action image.upload); a refusal answers 422 with code: region_not_allowed.

Quota, replacing and deleting#

• Quota. An organization (the install, when single-tenant) stores up to RUNR_IMAGES_QUOTA_GB (50 GiB) of uploaded images over every region: the size of its images plus the declared size of uploads still running. An upload that does not fit is refused (code: quota_exceeded); replacing an image of the same name gives its size back first. Settings → Images and GET /api/images/quota show the use.
• Replacing. Uploading the same repository:tag into the same region again replaces the image; the manifest it replaced is removed from the registry unless another tag of the owner points at the same digest.
• Deleting. DELETE /api/images/{id} (Settings → Images, runr images rm) removes the record and the manifest in the region registry (RegistryImageLifecycleService, as the build retention removes old builds; Zot frees the blobs with its garbage collection). It is refused (409, code: image_in_use) while a CaaS project or a runtime version still uses the image — the answer names them.

Air-gapped regions#

1. On a machine that reaches the image's registry: docker pull myapp:1.0 && docker save myapp:1.0 -o myapp.tar (or skopeo copy --all docker://… oci-archive:myapp.tar for every platform).
2. Bring the file to a machine that reaches the RunR console, and upload it (console, CLI or API).
3. The region pulls nothing from outside: the receiver image itself must be in a registry the region reaches — mirror ghcr.io/brf-tech/runr/image-upload:1.0.0 into the region registry or your own mirror and set RUNR_IMAGE_UPLOAD_IMAGE (Helm images.uploadImage).
4. Run it: a CaaS project on the uploaded image, or a runtime version / wasm-exec function on it.

Permissions#

Using an uploaded image in a project or a runtime needs nothing beyond changing that project or runtime (Roles and permissions).

Audit#

Chunks are not audited (one event per upload is enough); the upload's start, completion and result are.

API#

All under /api, authenticated with a session or an API token; rules in api/config/route_permissions.php.

An uploaded image:

{
  "id": "01JB…", "name": "myapp:1.0", "repository": "myapp", "tag": "1.0",
  "knative_region_id": "01JA…", "region_name": "eu-1",
  "image_ref": "10.43.0.5:5000/runr-uploads/platform/myapp@sha256:…",
  "tag_ref": "10.43.0.5:5000/runr-uploads/platform/myapp:1.0",
  "digest": "sha256:…", "media_type": "application/vnd.oci.image.index.v1+json",
  "kind": "image", "source_format": "oci", "size_bytes": 52428800, "archive_bytes": 60000000,
  "platforms": ["linux/amd64", "linux/arm64"], "layers": 4, "source_filename": "myapp.tar",
  "note": null, "security": {"status": "completed", "scan_status": "ok", "counts": {"critical": 0, "high": 2}},
  "created_at": "2026-10-11T08:00:00Z"
}

Configuration#

The images.* Helm values are empty by default, which keeps the defaults above (api/config/images.php).

The receiver's emptyDir (and ephemeral-storage request) is twice the file plus 512 MiB — the file and, for OCI layouts and gzip'ed archives, its extracted copy; a .wasm needs the file only. Uploads need the region's internal registry (registry_mode: internal, status ready).

Data model#

The supply-chain reports of uploaded images are in image_security_reports of the central schema.

Testing#

• Receiver: cd runtime/image-upload && go vet ./... && go test ./... — chunks in any order and the contiguous prefix, refused chunks, SHA-256 mismatch, failed pushes; pushes into an in-memory OCI registry of docker save archives (gzip'ed, several images), OCI layouts, multi-platform indexes (complete and partial), .wasm modules and the fetch of a module.
• API: cd api && php artisan test tests/Feature/Images tests/Unit/Images tests/Feature/Runtimes/RuntimeUploadSourceTest.php tests/Feature/Wasm/WasmExecTest.php tests/Unit/Wasm/WagiSpinManifestTest.php — the receiver Job and Service, chunk forwarding and resume, complete → push → uploaded image, replacing a name, SHA-256 mismatch, failed pushes, abort / expiry, registry / quota / residency checks, permissions; listing, deletion with the manifest and the in-use refusal, owner scoping, CaaS validation and the supply-chain kind; the runtime upload source; wasm-exec builds.
• CLI: cd cli && go test ./internal/cmd ./pkg/runr -run 'Images|NameFromFilename|FindImage|PushImage' against the fake API.
• UI: cd vue && npx vitest run tests/modules/images and npx playwright test e2e/images.spec.ts --project=mock.
• End to end: KIND_LOCK=/tmp/runr-kind.lock bash runtime/ci.sh test-images [--k8s=X.Y.Z] [--no-cleanup] uploads a docker save archive and q.wasm into a Kind region, runs a CaaS project from the upload, a wasm-exec function in C and a Q (Wasm) function, and deletes everything again.