Docker v29 en VPS: migrar sin romper sus stacks

Por qué Docker v29 rompe los stacks existentes — y por qué ahora

Lo que esta guía le permite hacer

• Detectar la versión de API en tensión entre su cliente docker y el daemon del VPS, antes de que el próximo comando produzca un error críptico.
• Identificar en 30 segundos si un VPS todavía funciona con docker-compose v1 standalone — el binario obsoleto desde Docker Desktop 3.6 y retirado de los paquetes oficiales.
• Migrar al plugin docker compose v2 con los dos comandos exactos, y luego verificar que sus docker-compose.yml existentes funcionan sin cambios de sintaxis.
• Comprender el impacto de nftables en sus stacks: lo que sigue funcionando (las redes Docker), lo que puede romperse (sus scripts que leen iptables) y el comando de diagnóstico que lo aclara.
• Activar o aplazar el almacén containerd según su calendario de migración, con la clave de configuración exacta y el comando de verificación.
• Evaluar la compatibilidad de Dockge, Portainer y CasaOS App Store con v29, para no descubrir la incompatibilidad durante una incidencia de cliente.
• Preparar los VPS de sus clientes para que el próximo apt upgrade sea un evento planificado, no una urgencia nocturna.

Requisitos previos antes de empezar

Paso 1 — Diagnosticar la versión de API

1. 01

   Verificar la versión de API del cliente y del daemon

   En cada VPS que vaya a auditar, ejecute los dos comandos siguientes:

   docker version --format '{{.Client.APIVersion}}'
   docker version --format '{{.Server.APIVersion}}'

   Si la versión del cliente es inferior a 1.44 y el daemon funciona en v29, obtendrá un error en los próximos comandos. El umbral 1.44 es el mínimo aceptado por Docker Engine v29: un cliente compilado para 1.43 o anterior falla con Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client.

   Si ambas líneas muestran 1.44 o más, su cliente es compatible. Pase al paso siguiente.

2. 02

   Detectar la presencia de docker-compose v1 standalone

   El comando docker-compose con guion y el comando docker compose sin guion no son lo mismo. El v1 es un binario Python autónomo; el v2 es un plugin Go integrado en la CLI de Docker.

   which docker-compose && docker-compose --version

   Si el comando devuelve una ruta en /usr/local/bin/ o /usr/bin/ con una versión 1.x.x, tiene el binario standalone obsoleto. Tras la actualización a Docker v29, ese binario devuelve docker-compose: command not found si el paquete ha sido retirado, o el error de API descrito arriba si todavía está presente.

   docker compose version

   Si este comando devuelve Docker Compose version v2.x.x, el plugin v2 ya está presente. Ambos pueden convivir temporalmente, pero el objetivo es usar únicamente el plugin v2.

Paso 2 — Migrar de docker-compose v1 al plugin v2

1. 03

   Retirar el binario v1 e instalar el plugin

   apt remove docker-compose
   apt install docker-compose-plugin

   En un VPS Debian o Ubuntu que use los repositorios oficiales de Docker Inc. (download.docker.com), el paquete docker-compose-plugin está disponible sin configuración adicional. Si apt remove docker-compose responde Package not found, el binario se instaló manualmente: localícelo con which docker-compose y elimine el archivo.

   Verificación posterior a la migración:

   docker compose version
   # Docker Compose version v2.36.0

2. 04

   Verificar la compatibilidad sintáctica de sus archivos Compose existentes

   La gran mayoría de los archivos docker-compose.yml escritos para v1 funcionan sin modificación con el plugin v2. Las únicas rupturas de sintaxis afectan a las directivas version: superiores a "3.8" (ignoradas en v2, no bloqueantes) y a la opción --compatibility (retirada). Valide sus archivos existentes:

   docker compose config

   Este comando resuelve las variables de entorno, valida la sintaxis y muestra la configuración resuelta. Una salida sin errores significa que su archivo es compatible.

   Si su equipo usa scripts de shell con docker-compose (con guion), ponga un alias de compatibilidad en el /etc/bash.bashrc del VPS:

   alias docker-compose='docker compose'

   Este alias no resuelve los scripts que llaman a docker-compose con ruta absoluta desde un cron o un servicio systemd — audítelos.

Paso 3 — Entender y adaptarse al cambio de backend de red nftables

1. 05

   Verificar que las redes Docker siguen funcionando

   La buena noticia: docker network funciona correctamente con nftables. El tráfico entre contenedores, el NAT y la exposición de puertos siguen funcionando. Lo que cambia es la herramienta subyacente que escribe las reglas.

   docker network ls

   Sus redes bridge existentes siguen apareciendo en la lista. Para comprobar que un contenedor recibe tráfico en el puerto esperado, pruebe directamente:

   curl -s http://localhost:8080/health

   Si la respuesta es correcta, el plano de datos de Docker funciona con independencia del backend.

