Deployments blue/green

Un Deployment es propietario de una identidad de aplicación estable y de dos slots de ejecución. Opfield prepara una nueva versión en el slot inactivo, evalúa su estado y cambia el tráfico solo cuando la versión está lista. El slot que estaba activo sigue disponible como candidato de reversión hasta que el ciclo de vida del Deployment lo retira.

Gestiona los slots a través del Deployment y no como Containers individuales. El Deployment es responsable del cambio de tráfico, del historial de versiones, de la posibilidad de revertir y de la relación entre los dos hijos de ejecución. Editar directamente un hijo activo crea deriva de estado y debilita las garantías que hacen segura la reversión.

Qué cambia la decisión de usar un Deployment

Elige un Deployment cuando el riesgo de una versión dependa sobre todo del arranque y del estado de la aplicación, y cuando dos slots de versión puedan coexistir de forma segura en el mismo nodo Docker durante el cambio. El resultado es una identidad de servicio estable con una promoción controlada y un candidato de reversión explícito. Esto es especialmente útil para servicios públicos o compartidos en los que sustituir directamente un Container provocaría un tiempo de inactividad evitable.

El equipo de la aplicación es responsable de la preparación de la versión, de la semántica de estado, de la compatibilidad de las migraciones de datos y de la decisión de promover o revertir. El equipo de la plataforma es responsable de la capacidad de los nodos, de la confianza en las imágenes, de las Routes, de la entrega de secretos y de la disponibilidad del camino de reversión. Opfield coordina los slots y registra la operación; no puede hacer reversible un cambio de esquema incompatible.

No uses blue/green como sustituto de una estrategia de datos. Ambos slots pueden acceder temporalmente a la misma dependencia externa o a los mismos datos persistentes. Las migraciones de bases de datos deben ser compatibles con versiones anteriores durante la ventana de reversión, o el plan de la versión debe aceptar explícitamente que la reversión del entorno de ejecución por sí sola no basta.

Requisitos previos

Usa un digest de imagen inmutable o un artefacto de build aprobado. Antes de iniciar una versión, confirma que el nodo de destino está en línea, que la imagen se puede descargar, que los secretos y los volúmenes son correctos, que los límites de recursos caben en el nodo y que la ruta de estado comprueba el camino de la aplicación que importa a los usuarios. Revisa las Routes y las vinculaciones de bases de datos dependientes como parte del mismo cambio.

Publica una versión nueva

1. Abre el Deployment y prepara la nueva imagen y la configuración.
2. Revisa la entrada de la versión, incluidos el entorno, los secretos, los volúmenes, la selección del entorno de ejecución y la comprobación de estado.
3. Inicia la versión y sigue el Task mientras Opfield prepara el slot inactivo.
4. Espera a que se supere la comprobación de estado.
5. Deja que se complete el cambio de tráfico y verifica después una petición real, los logs de la aplicación y las métricas.
6. Mantén intacto el slot anterior hasta que haya pasado la ventana de reversión acordada.

Guardar un tag de imagen, un comando, montajes, etiquetas o un entorno de ejecución nuevos en los ajustes del Deployment lo despliega de esta forma; el botón dice Save & Deploy. Guardar las variables de entorno de un Deployment en ejecución las despliega en el slot en espera. Los límites de recursos se guardan con la configuración. Desplegar o actualizar un Deployment con una imagen o un comando nuevos requiere docker:containers:environment y docker:containers:secrets sobre él, porque el nuevo slot recibe el entorno y los secretos del Deployment; un entorno nuevo por sí solo solo requiere docker:containers:environment. Los comandos de despliegue esperan a la descarga de la imagen, al periodo de gracia de arranque y al tiempo de espera del despliegue antes de informar de un resultado.

A través de la API, POST /api/docker/nodes/{nodeId}/deployments/{deploymentId}/deploy con env sustituye todo el entorno del Deployment y lo guarda como su configuración, así que envía todas las variables que deba conservar el Deployment. La herramienta MCP deploy_docker_deployment y el asistente, en cambio, aplican env sobre el entorno guardado y eliminan las claves indicadas en removeEnv; todas las demás variables guardadas se mantienen. Ambos requieren docker:containers:environment.

