@@ -3,54 +3,131 @@ title: containerd image store with Docker Engine
33linkTitle : containerd image store
44weight : 50
55keywords : containerd, snapshotters, image store, docker engine
6- description : Learn how to enable the containerd image store on Docker Engine
6+ description : Learn about the containerd image store
77aliases :
88 - /storage/containerd/
99---
1010
11- {{< summary-bar feature_name="containerd" >}}
11+ The containerd image store is the default storage backend for Docker Engine
12+ 29.0 and later on fresh installations. If you upgraded from an earlier version,
13+ your daemon continues using the legacy graph drivers (overlay2) until you
14+ enable the containerd image store.
1215
1316containerd, the industry-standard container runtime, uses snapshotters instead
14- of the classic storage drivers for storing image and container data.
15- While the ` overlay2 ` driver still remains the default driver for Docker Engine,
16- you can opt in to using containerd snapshotters as an experimental feature.
17+ of classic storage drivers for storing image and container data.
1718
18- To learn more about the containerd image store and its benefits, refer to
19- [ containerd image store on Docker Desktop] ( /manuals/desktop/features/containerd.md ) .
19+ > [ !NOTE]
20+ > The containerd image store is not available when using user namespace
21+ > remapping (` userns-remap ` ). See
22+ > [ moby #47377 ] ( https://github.com/moby/moby/issues/47377 ) for details.
23+
24+ ## Why use the containerd image store
25+
26+ The containerd image store uses snapshotters to manage how image layers are
27+ stored and accessed on the filesystem. This differs from the classic graph
28+ drivers like overlay2.
29+
30+ The containerd image store enables:
31+
32+ - Building and storing multi-platform images locally. With classic storage
33+ drivers, you need external builders for multi-platform images.
34+ - Working with images that include attestations (provenance, SBOM). These use
35+ image indices that the classic store doesn't support.
36+ - Running Wasm containers. The containerd image store supports WebAssembly
37+ workloads.
38+ - Using advanced snapshotters. containerd supports pluggable snapshotters that
39+ provide features like lazy-pulling of images (stargz) or peer-to-peer image
40+ distribution (nydus, dragonfly).
41+
42+ For most users, switching to the containerd image store is transparent. The
43+ storage backend changes, but your workflows remain the same.
2044
2145## Enable containerd image store on Docker Engine
2246
23- Switching to containerd snapshotters causes you to temporarily lose images and
24- containers created using the classic storage drivers.
25- Those resources still exist on your filesystem, and you can retrieve them by
26- turning off the containerd snapshotters feature.
47+ If you're upgrading from an earlier Docker Engine version, you need to manually
48+ enable the containerd image store.
2749
28- The following steps explain how to enable the containerd snapshotters feature.
50+ > [ !IMPORTANT]
51+ > Switching storage backends temporarily hides images and containers created
52+ > with the other backend. Your data remains on disk. To access the old images
53+ > again, switch back to your previous storage configuration.
2954
30- 1 . Add the following configuration to your ` /etc/docker/daemon.json `
31- configuration file:
55+ Add the following configuration to your ` /etc/docker/daemon.json ` file:
3256
33- ``` json
34- {
35- "features" : {
36- "containerd-snapshotter" : true
37- }
38- }
39- ```
57+ ``` json
58+ {
59+ "features" : {
60+ "containerd-snapshotter" : true
61+ }
62+ }
63+ ```
4064
41- 2 . Save the file.
42- 3 . Restart the daemon for the changes to take effect.
65+ Save the file and restart the daemon:
4366
44- ``` console
45- $ sudo systemctl restart docker
46- ```
67+ ``` console
68+ $ sudo systemctl restart docker
69+ ```
4770
48- After restarting the daemon, running ` docker info ` shows that you're using
49- containerd snapshotter storage drivers.
71+ After restarting the daemon, verify you're using the containerd image store:
5072
5173``` console
5274$ docker info -f ' {{ .DriverStatus }}'
5375[[driver-type io.containerd.snapshotter.v1]]
5476```
5577
5678Docker Engine uses the ` overlayfs ` containerd snapshotter by default.
79+
80+ > [ !NOTE]
81+ > When you enable the containerd image store, existing images and containers
82+ > from the overlay2 driver remain on disk but become hidden. They reappear if
83+ > you switch back to overlay2. To use your existing images with the containerd
84+ > image store, push them to a registry first, or use ` docker save ` to export
85+ > them.
86+
87+ ## Experimental automatic migration
88+
89+ Docker Engine includes an experimental feature that can automatically switch to
90+ the containerd image store under certain conditions. ** This feature is
91+ experimental** . It's provided for those who want to test it, but [ starting
92+ fresh] ( #enable-containerd-image-store-on-docker-engine ) is the recommended
93+ approach.
94+
95+ > [ !CAUTION]
96+ > The automatic migration feature is experimental and may not work reliably in
97+ > all scenarios. Create backups before attempting to use it.
98+
99+ To enable automatic migration, add the ` containerd-migration ` feature to your
100+ ` /etc/docker/daemon.json ` :
101+
102+ ``` json
103+ {
104+ "features" : {
105+ "containerd-migration" : true
106+ }
107+ }
108+ ```
109+
110+ You can also set the ` DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD ` environment
111+ variable to make the daemon switch automatically if you have no containers and
112+ your image count is at or below the threshold. For systemd:
113+
114+ ``` console
115+ $ sudo systemctl edit docker.service
116+ ```
117+
118+ Add:
119+
120+ ``` ini
121+ [Service]
122+ Environment =" DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=5"
123+ ```
124+
125+ If you have no running or stopped containers and 5 or fewer images, the daemon
126+ switches to the containerd image store on restart. Your overlay2 data remains
127+ on disk but becomes hidden.
128+
129+ ## Additional resources
130+
131+ To learn more about the containerd image store and its capabilities in Docker
132+ Desktop, see
133+ [ containerd image store on Docker Desktop] ( /manuals/desktop/features/containerd.md ) .
0 commit comments