Skip to content

Commit b5da48f

Browse files
committed
Address Brad comments: stargz & online prepulling & one-line example
Signed-off-by: manuelbuil <mbuil@suse.com>
1 parent d53c6d3 commit b5da48f

File tree

1 file changed

+9
-14
lines changed

1 file changed

+9
-14
lines changed

blog/2025-11-03-strategies-for-large-images.md renamed to blog/2025-11-11-strategies-for-large-images.md

Lines changed: 9 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,24 +17,15 @@ K3s provides mechanisms for ensuring large images are available quickly, that ad
1717
- Offline (Air-Gapped) Clusters: Where no external registry is available, K3s can `import` images directly from local tarball archives.
1818

1919
1. Pre-Pulling Images via a Manifest File (Online)
20-
In scenarios with internet connectivity, the goal is to initiate image pulls as early and efficiently as possible. K3s can be instructed to sequentially pull a set of images into the embedded containerd store during startup. This is ideal for ensuring base images are ready the moment the cluster starts.
20+
In scenarios with internet connectivity, the goal is to initiate image pulls as early and efficiently as possible. K3s can be instructed to sequentially pull a set of images into the embedded containerd store during startup or while K3s is running. This is ideal for ensuring base images are ready the moment the cluster starts or the moment the application is deployed. However, if this process is done before the cluster is started, K3s won't successfully start until all images have been pulled, which could make K3s fail to start if it takes more than 15 minutes. If you suspect this is happening to you, you'd better do the pre-pulling while K3s is running.
2121

22-
Users can trigger a pull of images into the containerd image store by placing a simple text file containing the image names, one per line, in the /var/lib/rancher/k3s/agent/images directory. This can be done before K3s starts or while K3s is running.
23-
24-
Imagine the file `example.txt` which contains:
25-
26-
```text
27-
docker.io/pytorch/pytorch:2.9.0-cuda12.6-cudnn9-runtime
28-
```
29-
Before starting the k3s service in the node, do the following:
22+
Users can trigger a pull of images into the containerd image store by placing a simple text file containing the image names, one per line, in the `/var/lib/rancher/k3s/agent/images` directory. As we have just explained, this can be done before K3s starts or while K3s is running. For example, you can execute the following in one of the nodes:
3023

3124
```bash
32-
# 1. Create the images directory on the node
33-
mkdir -p /var/lib/rancher/k3s/agent/images
34-
35-
# 2. Copy the manifest file (example.txt)
36-
cp example.txt /var/lib/rancher/k3s/agent/images
25+
mkdir -p /var/lib/rancher/k3s/agent/images && echo docker.io/pytorch/pytorch:2.9.0-cuda12.6-cudnn9-runtime > /var/lib/rancher/k3s/agent/images/pytorch.txt
3726
```
27+
In the previous command, we have created the images directory on the node and dropped a file names `pytorch.txt` that contains the image: `docker.io/pytorch/pytorch:2.9.0-cuda12.6-cudnn9-runtime`.
28+
3829
The K3s process will then pull these images via the CRI API. You should see the following two logs:
3930
```log
4031
# When the k3s controller detects the file
@@ -110,7 +101,11 @@ And you should be able to see metrics of Spegel by querying the supervisor metri
110101
```bash
111102
kubectl get --server https://10.11.0.11:6443 --raw /metrics | grep spegel
112103
```
104+
## Bonus: eStargz images ⚡ ##
105+
106+
A different solution to speed up the creation of pods is by using a special image format called eStargz. This enables lazy pulling, which means that the application can start almost instantly while the rest of the image is pulled in the background. This strategy requires both the image to be specifically built in the eStargz format and the K3s agent to be configured to use the stargz snapshotter: `--snapshotter=estargz` flag, or with `snapshotter: estargz` in the configuration file.
113107

108+
This is currently an experimental feature in K3s and we have more information in the [advance section of our docs](https://docs.k3s.io/advanced#enabling-lazy-pulling-of-estargz-experimental). We would love to hear your feedback if you are using it.
114109

115110
## Conclusion 🏁 ##
116111

0 commit comments

Comments
 (0)