Despliegue atascado en cola: qué comprobar primero

Un despliegue atascado en cola es uno de los fallos menos informativos que puede mostrarte una plataforma. No se ha producido ningún crash. No han aparecido logs porque no se ha ejecutado nada. El release simplemente permanece ahí, y cada actualización muestra la misma palabra.

Lo frustrante es que «en cola» abarca al menos cuatro situaciones distintas que no tienen nada que ver entre sí. Saber en cuál te encuentras lleva unos treinta segundos y determina si debes esperar, reintentar o buscar el problema en otro sitio completamente distinto.

Qué significa realmente «en cola»

Un despliegue en cola ha sido aceptado y registrado, pero todavía no se le ha asignado un worker. Entre esos dos momentos, deben cumplirse varias condiciones:

• La plataforma debe obtener tu código fuente, lo que normalmente implica una llamada a la API de tu proveedor de Git.
• Debe haber un build slot disponible.
• Cualquier prerrequisito del release debe haber terminado: un paso de migración, una operación sobre un volumen o un despliegue anterior del mismo servicio.

Si algo de eso está bloqueado, el registro existe, pero el trabajo no comienza. Ese es todo el mecanismo. No es ningún misterio, pero la mayoría de los dashboards muestran los cuatro casos con la misma palabra.

Los cuatro casos, en el orden en que conviene comprobarlos

1. Tu proveedor de Git está teniendo un mal día

Esta es la causa más habitual y aquella sobre la que no puedes hacer nada. La plataforma solicitó tu repositorio y recibió una respuesta lenta o un error. Si varios servicios no relacionados entran en cola al mismo tiempo y no comparten código, el proveedor es la dependencia común.

Comprueba la página de estado de tu proveedor antes de hacer cualquier otra cosa. Un deploy que está esperando a una API upstream se resolverá por sí solo, y reintentarlo solo añade otro registro a la pila; por eso una cola atascada acaba tan a menudo convirtiéndose en cinco colas atascadas.

2. Algo que estaba delante todavía no ha terminado

La mayoría de las plataformas serializan los despliegues por servicio, y con razón: dos builds escribiendo el mismo image tag no es una carrera que quieras ganar. Si un despliegue anterior de ese servicio todavía está ejecutándose —o, peor aún, la plataforma todavía cree que se está ejecutando porque un worker ha muerto sin informar—, el siguiente tiene que esperar.

En Dockup, dockup deployments muestra el historial empezando por el más reciente, con el estado de cada entrada. Si el despliegue situado justo encima de tu release en cola no está en un estado terminal, esa es la respuesta: cancelarlo o dejar que agote el tiempo de espera es lo que desbloquea la cola.

dockup deployments my-project/my-api --json

La salida de --json incluye el estado y la duración de cada despliegue, lo que hace evidente que «el anterior nunca terminó» de una forma que un spinner no consigue.

3. No hay capacidad

Todas las plataformas tienen un número finito de build workers. En un shared tier, un pico de actividad en toda la plataforma puede hacer que tus builds queden detrás de los de otros usuarios. Es algo real, normalmente breve, y es el único caso en el que esperar es realmente lo correcto.

Lo importante aquí es si puedes verlo. Una posición en la cola o una estimación del tiempo de espera convierte una experiencia que parece una caída en una situación normal. Un simple «en cola» no.

4. El despliegue nunca iba a empezar

El caso problemático: se creó el registro, pero el componente que debía recogerlo nunca lo hizo. Un worker se bloqueó, se perdió un webhook o un token caducó entre el trigger y la obtención del código.

La pista es el tiempo. Las esperas en cola se miden en segundos o un par de minutos. Un despliegue que lleva diez minutos en cola sin que haya ningún otro release por delante no está esperando: está atascado y seguirá así.

Cómo distinguir una espera de un bloqueo

Antes de reintentar, recopila tres datos:

1. ¿Se está desplegando algo más? Si hay otro release del mismo servicio en ejecución, estás en el caso 2 y deberías dejarlo tranquilo.
2. ¿Cuánto tiempo lleva en cola? Menos de dos minutos es normal. Más de diez, no.
3. ¿Otros servicios entraron en cola al mismo tiempo? Si varios servicios no relacionados se detuvieron a la vez, busca el problema upstream, no en tu código.

Estas tres respuestas separan «esperar» de «actuar» prácticamente siempre.

Por qué reintentar suele empeorar las cosas

Cuando un release se atasca, el impulso natural es volver a pulsar el botón de deploy. En un pipeline serializado, eso es contraproducente: añades un segundo registro detrás del primero y, si el primero está realmente atascado, el segundo hereda el bloqueo. Los desarrolladores que se encuentran con esto suelen acabar con una columna de entradas en cola, ninguna de las cuales se ejecutará hasta que se desbloquee la primera.

Si vas a reintentar, cancela primero el que está atascado. Un despliegue en cola que falla de forma visible es mucho más útil que cinco que se quedan ahí.

Qué hacemos al respecto en Dockup

La decisión de diseño importante aquí es que nunca se da por hecho que un despliegue está ejecutándose. Cada uno tiene un estado terminal, y alcanzarlo es lo que libera la cola. Un build que muere sin informar también agota el tiempo de espera y libera el servicio.

Hay otras dos cosas que ayudan más de lo que podría parecer:

Las etapas tienen nombre. Un despliegue de Dockup pasa por la obtención del código fuente, el build y el health gate, y cada etapa registra su propia duración. Cuando algo va lento puedes ver qué es lo que va lento en lugar de observar una sola palabra. stageTimings aparece en todos los registros de despliegue, también mediante --json.

No se pone nada en cola detrás de un release que ya ha fallado. Si el health check nunca se supera, el despliegue termina; no se queda ocupando el servicio mientras te preguntas qué ocurre. La versión anterior sigue sirviendo tráfico durante todo el proceso, que es la otra razón por la que un release atascado no supone una caída en Dockup.

# What is the current state, and how long has each stage taken?
dockup status my-project/my-api --json

# Follow the build as it happens rather than waiting for a summary
dockup logs my-project/my-api --build --follow

La regla general

Estar en cola no es un modo de fallo. Estar en cola sin un motivo asociado sí lo es. Cualquier plataforma hará que esperes ocasionalmente a un proveedor de Git o a un build slot; la diferencia entre una molestia de cinco minutos y una tarde perdida depende de que la interfaz te indique en cuál de los cuatro casos te encuentras.

Cuando evalúes dónde ejecutar algo, conviene comprobarlo de forma intencionada: activa un deploy y observa qué muestra la plataforma entre aceptarlo y comenzarlo. Si la respuesta es una sola palabra sin timestamp, tarde o temprano perderás una tarde con este problema.

Preguntas frecuentes

¿Cuánto tiempo debería permanecer un despliegue en cola? Unos segundos o un par de minutos en una plataforma saludable. Cualquier espera superior a diez minutos sin nada por delante debería considerarse un bloqueo, no lentitud.

¿Debería reintentar un despliegue en cola? No antes de cancelarlo. En un pipeline serializado, el reintento se pone detrás del que está atascado y hereda el mismo bloqueo.

¿Un despliegue atascado puede hacer que mi sitio deje de funcionar? No debería. En una plataforma que solo cambia el tráfico después de que un nuevo release supere su health check, la versión en ejecución sigue sirviendo durante todo el proceso: un deploy en cola o fallido es un release que nunca llegó a producirse, no una caída.

¿Por qué varios servicios entran en cola a la vez? Porque comparten una dependencia, que casi siempre es el proveedor de Git o la build fleet, no algo de tu código.