From efc4ac5764d9aea98cbd747f3b325a06d4078422 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Wed, 12 Aug 2026 18:01:42 +0500
Subject: [PATCH] docs: note insecure registries with containerd image store

docker info can list insecure-registries while pull/push still fails
TLS with the containerd path. Call out restart, real pull checks, and
recent 29.x TLS fixes.

Signed-off-by: Dean Chen <862469039@qq.com>
---
 content/manuals/engine/storage/containerd.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/content/manuals/engine/storage/containerd.md b/content/manuals/engine/storage/containerd.md
index 64bacd22b080..f6bb11f93008 100644
--- a/content/manuals/engine/storage/containerd.md
+++ b/content/manuals/engine/storage/containerd.md
@@ -113,6 +113,23 @@ Docker Engine uses the `overlayfs` containerd snapshotter by default.
 > image store, push them to a registry first, or use `docker save` to export
 > them.
 
+## Private and insecure registries
+
+Registry settings such as `insecure-registries` and custom CAs under
+`/etc/docker/certs.d/` apply through the daemon configuration, but they are
+implemented on a different code path than the legacy graph-driver image store.
+
+After changing those settings, restart Docker and confirm a real
+`docker pull` / `docker push` against the registry. `docker info` may still
+list an insecure registry even when a TLS handshake fails for
+containerd-backed pulls.
+
+If an insecure or custom-CA registry works only after setting
+`"containerd-snapshotter": false`, upgrade Docker Engine to a recent 29.x
+release (auth/TLS handling for the containerd path has received fixes such as
+[moby#52600](https://github.com/moby/moby/pull/52600)) and re-test with the
+containerd image store enabled.
+
 ## Experimental automatic migration
 
 Docker Engine includes an experimental feature that can automatically switch to