Dominios, Routes y TLS

Para el DNS gestionado de Cloudflare, configura la integración con Cloudflare antes de seleccionar zonas y crear registros de dominio. Un conector DNS no sustituye al nodo de ingress ni a su configuración TLS.

Esta cadena de recursos convierte una aplicación en un endpoint público estable. Un Domain representa el nombre de host y dónde se sirve, una Route define qué hace Opfield con las peticiones que coinciden y un certificado TLS demuestra el nombre de host ante los clientes HTTPS. Juntos dan al nombre de host tráfico cifrado, un upstream explícito y un camino de reversión.

En la consola, las Routes y los dominios son pestañas de la página Routes, y los certificados TLS están en la pestaña SSL de la página Certificates.

Opfield emite y renueva certificados de Let’s Encrypt y gestiona los registros DNS en las zonas de Cloudflare conectadas mediante la integración. El DNS en cualquier otro proveedor y la preparación de la propia aplicación siguen siendo responsabilidad tuya: decide antes de empezar quién es responsable de ellos y del cambio a producción.

El éxito significa que el nombre de host canónico se resuelve al nodo Ingress previsto, HTTPS presenta el certificado esperado, la Route llega a la aplicación prevista, y tanto el estado en Opfield como una petición externa independiente coinciden.

Dominios

Registra cada nombre de host una vez y asígnalo a un nodo nginx compatible con una dirección de servicio pública detectada. Una Route y su dominio deben permanecer en el mismo nodo. Los dominios gestionados por Cloudflare pueden conciliar los registros A/AAAA; el DNS externo sigue siendo responsabilidad del operador. Abrir un dominio solo lee sus registros DNS; Opfield repara los registros de Cloudflare solo cuando se lo pides.

A través de la API y de MCP, nginxNodeId se puede omitir cuando hay exactamente un nodo compatible con una dirección pública detectada abierto a la concesión domains:create de quien llama. En caso contrario, la petición falla con 409 DOMAIN_NGINX_NODE_REQUIRED y enumera los nodos compatibles. GET /api/domains/nginx-nodes, o manage_domain con la operación list_nginx_nodes por MCP, los enumera para cualquiera que tenga domains:create; no se necesita ningún permiso sobre nodos.

Certificados

Emite certificados de Let’s Encrypt mediante HTTP-01 o DNS-01, o sube material existente. HTTP-01 requiere que el nodo asignado sea accesible públicamente en el puerto 80. Opfield distribuye el material de las claves privadas solo a los nodos con Routes TLS activadas que lo usan.

Routes

Elige el dominio, el comportamiento, el upstream, el certificado TLS y la política de estado. Activa WebSockets, reescrituras, cabeceras, búferes o cambios de tiempos de espera solo cuando la aplicación lo requiera.

Un nodo Ingress responde a TLS solo para los nombres de host que sirve alguna de sus Routes. Una petición TLS para cualquier otro nombre se rechaza durante el handshake en lugar de recibir el certificado y el sitio de otra Route. La actualización del daemon instala esto en los nodos existentes; cuando el propio nginx del nodo ya tiene un servidor predeterminado en el puerto 443, la actualización lo omite y registra una advertencia. Cuando nginx rechaza un cambio de configuración, el cambio falla con 422 NGINX_CONFIG_FAILED tanto en las Routes HTTP como en las HTTPS, y el error incluye la salida de nginx -t; el nodo conserva su configuración anterior. Una Route sin comprobaciones de estado muestra su estado como Unknown.

Raw Config Mode te entrega toda la configuración de nginx de la Route. Parte de la configuración generada, y Opfield deja de generar la Route hasta que se desactiva el modo en bruto. Una Route hacia una carga de trabajo Docker conserva su Secure Link en modo en bruto: el upstream precargado, el socket del enlace en el nodo Ingress, sigue llegando a la carga de trabajo y la sigue cuando se recrea su contenedor, así que edita la configuración como necesites, pero sigue haciendo de proxy hacia ese upstream. La configuración en bruto, el contenido de las plantillas de nginx y la configuración avanzada de las Additional Routes pasan las mismas comprobaciones de directivas: sin proxy:unrestricted, las directivas denegadas se rechazan y los logs de nginx solo se pueden escribir en /var/log/nginx.