Las versiones desencadenadas por webhooks usan el mismo camino de autorización y de condición de estado. Una petición de webhook no elude la propiedad del Deployment ni convierte un build fallido en una versión pública.

Fallos y reversión

Si la preparación o la validación del estado fallan antes de cambiar el tráfico, el slot activo existente sigue siendo la versión que sirve. Inspecciona la operación en busca de errores de descarga de la imagen, arranque, estado, secretos, volúmenes o capacidad; corrige la causa e inicia una versión nueva en lugar de modificar en su sitio el slot fallido. Un slot candidato que falla su comprobación de estado se detiene y se conserva para sus logs, de modo que no puede entrar en un bucle de fallos y quitarle conexiones a la base de datos al slot que sirve; un cambio posterior a ese slot lo recrea a partir de su versión registrada.

Si aparece una regresión visible para los clientes después del cambio, usa la acción de reversión explícita. Devuelve el tráfico al slot conservado que se sabe que funciona y registra el evento en el historial del Deployment. Verifica la Route, el estado de la aplicación y los logs tras la reversión. Un cambio de slot conserva la versión del slot en espera, y la reversión vuelve a la versión anterior. No elimines el slot más nuevo hasta que estén claros el registro del incidente y el seguimiento deseado.

Operaciones durante reinicios, actualizaciones y builds

Las operaciones de los Deployments sobreviven a los reinicios de Opfield. Un barrido duradero termina el vaciado del slot anterior, y una versión interrumpida se reconstruye a partir del slot que realmente sirve el router del nodo. Si el nodo no se puede inspeccionar en 5 minutos, la versión se marca como fallida con un motivo como un router detenido o un daemon que no puede informar de su slot activo; en este último caso, actualiza el daemon de Docker.

Mientras se ejecuta una versión, los ajustes del Deployment están bloqueados: guardar devuelve DEPLOYMENT_BUSY y la consola desactiva Save hasta que termina la versión. Mientras se despliega un build de Git en el Deployment, los cambios de ciclo de vida y de configuración devuelven BUILD_ROLLOUT_IN_PROGRESS; espera a que termine el despliegue. Un Deployment vuelve en su slot activo tras Stop y después Start, o tras un reinicio del nodo, y un reinicio de Opfield en mitad de un despliegue no pierde la versión. Durante una actualización de Opfield, las nuevas operaciones de Deployments se rechazan con OPFIELD_UPDATING hasta que termina la actualización; consulta Requisitos previos de la actualización en la 2.11.

Router del Deployment

Cada Deployment tiene un pequeño contenedor router de nginx en su nodo. El router recibe el tráfico del Deployment y lo reenvía al slot activo; un cambio de slot o una reversión solo cambian el destino del router.

