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.tarThen look at what the cluster recorded:
k3sm image ls
k3sm image dfk3sm 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 image | rejected. 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 archive | rejected for the same reason: one archive, one image |
| naming | taken 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 provenance | none evaluated. This is an operator-only surface, and what it stores is exactly what you handed it |
| a running daemon | required; 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#
- serving a model with MLX is the next tutorial.
- images is the reference page, including the rest of the OCI roadmap.