Dos Routes activadas en el mismo nodo no pueden servir el mismo nombre, porque nginx solo serviría una de ellas. Crear, activar o editar una Route, o moverla a otro nodo, de modo que sirva un nombre que ya sirve otra Route activada en ese nodo falla con 409 PROXY_HOST_DOMAIN_CONFLICT, que indica la otra Route. Los nombres se comparan sin distinguir mayúsculas de minúsculas. Las Routes que ya se solapaban antes de la actualización a la 2.11 conservan su configuración; consulta Conflictos resueltos por la actualización a la 2.11.

Elige el nodo Ingress

Una Route se ejecuta en un nodo Ingress nginx, o en todos los miembros de un grupo de ingress. En el diálogo Create Route, elegir un dominio registrado rellena su nodo. Los usuarios que pueden crear Routes de forma amplia o en una carpeta también pueden seleccionar Automatic (from the registered domain) y dejar que elija Opfield; si no puede, el error enumera los nodos entre los que elegir. A través de la API y de MCP, nodeId es opcional en POST /api/proxy-hosts y create_route, y Opfield resuelve el nodo en este orden:

1. Un nodeId explícito se usa tal cual.
2. Los dominios registrados entre los nombres de la Route fijan su nodo Ingress, por coincidencia exacta o mediante un comodín que los cubra. Los dominios registrados en nodos distintos no pueden compartir una Route: 409 DOMAIN_NGINX_NODE_MISMATCH.
3. En caso contrario, se usa el único nodo nginx en el que quien llama puede crear Routes en ese destino, siempre que esté en línea. Los nodos que todavía están pendientes de registro nunca se eligen ni se ofrecen. Una Route nunca se coloca automáticamente en un nodo desconectado; pasa explícitamente el ID de ese nodo si la quieres allí.
4. En caso contrario, la petición falla: 409 ROUTE_INGRESS_NODE_REQUIRED cuando cumplen los requisitos varios nodos o el único está desconectado, con los nodos enumerados en el mensaje y en details.eligibleNodes; 409 ROUTE_INGRESS_NODE_UNAVAILABLE cuando no hay ninguno disponible; o 403 cuando quien llama no tiene ninguna concesión proxy:create para el destino.

GET /api/proxy-hosts/ingress-nodes, o list_route_ingress_nodes por MCP, enumera los nodos compatibles solo con su ID, su nombre visible, su nombre de host y su estado. Requiere cualquier concesión proxy:create y ningún permiso sobre nodos. Una concesión proxy:create amplia o por carpeta cubre todos los nodos nginx, una concesión sobre node/<nodeId> cubre solo ese nodo, y los nodos bloqueados para servicios nuevos nunca se ofrecen. Pasa folderId cuando la Route vaya a crearse en una carpeta; un creador limitado a carpetas debe pasarlo en cualquier caso. El nodo resuelto pasa las comprobaciones habituales: la concesión sobre el nodo, la carpeta de destino, la ubicación del dominio y el bloqueo de creación de servicios.

Migración

Usa el flujo explícito de migración de ingress para mover un dominio y sus Routes. El DNS de Cloudflare se puede cambiar durante el cambio final; el DNS externo requiere una actualización confirmada por el operador. Verifica el destino antes de eliminar la ubicación de origen. Si una Route activada en el nodo de destino ya sirve uno de los nombres que se mueven, la migración se rechaza con 409 DOMAIN_INGRESS_TARGET_DOMAIN_CONFLICT antes de que cambie nada.

Requisitos previos y permisos

El nodo Ingress de destino debe estar en línea, informar de una dirección de servicio utilizable y admitir el desafío de certificado previsto. Quien llama necesita acceso al dominio, a la Route, al certificado, a la carga de trabajo de destino y a cualquier Access List reutilizable implicada en el cambio.

Para el DNS gestionado externamente, reduce el TTL antes de una migración planificada y registra los registros actuales. Para el DNS gestionado por Cloudflare, verifica el alcance del conector y la lista de zonas permitidas antes de pedir a Opfield que modifique registros.

