Document auto-import images feature (#430)

* Add information about importing images

---------

Signed-off-by: manuelbuil <mbuil@suse.com>

Author: manuelbuil

docs/import-images.md

@@ -0,0 +1,71 @@
+---
+title: "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](https://kubernetes.io/docs/concepts/containers/images/#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](installation/private-registry.md) 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
+:::info 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:
+
+<Tabs groupId = "import images" queryString>
+<TabItem value="Online image importing" default>
+
+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](installation/private-registry.md) configuration.
+
+For example:
+
+```bash
+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.
+
+</TabItem>
+<TabItem value="Offline image importing">
+
+Users can import images directly into the containerd image store by placing image tarballs in the `/var/lib/rancher/k3s/agent/images` directory. The tarball can be placed before K3s is started, or created/modified while K3s is running. K3s will decompress the image tarball if necessary, extract the images, and load them into the containerd image store.
+
+For example:
+
+```bash
+mkdir /var/lib/rancher/k3s/agent/images
+curl  https://github.com/k3s-io/k3s/releases/download/v1.33.1%2Bk3s1/k3s-airgap-images-amd64.tar.zst -O  /var/lib/rancher/k3s/agent/images/k3s-airgap-images-amd64.tar.zst
+```
+
+After a few seconds, the images included in the image tarball will be available in the containerd image store of the node. 
+
+Use `sudo k3s ctr images list` to query the containerd image store.
+
+This is the method used in Airgap. Please follow the [Airgap install documentation](installation/airgap.md) for detailed information.
+
+</TabItem>
+</Tabs>
+
+## Set up an image registry
+
+K3s supports two alternatives for image registries:
+
+* [Private Registry Configuration](installation/private-registry.md) covers use of `registries.yaml` to configure container image registry authentication and mirroring.
+
+* [Embedded Registry Mirror](installation/registry-mirror.md) shows how to enable the embedded distributed image registry mirror, for peer-to-peer sharing of images between nodes.

docs/installation/installation.md

@@ -6,9 +6,9 @@ This section contains instructions for installing K3s in various environments. P
 
 [Configuration Options](configuration.md) provides guidance on the options available to you when installing K3s.
 
-[Private Registry Configuration](private-registry.md) covers use of `registries.yaml` to configure container image registry mirrors.
+[Private Registry Configuration](private-registry.md) covers use of `registries.yaml` to configure container image registry authentication and mirroring.
 
-[Embedded Mirror](registry-mirror.md) shows how to enable the embedded distributed image registry mirror.
+[Embedded Registry Mirror](registry-mirror.md) shows how to enable the embedded distributed image registry mirror, for peer-to-peer sharing of images between nodes.
 
 [Air-Gap Install](airgap.md) details how to set up K3s in environments that do not have direct access to the Internet.
 

docs/installation/registry-mirror.md

@@ -16,9 +16,7 @@ This option enables the embedded mirror for use on all nodes in the cluster.
 When enabled at a cluster level, all nodes will host a local OCI registry on port 6443,
 and publish a list of available images via a peer to peer network on port 5001.
 Any image available in the containerd image store on any node, can be pulled by other cluster members without access to an external registry.
-<!-- Note: Not a regular markdown header because it exists inside a Tabs structure, access it via queryString-->
-Images imported via [air-gap image tar files](./airgap.md?airgap-load-images=Manually+Deploy+Images) are pinned in containerd to
-ensure that they remain available and are not pruned by Kubelet garbage collection.
+Images imported via [air-gap image tar files](./airgap.md?airgap-load-images=Manually+Deploy+Images) or [pre-imported](../import-images.md#pre-import-images) are pinned in containerd to ensure that they remain available and are not pruned by Kubelet garbage collection.
 
 The peer to peer port can changed from 5001 by setting the `K3S_P2P_PORT` environment variable for the K3s service. The port must be set to the same value on all nodes.
 Changing the port is unsupported and not recommended.
@@ -130,9 +128,8 @@ If image integrity is important, you should use image digests instead of tags, a
 
 ## Sharing Air-gap or Manually Loaded Images
 
-Images sharing is controlled based on the source registry.
-Images loaded directly into containerd via air-gap tarballs, or loaded directly into containerd's image store using the `ctr` command line tool,
-will be shared between nodes if they are tagged as being from a registry that is enabled for mirroring.
+Image sharing is controlled based on the source registry.
+Images loaded directly into containerd via [air-gap tarballs](./airgap.md?airgap-load-images=Manually+Deploy+Images), [pre-imported](../import-images.md#pre-import-images) or loaded directly into containerd's image store using the `ctr` command line tool, will be shared between nodes if they are tagged as being from a registry that is enabled for mirroring.
 
 Note that the upstream registry that the images appear to come from does not actually have to exist or be reachable.
 For example, you could tag images as being from a fictitious upstream registry, and import those images into containerd's image store.
@@ -143,5 +140,5 @@ You would then be able to pull those images from all cluster members, as long as
 The embedded registry is read-only, and cannot be pushed to directly using `docker push` or other common tools that interact with OCI registries.
 
 Images can be manually made available via the embedded registry by running `ctr -n k8s.io image pull` to pull an image,
-or by loading image archives created by `docker save` via the `ctr -n k8s.io image import` command.
+or by loading image archives created by `docker save` via the `ctr -n k8s.io image import` command or the [pre-import feature](../import-images.md#pre-import-images).
 Note that the `k8s.io` namespace must be specified when managing images via `ctr` in order for them to be visible to the kubelet.

sidebars.js

@@ -65,6 +65,7 @@ module.exports = {
     'architecture',
     'cluster-access',
     'storage',
+    'import-images',
     {
       type: 'category',
       label: 'Networking',