La API 1.57 de Docker pasa su especificación a OpenAPI 3.2
Docker cambia el formato fuente de su API y añade una pista útil para anticipar reinicios de contenedores.
El problema no está en el socket, sino en las herramientas que lo consumen
Si tienes un cliente generado, un validador o una automatización conectada al socket de Docker, esta actualización merece una revisión. La API de Docker Engine 1.57 cambia el formato fuente de su especificación de Swagger 2.0 a OpenAPI 3.2. No implica que tengas que reescribir una integración que ya funciona, pero sí puede romper la parte de tu cadena que descarga y procesa el contrato de la API. (github.com)
Esto afecta especialmente a scripts de homelab, paneles internos, workers y servicios que generan clientes desde el fichero de definición. Docker sigue ofreciendo una especificación Swagger 2.0 generada para facilitar la transición. También incluye una copia de Swagger fijada a la versión 1.57, pero ese fichero versionado no seguirá publicándose en futuras versiones. (github.com)
Qué cambia en la especificación
El archivo que Docker considera fuente de verdad pasa a ser api/openapi.yaml, escrito en OpenAPI 3.2. Si tu herramienta admite ese formato, el camino razonable es apuntarla a ese archivo y dejar de depender de copias Swagger asociadas a cada versión de la API. Si aún dependes de Swagger 2.0, puedes usar el archivo generado mientras adaptas el generador, el validador o la librería que tengas por medio. (github.com)
Yo no haría el cambio a ciegas en una automatización que toque producción o servicios importantes del homelab. Generaría el cliente de nuevo en una rama, compararía los tipos y revisaría cualquier ajuste que haga la herramienta al interpretar el documento. El cambio es de formato de especificación, pero cada generador tiene sus propias manías con referencias, esquemas reutilizados y nombres de modelos.
Comprueba primero la versión negociada
La API de Docker es versionada y cliente y daemon pueden negociar una versión común. Antes de exigir la 1.57 desde un cliente, conviene comprobar qué versión máxima soporta realmente el daemon al que te conectas. Docker documenta también la variable DOCKER_API_VERSION, pero usarla desactiva la negociación automática y la reservaría para compatibilidad concreta o depuración. (docs.docker.com)
docker version
DOCKER_API_VERSION=1.57 docker versionEn un servidor que todavía no exponga la API 1.57, ese segundo comando no convierte mágicamente al daemon en compatible. Si gestionas varios hosts desde Laravel, un worker o una automatización centralizada, detecta la versión del servidor antes de activar comportamientos que dependan de una versión reciente. La compatibilidad hacia atrás ayuda, pero las capacidades nuevas quedan desactivadas al negociar una API anterior. (docs.docker.com)
Un dato mejor para vigilar reinicios
La otra novedad útil está en los eventos die de contenedores. Cuando Docker prevé que un contenedor va a reiniciarse, el evento incorpora el atributo restarting con el valor "true". Puede ocurrir tanto por una política de reinicio como por un reinicio manual, y permite distinguir un contenedor que ha terminado de otro que está entrando en una secuencia de recuperación. (github.com)
Para verlo sin montar todavía un consumidor de la API, puedo filtrar los eventos de contenedor y pedir salida JSON. Docker admite filtros por tipo y por evento, y docker events puede emitir una línea JSON por cada evento recibido. (docs.docker.com)
docker events \
--filter 'type=container' \
--filter 'event=die' \
--format jsonA partir de ahí, un proceso que lea el flujo puede inspeccionar los atributos del evento y tratar restarting=true como una señal temprana. En Laravel lo usaría para registrar el incidente, pausar una tarea dependiente o marcar temporalmente un servicio como no disponible. No lo usaría como confirmación de que el contenedor ya está sano: para eso esperaría un evento posterior o consultaría el estado real del contenedor.
La letra pequeña importa
restarting=true anuncia una intención de reinicio, no una garantía. El reinicio puede cancelarse o fallar, así que no conviene disparar acciones irreversibles solo porque haya llegado el evento die. Además, el atributo se omite cuando el contenedor no va a reiniciarse, incluido el apagado del daemon. (github.com)
Tampoco sustituye una comprobación de disponibilidad de la aplicación. Un contenedor puede volver a estar en ejecución y seguir sin aceptar tráfico, sin haber terminado migraciones o con una dependencia caída. Si necesitas decidir cuándo reanudar trabajos, combina estos eventos con healthchecks, una comprobación HTTP o la señal que tenga sentido para tu servicio.
Qué revisaría ahora
Buscaría referencias a swagger.yaml, a copias versionadas de la especificación y a generadores anclados exclusivamente a Swagger 2.0. Después probaría OpenAPI 3.2 en local, regeneraría el cliente y compararía el resultado antes de actualizar la automatización desplegada. Si el proyecto no genera nada desde la especificación, probablemente este cambio no te obligue a hacer nada inmediato. (github.com)
Por otro lado, añadiría una prueba de integración para los eventos si mi sistema reacciona a reinicios. No basta con validar que llega un die: hay que cubrir el caso con restarting=true, el caso sin ese atributo y el momento en que el contenedor vuelve a estar realmente disponible. Es poco código, pero evita confundir una intención de recuperación con una recuperación completada.
Fuente oficial de Docker Engine API 1.57 Documentación oficial de Docker Engine API