Configura la cadena completa

1. Crea o selecciona el dominio y colócalo en un nodo Ingress.
2. Confirma que el DNS apunta a la dirección de servicio pública seleccionada.
3. Emite o sube un certificado que cubra el nombre de host exacto.
4. Crea la Route y selecciona el comportamiento de proxy, redirección o 404.
5. Selecciona el upstream y el protocolo de la aplicación.
6. Asocia TLS, la política de acceso, las comprobaciones de estado y las opciones de protocolo.
7. Guarda y espera a la validación y la aplicación en nginx.
8. Verifica el endpoint público desde fuera de la red gestionada.

Para los certificados comodín o con varios nombres, verifica cada nombre de host antes de reutilizarlos. Que un certificado exista no significa que esté distribuido; la distribución sigue la ubicación de las Routes TLS activadas.

Consecuencias de los cambios y de la eliminación

• Mover un dominio cambia dónde se sirven todas sus Routes.
• Sustituir un certificado afecta, tras la distribución, a todas las Routes TLS asociadas.
• Desactivar una Route conserva la configuración, pero detiene el host virtual gestionado.
• Eliminar una Route retira los Secure Links propiedad de la Route, pero no elimina los certificados ni las Access Lists reutilizables.
• Eliminar un dominio requiere eliminar o migrar antes las Routes que dependen de él.
• Un certificado que usa una Route o el perfil comodín de Pages no se puede eliminar: la petición falla con 409 CERT_IN_USE y los ID de las Routes que lo usan. Desvincula antes el certificado; al eliminarlo después se elimina la copia gestionada de Opfield.

Lista de comprobación de verificación

• El DNS externo se resuelve al nodo previsto.
• El comportamiento HTTP es deliberado: redirección, respuesta o desactivado.
• HTTPS sirve el certificado esperado y la cadena completa.
• Las comprobaciones de estado usan la ruta y el código esperados.
• Los ajustes de WebSocket y de tiempos de espera se ajustan a la aplicación.
• La configuración de nginx es válida y la última revisión está confirmada.
• Los logs de acceso y de errores muestran la petición de verificación externa.

Renovación y cambios de ubicación

La renovación de certificados y la migración de dominios son operaciones separadas. Un certificado renovado debe emitirse correctamente, guardarse en Opfield, distribuirse a cada nodo Ingress compatible que sirve una Route TLS asociada y ser confirmado por nginx. Comprueba el nuevo periodo de validez y el certificado que se sirve externamente; un registro de emisión correcto por sí solo no es la verificación final.

Para los cambios de ubicación, prepara el nodo de destino antes de cambiar el DNS. Confirma la capacidad de nginx, las direcciones de servicio públicas, la disponibilidad del certificado, la configuración de la Route, la accesibilidad del upstream y las comprobaciones de estado en el destino. Cuando el DNS es externo, cambia los registros solo cuando el destino esté listo y mantén disponible el origen durante al menos el TTL y la ventana de caché esperados. Cuando Opfield gestiona el DNS de Cloudflare, verifica igualmente las respuestas públicas resultantes en lugar de suponer que la operación del proveedor se completó en todas partes de inmediato.

Límites de los fallos y de la reversión

Si la validación de la configuración falla, la revisión no válida no debe sustituir a la última configuración de nginx confirmada. Lee el error de validación, corrige el ajuste relevante más pequeño y vuelve a aplicar. No desvincules un certificado que funciona ni muevas el dominio solo para sortear un error de sintaxis o de selección del upstream.

Si una migración falla antes del cambio de DNS, mantén el tráfico en el origen y repara el destino. Si el DNS externo ya se cambió, restaura los registros de origen registrados o completa la reparación del destino según la decisión tomada en el incidente; evita alternar los registros repetidamente, porque los resolutores recursivos pueden observar estados distintos. Tras la reversión, verifica tanto la resolución de la dirección pública como el certificado que sirve realmente el origen.

Opfield no puede revertir las escrituras de las aplicaciones ni los cambios de DNS externos que se produjeron fuera de su flujo gestionado. Conserva los valores DNS anteriores, la asignación del certificado y la revisión de la aplicación como parte del registro del cambio.