k3sm

Loading an image into a node

Ingest a docker-save tarball or an OCI layout into the cluster registry, see it recorded, and run a Pod from it on any node.


About 10 minutes, and you need an installed, running cluster first (the archive is uploaded to the server’s registry, and this node’s cache is filled by its runtime daemon). You end up with an image recorded in the cluster registry as registry-k3sm:6450/<repository>:<tag>, the cluster’s one image store, and pulled into this node’s cache, verified byte by byte on the way in.

Loaded content is runnable. Once the load succeeds and k3sm image ls shows the reference, a Pod on any node naming registry-k3sm:6450/<repository>:<tag> runs on the default runtime, and the node materializes the stored layers into the Pod’s filesystem. imagePullPolicy still decides what a reference means, the way it does on any Kubernetes. On this node IfNotPresent and Never serve the cached content with no registry traffic, while Always, the apiserver’s default for a :latest tag, goes to the registry regardless of what the node holds. Tag loaded images with something other than latest, or set the policy explicitly. Loading stages content for an airgapped cluster, and it ships a workload without an outside registry.

Two Verbs, Two Formats#

There is no format sniffing. A layout handed to load, or a docker-save tar handed to import, is refused with an error naming the other verb.

# a docker-save tar, from k3sm build or from docker save
k3sm build --tag myapp:v1 --output myapp.tar .
k3sm image load myapp.tar

docker save myapp:v1 -o from-docker.tar
k3sm image load from-docker.tar

# a tarred OCI layout
k3sm build --tag myapp:v1 --output ./layout --format oci .
tar -cf layout.tar -C ./layout .
k3sm image import layout.tar

Then look at what the cluster recorded:

k3sm image ls
k3sm image df

k3sm image also carries push and prune. Run k3sm image --help for the current flags on each.

What Happens to Your Archive#

The CLI reads the archive as you and uploads it to the server’s registry under the registry-k3sm:6450 name, overwriting whatever that tag named before. It then has this node’s runtime daemon pull the image into the node’s cache through its ordinary puller, which re-hashes every blob against its digest before it records anything.

Refusals#

k3sm image load and import
two tags on one imagerejected. The store records one reference per loaded image, with both tags named in the error; re-save with a single tag, or load once per tag
two images in one archiverejected for the same reason: one archive, one image
namingtaken from the archive, so RepoTags for docker-save and the ref-name annotation for an OCI layout; --reference overrides it, and is required for a layout that carries no annotation
signatures and provenancenone evaluated. This is an operator-only surface, and what it stores is exactly what you handed it
a running daemonrequired; load works against an installed node, not a bare directory
deadline--timeout defaults to 30 minutes for these two verbs, which stream a whole archive, and 2 minutes for the metadata verbs

Next#