Runbook: Migrate to the containerd image store

1 · Prerequisites

Confirm every item is in place before any state change.

• A maintenance window exists, because the daemon must be restarted
• Every image the host needs is either present in a registry you can pull from, or exported to a tar archive you have verified
• You know which containers run on this host and can recreate them from compose files in version control
• Free disk space is at least the total image size again, because containerd holds compressed and uncompressed layers
• You know whether the daemon uses userns-remap, which is not compatible with the containerd image store
• You have console or out-of-band access, so a daemon that fails to start does not lock you out
• The current daemon.json is in version control and you can restore the exact previous file

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

• · docker info -f "{{.ServerVersion}}" records the engine version before the change
• · docker info -f "{{.DriverStatus}}" shows the active backend; the containerd image store reports driver-type io.containerd.snapshotter.v1
• · docker info -f "{{.Driver}} {{.DockerRootDir}}" records the current storage driver and data root
• · docker info -f "{{json .SecurityOptions}}" shows whether userns-remap is in effect
• · docker image ls --digests --format "{{.Repository}}:{{.Tag}} {{.Digest}}" captures the full image inventory, saved to a file outside the Docker data root
• · docker ps -a --format "{{.Names}} {{.Image}} {{.State}}" captures every container and the image it runs
• · docker system df -v records image, container and volume space before the change
• · df -h / and df -h /var/lib/docker confirm free space on BOTH the root partition and the Docker data root
• · cat /etc/docker/daemon.json and dockerd --validate --config-file /etc/docker/daemon.json exits 0 before you edit anything

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1. 1Announce the maintenance window; the daemon restart stops every container that is not configured to restart
2. 2Capture the inventory: write docker image ls --digests and docker ps -a output to a file stored OUTSIDE the Docker data root
3. 3Confirm every image you need is pullable from a registry, or export it: docker save -o /srv/export/app-1.4.2.tar registry.example.com/team/app:1.4.2
4. 4Verify each export before you rely on it: tar -tf /srv/export/app-1.4.2.tar lists a manifest and layer entries
5. 5Confirm free space on the root partition as well as the data root, because containerd storage does not follow a custom data-root setting
6. 6Back up the current daemon configuration: cp /etc/docker/daemon.json /etc/docker/daemon.json.pre-containerd
7. 7Stop the containers cleanly rather than letting the daemon restart kill them: docker compose stop for each stack
8. 8Add the feature flag to /etc/docker/daemon.json: a features object containing containerd-snapshotter set to true
9. 9Validate before restarting: dockerd --validate --config-file /etc/docker/daemon.json exits 0
10. 10Restart the daemon: sudo systemctl restart docker
11. 11Confirm the store actually changed: docker info -f "{{.DriverStatus}}" reports driver-type io.containerd.snapshotter.v1
12. 12Expect docker image ls to be nearly empty; the old images are still on disk but are not visible to the new store
13. 13Repopulate the new store by pulling from the registry: docker compose pull for each stack, or docker load -i for each verified export
14. 14Compare the repopulated inventory against the file captured before the change; every entry must be accounted for
15. 15Start the stacks in dependency order: docker compose up -d, data stores first
16. 16Re-check disk usage with docker system df and df -h, because both stores are now consuming space
17. 17Once the host is verified healthy and the window for rollback has passed, reclaim space from the store you are no longer using

4 · Verification

Confirm the procedure actually fixed the problem.

• ✓docker info -f "{{.DriverStatus}}" prints driver-type io.containerd.snapshotter.v1, which is the only positive proof the switch took effect
• ✓docker info -f "{{.ServerVersion}}" matches the version recorded in the pre-checks, confirming nothing else changed
• ✓systemctl is-active docker prints active and journalctl -u docker --since "10 min ago" contains no error at daemon start
• ✓Every image in the pre-change inventory file is present in docker image ls --digests after repopulation; a diff of the two lists is empty
• ✓docker compose ps shows every expected service running, with no restart loop
• ✓Each container with a healthcheck reports healthy: docker inspect -f "{{.Name}} {{.State.Health.Status}}" prints healthy, not starting
• ✓A fresh pull works on the new store: docker pull registry.example.com/team/app:1.4.2 completes and the digest matches the recorded value
• ✓A build works on the new store: docker build -t localhost/smoke:1 - reading a trivial Dockerfile from stdin completes and the image appears in docker image ls
• ✓df -h on BOTH the root partition and the Docker data root shows free space above your alert threshold after repopulation
• ✓Reboot the host once and confirm the daemon starts on the containerd store and every service returns

5 · Rollback

If verification fails, undo the procedure in reverse order.

• ↶Stop the containers cleanly: docker compose stop for each stack
• ↶Restore the previous daemon configuration: cp /etc/docker/daemon.json.pre-containerd /etc/docker/daemon.json
• ↶Validate before restarting: dockerd --validate --config-file /etc/docker/daemon.json exits 0
• ↶Restart the daemon: sudo systemctl restart docker
• ↶Confirm the store reverted: docker info -f "{{.DriverStatus}}" no longer reports io.containerd.snapshotter.v1
• ↶The images that were hidden when you switched reappear on switching back, because the old store was never deleted
• ↶Start the stacks again and verify health as before
• ↶This rollback holds ONLY while you have not deleted the old store. Once you reclaim that space the rollback is gone, which is why space reclamation is the last step and not part of the change.
• ↶Images pulled or built while on the containerd store do not appear in the classic store; pull or load them again after reverting

6 · Escalation

When the runbook isn't enough, contact:

• · The daemon fails to start after the change: capture journalctl -u docker output, roll back to the saved daemon.json, and escalate to the platform team with the log
• · The daemon uses userns-remap: stop. The containerd image store is documented as unavailable with user-namespace remapping. Escalate rather than removing the remapping, which is a security control.
• · The root partition fills during repopulation: escalate to the platform team, since containerd storage does not follow a custom data-root and may need its own directory configured
• · An image cannot be repopulated because it exists nowhere but the old store: escalate to the service owner before proceeding; roll back first so the image is visible again
• · A build behaves differently on the new store: escalate to the build owner with the image digests from both stores rather than adjusting the Dockerfile under pressure
• · You are considering the experimental automatic migration feature on a production host: escalate for a decision, since the upstream documentation describes starting fresh as the recommended approach

References

1. containerd image store with Docker Engine
2. Docker Engine 29 release notes
3. dockerd reference — daemon.json, --validate, data-root
4. docker system df
5. docker image save