본문으로 건너뛰기

Import images

Container images are cached locally on each node by the containerd image store. Images can be pulled from the registry as needed by pods, preloaded via image pull, or imported from an image tarball.

On-demand image pulling​

Kubernetes, by default, automatically pulls images when a Pod requires them if the image is not already present on the node. This behavior can be changed by using the image pull policy field of the Pod. When using the default IfNotPresent policy, containerd will pull the image from either upstream (default) or your private registry and store it in its image store. Users do not need to apply any additional configuration for on-demand image pulling to work.

Pre-import images​

Version Gate

The pre-importing of images while K3s is running feature is available as of January 2025 releases: v1.32.0+k3s1, v1.31.5+k3s1, v1.30.9+k3s1, v1.29.13+k3s1. Before that, K3s pre-imported the images only when booting.

Pre-importing images onto the node is essential if you configure Kubernetes' imagePullPolicy as Never. You might do this for security reasons or to reduce the time it takes for your K3s nodes to spin up.

K3s includes two mechanisms to pre-import images into the containerd image store:

Users can trigger a pull of images into the containerd image store by placing a text file containing the image names, one per line, in the /var/lib/rancher/k3s/agent/images directory. The text file can be placed before K3s is started, or created/modified while K3s is running. K3s will sequentially pull the images via the CRI API, optionally using the registries.yaml configuration.

For example:

mkdir /var/lib/rancher/k3s/agent/images
cp example.txt /var/lib/rancher/k3s/agent/images

Where example.txt contains:

docker.io/library/redis:latest
docker.io/library/mysql:latest

After a few seconds, the redis and the mysql images will be available in the containerd image store of the node.

Use sudo k3s ctr images list to query the containerd image store.

Set up an image registry​

K3s supports two alternatives for image registries:

  • Private Registry Configuration covers use of registries.yaml to configure container image registry authentication and mirroring.

  • Embedded Registry Mirror shows how to enable the embedded distributed image registry mirror, for peer-to-peer sharing of images between nodes.