Solución de problemas del tráfico entrante

El objetivo ante un incidente es restablecer el servicio público sin destruir el estado que explica el fallo. El tráfico entrante cruza varios límites de propiedad (DNS, red, certificado, configuración de nginx, política de la Route, transporte privado y entorno de ejecución de la aplicación), por lo que cambiar varias capas a la vez suele alargar la caída.

Asigna un único responsable del incidente, registra el último cambio que se sabe que funcionaba y verifica de fuera hacia dentro. El éxito significa que el comportamiento externo se ha restablecido, que el estado deseado y el informado de Opfield coinciden y que la capa que falló y la acción de recuperación quedan registradas con el detalle suficiente para evitar que se repita.

Sigue este orden para no cambiar la capa equivocada:

1. DNS: resuelve el nombre de host desde un cliente externo y confirma que apunta al nodo de ingress asignado.
2. Red: confirma la accesibilidad pública de 80/443 y las reglas del cortafuegos del host.
3. TLS: inspecciona el nombre de host del certificado, la cadena, la caducidad y el estado de distribución.
4. Configuración de nginx: verifica que se aplicó la última revisión y que la validación de la configuración fue correcta.
5. Estado de la Route: inspecciona el código y el cuerpo esperados y el estado de mantenimiento.
6. Upstream: prueba la aplicación desde el nodo nginx o inspecciona el estado del Secure Link.
7. Logs: correlaciona los logs de acceso y de errores de nginx con los logs de la carga de trabajo y los ID de petición.

Entre los errores habituales están colocar el dominio y la Route en nodos distintos, un DNS externo desactualizado tras una migración, HTTP-01 en un nodo sin el puerto 80 público, una aplicación WebSocket sin reenvío de WebSocket y seleccionar un puerto de la carga de trabajo que en realidad no está publicado ni enlazado.

Guía de síntomas

Síntoma	Capa más probable	Primera prueba
El nombre de host no se resuelve	DNS	Consulta externa de A/AAAA y ubicación del dominio
Tiempo de espera de conexión agotado	red	Dirección pública, cortafuegos, puertos 80/443, disponibilidad del nodo
Advertencia de certificado	TLS	Nombre de host del certificado, cadena, caducidad y Route asignada
El handshake TLS falla de inmediato	coincidencia de Route	Ninguna Route activada en ese nodo sirve el nombre de host; el nodo rechaza esos handshakes en lugar de responder con el sitio de otra Route
404 inmediato	coincidencia de Route	Nombre de host, prefijo de ruta, estado activado, configuración en bruto
503 gestionado	mantenimiento o upstream en mal estado	Estado de mantenimiento e historial de estado
502/504	transporte al upstream	Secure Link, puerto de destino, estado de la carga de trabajo, ajustes de tiempo de espera
Desconexiones de WebSocket	reenvío del protocolo	Opción WebSocket, ruta de la aplicación, tiempos de espera del proxy y de lectura
Los cambios nunca aparecen	aplicación/conciliación	estado del Task, revisión de nginx, conexión del nodo, error de validación; un cambio rechazado falla con 422 NGINX_CONFIG_FAILED e incluye la salida de nginx -t
502 de una Route Docker en Raw Config Mode	configuración en bruto	La configuración en bruto debe seguir haciendo de proxy hacia el upstream del Secure Link de la Route; consulta Routes
502 de un Deployment	router del Deployment	La cabecera X-Opfield-Deployment-Router: upstream-unavailable significa que el router no pudo llegar al slot activo

Reúne pruebas antes de cambiar el estado

Registra el nombre de host que falla, la ruta, la hora, la clase de IP del cliente, la respuesta esperada, la respuesta real, el nodo asignado, el ID de la Route, el ID del último Task y el ID de petición correspondiente. Conserva el error de validación de la configuración generada y unos logs acotados antes de reintentar; las ediciones repetidas pueden borrar las pruebas más útiles.

Compara tres vistas:

1. el estado deseado de Opfield en los detalles de la Route y del dominio;
2. el último estado confirmado por el nodo nginx;
3. el comportamiento de DNS, TLS y HTTP observado desde fuera.

Una discrepancia entre estas vistas indica si el fallo está en el estado del plano de control, en la aplicación en el nodo o en la infraestructura externa.

Los fallos de los Secure Links se registran una vez por enlace, no una vez por petición. El daemon de nginx del nodo Ingress registra una advertencia proxy secure-link connections failing con el link_id, el último Relay, la etapa y el error cuando un enlace empieza a fallar; still failing con un recuento cada 5 minutos; una línea informativa cuando las peticiones solo tienen éxito tras reintentos; y recovered con el número de peticiones fallidas y reintentadas en la primera conexión limpia. El daemon de Docker del destino registra de la misma manera los túneles entrantes que fallan, por propietario del endpoint (relay endpoint tunnels), y por separado los rechazos en rutas revocadas (relay endpoint tunnels on revoked routes). Los detalles de cada intento están en el nivel debug.

Recuperación segura

• Corrige el DNS solo después de confirmar la ubicación prevista en los nodos.
• Corrige la asignación de un certificado en lugar de desactivar TLS de forma global.
• Corrige la validación de la configuración antes de forzar otra aplicación.
• Usa el modo de mantenimiento cuando la aplicación deba seguir sin estar disponible durante la reparación.
• Reintenta la conciliación solo cuando la dependencia que causó el fallo esté en buen estado.
• Revierte la aplicación o la configuración de la Route cuando exista una revisión que se sabe que funciona.

No elimines y vuelvas a crear el dominio, el certificado o la Route como primera respuesta. Eso destruye el historial de relaciones y puede introducir una segunda caída.

Verificación de la recuperación

Prueba desde un cliente externo y confirma después el nombre de host canónico, la cadena de certificados, el código de estado, el cuerpo, las redirecciones, los WebSockets, el historial de estado y los logs de nginx. Cierra el incidente solo cuando el comportamiento público y el estado de Opfield coincidan.

Reversión según la capa que falló

La reversión debe deshacer el cambio más pequeño que introdujo la caída. Para el DNS, restaura los valores de dirección registrados y ten en cuenta las cachés de los resolutores. Para TLS, restaura la asignación anterior de un certificado válido sin desactivar HTTPS. Para la configuración de nginx, vuelve a los últimos ajustes gestionados que se sabe que funcionaban y espera la confirmación. Para una regresión de la aplicación, revierte el Deployment o la revisión de Compose propietarios en lugar de reescribir la Route para sortear una versión defectuosa.

Los fallos de Secure Link requieren restablecer la conectividad de Relay y de los nodos o el entorno de ejecución del destino; cambiar el DNS o los certificados no puede repararlos. Los fallos de política de acceso requieren restaurar la Access List anterior o la interpretación anterior de los proxies de confianza, no abrir el puerto de la carga de trabajo. El modo de mantenimiento es útil mientras reparas estas capas, porque mantiene explícitos el nombre de host y la ruta TLS a la vez que evita tráfico accidental hacia una aplicación recuperada a medias.

Pruebas para escalar

Cuando el primer intento de recuperación no explica el fallo, reúne un conjunto acotado de pruebas antes de escalar:

• los identificadores del dominio y de la Route, el nodo Ingress asignado y la última revisión de configuración confirmada;
• las respuestas DNS externas y los detalles del certificado TLS observados en el momento del incidente;
• el historial de estado de la Route y la ruta, el método, el código y la marca de tiempo exactos de la petición que falla;
• las entradas relevantes de acceso y de errores de nginx y la operación de la carga de trabajo o del Secure Link propietarios;
• las versiones de los nodos y de Relay, el estado de conectividad y el mensaje del último Task fallido;
• la última revisión de la aplicación, de la Route y del DNS que se sabe que funcionaba.

Oculta las credenciales, las cookies, las cabeceras de autorización, las claves privadas y los valores de consulta sensibles. El objetivo es conservar la causalidad sin convertir el registro de un incidente en un almacén de secretos.