What the image must do
Each invocation starts the command as a new process in the image’s working
directory, with the image’s
Env plus spec.env. The guest is not a normal
container host:
- The root filesystem is read-only.
/tmpand/runare writable in-memory filesystems, so what you write there counts against the microVM’s memory. - An instance is reused for the next call of the same version while it is
warm, so files left in
/tmpand/runcan still be there on the next call. Do not rely on them either way. - The guest has no network unless the function sets
network: EGRESS, which reaches the internet but not private addresses or the cluster. See Isolation.
The spec
An image function’s spec has nosource:
Create the function with the API or the web UI, where you choose Image and
enter the reference:
imageDigest and always runs that digest. Pushing a new image
under the same tag changes nothing until you create a new version with
CreateFunctionVersion or New version in the UI.
Then invoke it like any function:
Private registries
Hosts pull images themselves, in process, without a container daemon. For each registry they look for credentials in this order:- Docker config.
config.jsonin$DOCKER_CONFIG, or~/.dockerwhen it is unset, including its credential helpers. Explicit credentials here win over the cloud providers. - Amazon ECR. The AWS credential chain of the host process: EKS Pod Identity, IRSA or the instance role.
- Google Artifact Registry and Container Registry. Application Default Credentials: Workload Identity or the node’s service account.
DOCKER_CONFIG and a mounted config.json added to
the host Deployment yourself.
A pull that fails, such as an image that does not exist or credentials the
registry refuses, fails the version’s build. Its statusMessage starts with
resolve <reference>: and carries the registry’s error. See
Troubleshooting.
Function images are pulled by hosts, not by Kubernetes, so
imagePullSecrets on the host pod do not apply to them.Image size and start time
A host turns the image into a root filesystem once per image digest:- It resolves the reference and pulls the image’s layers.
- It flattens them into an ext4 file with the supervisor inside, plus 64 MiB
of free space for runtime caches. The version reports its size as
rootfsBytes. - It boots a microVM on it and snapshots it.
DATA_DIR and shared by every
version on the same digest. One host builds it when the version is created,
and every other host builds it the first time it takes an invocation of the
version. That first call on each host pays for the pull and the flattening,
so a larger image makes it slower and takes more disk on every host.
After that, size matters little. An invocation runs on a warm instance of the
version when one is idle, or restores the version’s snapshot. The cost that
remains on every call is starting the process, which is why an interpreter
with heavy imports is slower per call than a static binary. Each invocation
reports how its microVM started as startKind: START_KIND_WARM,
START_KIND_SNAPSHOT_RESTORE or START_KIND_COLD_BOOT.
To keep images small, start from a slim base such as the Alchemy runtimes or
static:13, and leave build tools in a separate build stage as the
Go and Rust
examples do.
Next steps
Runtimes and builds
The full build path from spec to snapshot.
Isolation
What separates one microVM from another and from the host.