Error response from daemon: Get "https://registry.example.com:5000/v2/": tls: failed to verify certificate: x509: certificate signed by unknown authority

El host y el puerto del registro serán los tuyos; docker push, pull y login lo notifican como «Error response from daemon: Get \"https://<registry>/v2/\": …». containerd, nerdctl, Podman y los nodos de Kubernetes que descargan imágenes imprimen el mismo texto x509 con sus propios prefijos.

Docker Engine (dockerd) — docker pull / push / login against a registry with an untrusted certificate

Qué significa

El daemon de Docker (no la CLI docker) intentó acceder a la API del registro en /v2/ y no pudo verificar su certificado TLS: la cadena no lleva a ninguna CA en la que confíe el daemon. dockerd confía en el bundle de CA del sistema del host, además de en las CA por registro colocadas en /etc/docker/certs.d/<registry>:<port>/. Las causas habituales son los registros privados con certificados de la empresa y los proxies que inspeccionan TLS.

Por qué ocurre

• Un registro autoalojado con un certificado privado

  frecuente

  Harbor, el registro de GitLab, Nexus o registry:2 detrás de un certificado de una CA de la empresa o creada por uno mismo.

• Un proxy que inspecciona TLS delante de Docker Hub u otros registros

  frecuente

  El daemon ve los certificados del proxy; sin su raíz en el almacén del host, todos los pull fallan.

• La CA se instaló donde el daemon no la busca

  ocasional

  Copiar la CA en el almacén del equipo cliente no sirve de nada si el daemon se ejecuta en otro lugar (la VM de Docker Desktop, un DOCKER_HOST remoto, un runner de CI). El nombre del directorio dentro de certs.d debe coincidir exactamente con el host y el puerto del registro.

• El registro omite su intermedio

  ocasional

  Go (dockerd) no descarga los intermedios; un registro que solo envía el certificado hoja falla incluso con una CA pública.

Cómo solucionarlo

1. 1.

   Instalar la CA de este registro en certs.d

   /etc/docker/certs.d/<host>:<port>/ca.crt se lee en cada solicitud; en la reproducción, docker login funcionó justo después de añadirlo.

   # Trust the registry's CA for this registry only (no daemon restart needed)
   sudo mkdir -p /etc/docker/certs.d/registry.example.com:5000
   sudo cp corp-root-ca.pem /etc/docker/certs.d/registry.example.com:5000/ca.crt
   docker login registry.example.com:5000

2. 2.

   Instalar la CA en todo el sistema y reiniciar dockerd

   Para los proxies y muchos registros, añade la raíz al bundle del host; el daemon lo lee al arrancar.

   # Or system-wide (proxy roots, many registries), then restart the daemon
   sudo cp corp-root-ca.pem /usr/local/share/ca-certificates/corp-root-ca.crt
   sudo update-ca-certificates
   sudo systemctl restart docker

3. 3.

   Docker Desktop: confiar en la raíz en el host

   La VM de Docker Desktop toma las raíces de confianza del sistema operativo del host al arrancar, así que instala allí la raíz y reinicia Docker Desktop.

   Docker Desktop: the daemon runs in a VM. Add the root to the host's trust store
   (macOS Keychain "System" with "Always Trust", Windows "Trusted Root Certification Authorities")
   and restart Docker Desktop; it imports trusted host roots into the VM.

4. 4.

   Comprobar la cadena del registro

   Si solo se envía el certificado hoja, configura el registro o su proxy inverso con la cadena completa.

   openssl s_client -connect registry.example.com:5000 -servername registry.example.com -showcerts </dev/null 2>/dev/null \
     | grep -E '^ *[0-9]+ s:|^ *i:'

← Explorar toda la base de datos de errores de firma