2. 06

   Diagnosticar el impacto en sus scripts iptables

   El problema aparece cuando un script de terceros (monitorización, Ansible, reglas UFW) inspecciona iptables para comprobar que las reglas Docker están presentes:

   iptables -L DOCKER 2>&1

   Con el backend nftables, esa cadena está vacía o ausente. El script devuelve un error mientras Docker funciona perfectamente. No es una avería de Docker — es su herramienta de auditoría, que ya no mira en el sitio correcto.

   Para inspeccionar las reglas reales:

   nft list ruleset | grep -A 20 'docker'

   Si sus scripts de monitorización o sus playbooks Ansible comprueban la presencia de reglas iptables específicas de Docker, adáptelos para consultar nftables en lugar de deducir de ahí una avería.

   Si tiene reglas UFW personalizadas que interactúan con las reglas Docker, consulte la documentación de Docker sobre el modo DOCKER-USER — existe tanto en nftables como en iptables, pero la sintaxis para añadir reglas difiere. El artículo [pare-feu-ufw-vps](/blog/pare-feu-ufw-vps) cubre UFW de forma general; para la interacción específica de Docker v29, consulte las notas de la versión oficial.

Paso 4 — Evaluar y activar el almacén de imágenes containerd

1. 07

   Verificar el driver de almacenamiento actual

   docker info | grep 'Storage Driver'

   En un VPS actualizado a v29 sin cambios de configuración, obtendrá normalmente Storage Driver: overlay2. El almacén containerd es opt-in en v29 — no se activa automáticamente. Será el valor por defecto en v30.

   Si ve Storage Driver: overlayfs (señal de que alguien ya ha activado el backend containerd), el almacén está activo.

2. 08

   Activar el almacén containerd (opt-in, recomendado antes de v30)

   Para activar el almacén containerd en v29 y preparar la migración antes de que se imponga en v30, añada la clave siguiente en /etc/docker/daemon.json:

   {
     "features": {
       "containerd-snapshotter": true
     }
   }

   Reinicie el daemon:

   systemctl restart docker

   Verificación:

   docker info | grep 'Storage Driver'
   # Storage Driver: overlayfs

   Punto de atención: las imágenes existentes descargadas bajo overlay2 siguen disponibles, pero las nuevas capas se escriben en el formato containerd. Si necesita volver atrás, elimine la clave y reinicie — las imágenes del nuevo formato dejarán de ser accesibles sin el backend containerd. Por eso se recomienda un snapshot antes de este paso.

Compatibilidad de las herramientas de terceros con Docker Engine v29

Desplace la tabla

Resolución de problemas — errores reales y remedios

Escenarios de error frecuentes

1. 09

   Error: `client version X.XX is too old. Minimum supported API version is 1.44`

   Causa: el binario docker-compose v1 standalone sigue presente e intenta comunicarse con el daemon v29.

   Remedio:

   apt remove docker-compose
   apt install docker-compose-plugin
   docker compose version

   Si el binario se instaló manualmente (fuera de apt), búsquelo:

   which docker-compose
   rm /usr/local/bin/docker-compose

2. 10

   Error: `docker-compose: command not found` tras `apt upgrade`

   Causa: el paquete docker-compose (v1) fue retirado durante la actualización, y el plugin v2 no se instaló.

   Remedio:

   apt install docker-compose-plugin

   Compruebe después que sus scripts que llaman a docker-compose (con guion) usan ahora docker compose (sin guion), o ponga el alias de sistema.

3. 11

   Error: `iptables: No chain/target/match by that name` en un script de monitorización

   Causa: su script inspecciona la cadena DOCKER en iptables, pero Docker v29 con nftables ya no la escribe ahí.

   Remedio: sustituya la comprobación iptables por una comprobación nftables:

   nft list ruleset | grep -c 'docker'

   Si el recuento es mayor que cero, las reglas Docker están presentes en nftables. O use docker network inspect bridge para comprobar el estado del plano de datos directamente desde Docker, sin depender del backend de red.

4. 12

   Dockge ya no arranca tras la actualización

   Causa: Dockge 1.4.1 y anteriores llaman a rutas de API ausentes en Docker Engine v29.

   Remedio:

   cd /opt/dockge
   docker compose pull
   docker compose up -d

   Si el tag latest de la imagen de Dockge ya está en 1.4.2 o superior, este comando basta. Si no, edite el docker-compose.yml de Dockge para apuntar al tag de la versión correctiva antes de relanzarlo.

5. 13

   Los contenedores ya no responden en sus puertos tras reiniciar el daemon

   Causa: en el primer reinicio de dockerd en modo nftables, las reglas de NAT se reescriben en el backend correcto, pero algunas distribuciones tienen un conflicto entre el servicio iptables-legacy y nftables que retrasa la puesta en marcha de las reglas.

   Remedio:

   systemctl stop docker
   systemctl disable iptables
   systemctl start docker

   Compruebe después que los contenedores se han reiniciado correctamente (docker compose up -d) y que los puertos están expuestos (docker ps --format 'table {{.Names}}\t{{.Ports}}').

Preparar su flota para evitar la próxima incidencia

apt-mark hold docker-ce docker-ce-cli containerd.io