Ingeniería
Del código fuente a una versión saludable: qué hace realmente un despliegue
Un comando de despliegue cruza varios límites: empaquetado del código fuente, compilación, inicio del entorno de ejecución, disponibilidad, promoción y enrutamiento público. Cada uno puede fallar de forma distinta.
Una compilación correcta no es una aplicación en producción. Entre el código fuente en la máquina del desarrollador y una URL pública hay varias comprobaciones independientes, cada una con sus propias pruebas y vía de recuperación.
El límite del código fuente: capturar lo que se compilará
La primera pregunta parece sencilla: ¿qué archivos representa este despliegue? Un directorio local, una revisión Git y un espacio de trabajo abierto pueden tener contenidos distintos. Si la plataforma no puede identificar el código fuente exacto que compiló, depurar después se convierte en adivinar. Adios registra el código fuente como un artefacto para vincular el despliegue con código que se puede volver a abrir en un espacio de trabajo.
El paquete debe excluir salidas desechables como node_modules y los directorios de compilación locales, pero conservar el archivo de bloqueo, el manifiesto y los archivos necesarios para compilar. Una subida correcta solo demuestra que llegó el paquete. No demuestra que el código compile ni que el entorno de ejecución pueda iniciarse.
El límite de compilación: producir una salida con versión
La etapa de compilación instala dependencias, ejecuta el comando de compilación declarado y produce la salida que iniciará una carga de trabajo. Una compilación fallida debe dejar registros y un resultado de fallo, no una versión promovida a medias. Adios muestra por separado los registros de compilación y del entorno de ejecución porque los fallos de resolución de paquetes y compilación tienen responsables distintos de los fallos de inicio de la aplicación.
Para una API Go, la salida de compilación puede ser un binario. Para Next.js incluye el servidor y los recursos. Para un servicio Python, el trabajo principal puede ser instalar dependencias fijadas y preparar el entorno. La forma varía, pero la condición es la misma: el entorno de ejecución inicia una salida identificada, derivada de código fuente identificado, bajo un contrato explícito de compilación.
- —Registra el artefacto de código fuente y el identificador de compilación.
- —Mantén el comando de compilación en adios.yaml y en los scripts del proyecto.
- —Inspecciona los registros de compilación cuando falle la instalación de dependencias o la compilación.
- —No deduzcas la salud del entorno de ejecución de una compilación correcta.
El límite del entorno de ejecución: iniciar el proceso correcto
Cuando existe una compilación, el proceso de trabajo debe iniciar el proceso de producción declarado con su entorno, límites de recursos y configuración de red. Un fallo habitual es escuchar en un puerto distinto del manifiesto. Otro es escuchar solo en localhost cuando el gateway necesita acceder al puerto de la carga de trabajo. Los secretos ausentes y los recursos gestionados necesarios también pueden hacer que un proceso termine inmediatamente o parezca activo sin atender solicitudes.
Adios crea una versión del entorno de ejecución con una o varias réplicas. El manifiesto describe la región, el número de réplicas, el comando de inicio, el puerto y la ruta de salud. Esto permite que un revisor determine si la nueva versión puede ejecutarse con seguridad sin depender de ajustes de panel que nunca se guardaron en un commit.
A small API deploy contract
name: api
region: de
replicas: 2
build_cmd: go build -o /app/api ./cmd/api
start_cmd: /app/api
runtime:
name: go@1.25
port: 8080
health_path: /healthzEl límite de disponibilidad: demostrar que esta versión puede atender solicitudes
Un proceso puede estar activo mientras sus rutas devuelven errores. La disponibilidad determina si esta versión puede atender una solicitud real. Una ruta de salud útil debe fallar dentro de un plazo cuando una dependencia necesaria no esté disponible y recuperarse cuando vuelva. Debe evitar trabajo costoso que convierta la propia sonda en carga.
La guía de inicio rápido de Adios describe la promoción después de alcanzar un despliegue saludable. La CLI también comprueba una ruta pública de salud configurada y puede indicar que la ruta actual está saludable. Son observaciones distintas: la disponibilidad de la réplica protege la versión candidata; una sonda pública comprueba lo que el cliente alcanza a través de la entrada. Una verificación completa necesita ambas y una solicitud a una ruta representativa de la aplicación.
El límite de promoción: convertir la nueva versión en actual
Una versión de despliegue y la versión actual son conceptos distintos. Separarlos permite que un operador inspeccione una versión fallida o sustituida sin aparentar que es la que atiende a los usuarios. La ruta debe apuntar a la versión que superó las comprobaciones requeridas, y una candidata fallida debe dejar disponible la versión actual anterior.
Aquí revertir tiene un significado concreto: seleccionar una versión anterior saludable conocida, verificar sus recursos y compatibilidad de esquema, y devolverle la ruta. Una migración de base de datos puede dificultarlo aunque la plataforma conserve salidas antiguas del entorno de ejecución. Revisa la compatibilidad con versiones anteriores antes de asumir una reversión automática.
El límite de la ruta pública: probar lo que ven los usuarios
La solicitud final atraviesa DNS, TLS, un gateway de entrada, la búsqueda de ruta y la carga de trabajo seleccionada. Un fallo en cualquiera de esos puntos puede parecer al usuario que el despliegue está averiado aunque el contenedor esté saludable. Solicita el nombre de host y la ruta reales, comprueba las redirecciones y certificados, y compara la respuesta con la versión que querías promover.
Para un dominio personalizado, verificar el DNS y emitir el certificado son controles adicionales. Para una dirección anycast, el nodo perimetral que recibe la solicitud puede estar en una ciudad distinta de la carga de trabajo. La prueba básica pública sirve para recorrer todo ese camino, en lugar de detenerse en una comprobación de salud local.
- —Usa los registros de compilación para los errores de empaquetado y compilación.
- —Usa los registros del entorno de ejecución para los errores de inicio, dependencias y salud.
- —Usa una solicitud HTTPS pública para los errores de TLS, rutas y selección de versión.
- —Registra el artefacto de código fuente y la versión junto a la respuesta pública.
Un despliegue está completo cuando las pruebas coinciden
La salida útil de un despliegue es más que una URL. Es una cadena que conecta el código fuente, la compilación, la versión del entorno de ejecución, el resultado de disponibilidad, la versión promovida y la respuesta pública. Cuando los identificadores coinciden, un desarrollador puede saber qué está en producción y cómo recuperarlo. Cuando no coinciden, el límite en el que faltan pruebas indica dónde investigar después.