• Vuelve tras un reinicio. Los routers se ejecutan con la política de reinicio unless-stopped. Cuando arranca el daemon de Docker, repara el router de cada Deployment que está sirviendo: un router creado por una versión anterior, o que haya quedado con la política de reinicio no, recibe la política actual o se vuelve a crear a partir de la configuración que sirve, con sus rutas y sus puertos publicados, y se apunta al slot de aplicación que realmente se está ejecutando. El daemon repite la reparación cada minuto hasta que tiene éxito; mientras una operación del Deployment lo tiene ocupado, la reparación la espera y se ejecuta cuando termina. Un Deployment que se detuvo o se mató deliberadamente mantiene su router detenido.
• Las operaciones arrancan un router detenido. Un despliegue, un cambio de slot, una actualización del router o un inicio levantan un router que se había detenido con kill o stop en lugar de fallar por ello, y un Deployment cuyo slot activo no puede arrancar ya no se queda bloqueado.
• No depende del DNS de Docker. La configuración del router indica la dirección del contenedor del slot activo y hace de proxy directamente hacia ella en todas las versiones de nginx, sin un resolutor; el daemon comprueba la dirección cada 5 segundos y reescribe la configuración cuando cambia. Solo una configuración escrita antes de conocerse la dirección del slot resuelve el nombre del slot a través del DNS de Docker. Los routers existentes se actualizan en su sitio, sin volver a crearlos.
• No escribe log de acceso. El nodo Ingress ya registra cada petición. Por tanto, un router nunca se bloquea en la salida de su contenedor, que vacía dockerd, de modo que un Docker Engine (dockerd) bloqueado no detiene el tráfico hacia un Deployment en ejecución.
• Aplicaciones que registran cada petición. La salida de los contenedores pasa por el pipeline de logs de Docker, que deja de vaciarse mientras dockerd está congelado. Por tanto, una aplicación que escribe una línea en stdout o stderr por cada petición puede bloquearse cuando se llene esa tubería, aunque el router y los Secure Links sigan funcionando. Mantén el logging por petición fuera de la salida del contenedor, o acepta que esa aplicación puede bloquearse durante una congelación de dockerd.
• Los cuerpos de las peticiones no están limitados. El router deja pasar cuerpos de petición de cualquier tamaño (el límite lo decide la Route) y los transmite al slot en lugar de guardarlos en disco. Los routers creados antes de este cambio lo adoptan en su siguiente despliegue, cambio de slot o reinicio.
• Sus propios errores están marcados. Cuando el router no puede llegar al slot activo, responde 502 o 504 con la cabecera X-Opfield-Deployment-Router: upstream-unavailable (X-Gateway-Deployment-Router en un router desplegado antes de la 2.12.1, hasta que se vuelva a desplegar el Deployment), lo que distingue un error del router de un error de la aplicación. Workload Availability lo usa para decidir si una ubicación de un Deployment está lista.

Consecuencias de la retirada

Eliminar un Deployment elimina sus slots gestionados y puede eliminar relaciones de acceso que solo pertenecen a ese recurso. Un Deployment se puede eliminar mientras su slot en espera todavía ejecuta una imagen anterior. Primero desvincula o migra las Routes, las vinculaciones de bases de datos y los datos persistentes que deban sobrevivir. Una reversión de un Deployment protege un slot de ejecución anterior; no sustituye a hacer copias de seguridad de los datos mutables de los volúmenes.

Criterios de éxito y política de despliegue

Define una comprobación de estado que represente una dependencia relevante para el usuario, no solo que el proceso acepte una conexión TCP. Antes de la promoción, verifica los logs de arranque, la estabilidad del estado durante el periodo de observación acordado, el uso de recursos y cualquier dependencia privada. Tras la promoción, verifica una petición real a través de la Route y vigila la tasa de errores y la latencia antes de retirar el slot anterior.

Fija una ventana de reversión explícita. Durante esa ventana, mantén disponibles el artefacto y la configuración anteriores y evita los cambios que impidan servirlos. Si un problema posterior no está relacionado con la nueva versión, registra esa prueba antes de revertir; cambiar de slot innecesariamente puede dificultar el diagnóstico.

Detalles para operadores: capacidad y versiones fallidas

El slot inactivo necesita CPU, memoria, almacenamiento, puertos y acceso de descarga de imágenes suficientes para arrancar junto al slot activo. Durante el solapamiento, ambos slots comparten además cada enlace de base de datos del Deployment, que transporta tantas conexiones como acepte la base de datos; dimensiona los pools de conexiones para que el nuevo slot pueda abrir sus pools mientras el slot que sirve mantiene los suyos. Consulta Capacidad de los enlaces y pools de conexiones. La planificación de la capacidad debe incluir este solapamiento temporal. Una versión que no puede asignar su slot inactivo debe fallar antes de que cambie el tráfico, dejando intacto el servicio activo.

Cuando el estado nunca llega a estar listo, inspecciona los logs del slot inactivo y la respuesta exacta de la comprobación de estado. Corrige la imagen o la configuración de la versión y crea un nuevo intento de versión; no modifiques el Container hijo gestionado. Si la promoción se completó pero la verificación falla, usa la acción de reversión registrada y verifica después tanto el camino del servicio como la identidad final del slot activo.