Domaines, Routes et TLS

Pour un DNS Cloudflare géré, configurez l’intégration Cloudflare avant de sélectionner des zones et de créer des enregistrements de domaine. Un connecteur DNS ne remplace ni le nœud ingress ni sa configuration TLS.

Cette chaîne de ressources transforme une application en point de terminaison public stable. Un domaine représente le nom d’hôte et l’endroit où il est servi, une Route définit ce qu’Opfield fait des requêtes correspondantes, et un certificat TLS prouve le nom d’hôte aux clients HTTPS. Ensemble, ils donnent au nom d’hôte un trafic chiffré, un upstream explicite et un chemin de retour arrière.

Dans la console, Routes et Domains sont des onglets de la page Routes, et les certificats TLS se trouvent dans l’onglet SSL de la page Certificates.

Opfield émet et renouvelle les certificats Let’s Encrypt et gère les enregistrements DNS dans les zones Cloudflare connectées via l’intégration. Le DNS chez tout autre fournisseur et la disponibilité propre de l’application restent de votre ressort : décidez qui en est responsable, ainsi que de la bascule en production, avant de commencer.

Le succès signifie que le nom d’hôte canonique se résout vers le nœud Ingress prévu, que HTTPS présente le certificat attendu, que la Route atteint l’application prévue, et que la santé selon Opfield et une requête externe indépendante concordent.

Domaines

Enregistrez chaque nom d’hôte une seule fois et attribuez-le à un nœud nginx éligible dont l’adresse de service publique a été détectée. Une Route et son domaine doivent rester sur le même nœud. Les domaines gérés par Cloudflare peuvent réconcilier les enregistrements A/AAAA ; le DNS externe reste de la responsabilité de l’opérateur. Ouvrir un domaine ne fait que lire ses enregistrements DNS ; Opfield ne répare les enregistrements Cloudflare que lorsque vous le demandez.

Via l’API et MCP, nginxNodeId peut être omis lorsqu’exactement un nœud éligible avec une adresse publique détectée est ouvert au droit domains:create de l’appelant. Sinon, la requête échoue avec 409 DOMAIN_NGINX_NODE_REQUIRED et liste les nœuds éligibles. GET /api/domains/nginx-nodes, ou manage_domain avec l’opération list_nginx_nodes via MCP, les liste pour tout détenteur de domains:create ; aucune permission sur les nœuds n’est nécessaire.

Certificats

Émettez des certificats Let’s Encrypt via HTTP-01 ou DNS-01, ou téléversez du matériel existant. HTTP-01 exige que le nœud attribué soit publiquement joignable sur le port 80. Opfield ne distribue le matériel de clé privée qu’aux nœuds dont des Routes TLS activées l’utilisent.

Routes

Choisissez le domaine, le comportement, l’upstream, le certificat TLS et la politique de santé. N’activez les WebSockets, les réécritures, les en-têtes, la mise en mémoire tampon ou les changements de délais que si l’application l’exige.

Un nœud Ingress ne répond en TLS que pour les noms d’hôte que sert l’une de ses Routes. Une requête TLS pour tout autre nom est refusée pendant la poignée de main au lieu de recevoir le certificat et le site d’une autre Route. La mise à jour du démon installe ce comportement sur les nœuds existants ; lorsque le nginx propre au nœud a déjà un serveur par défaut sur le port 443, la mise à jour l’ignore et consigne un avertissement. Lorsque nginx refuse une modification de configuration, la modification échoue avec 422 NGINX_CONFIG_FAILED, pour les Routes HTTP comme HTTPS, et l’erreur inclut la sortie de nginx -t ; le nœud conserve sa configuration précédente. Une Route sans vérification de santé affiche sa santé comme Unknown.

Raw Config Mode vous confie toute la configuration nginx de la Route. Il part de la configuration générée, et Opfield cesse de générer la Route tant que le mode brut n’est pas désactivé. Une Route vers une charge de travail Docker conserve son Secure Link en mode brut : l’upstream prérempli, le socket du lien sur le nœud Ingress, continue d’atteindre la charge de travail et la suit lorsque son conteneur est recréé ; modifiez donc la configuration selon vos besoins, mais continuez à faire proxy vers cet upstream. La configuration brute, le contenu des modèles nginx et la configuration avancée des Additional Routes passent les mêmes contrôles de directives : sans proxy:unrestricted, les directives interdites sont refusées et les journaux nginx ne peuvent être écrits que sous /var/log/nginx.

Deux Routes activées sur le même nœud ne peuvent pas servir le même nom, car nginx n’en servirait qu’une. Créer, activer ou modifier une Route, ou la déplacer vers un autre nœud, de sorte qu’elle serve un nom déjà servi par une autre Route activée sur ce nœud échoue avec 409 PROXY_HOST_DOMAIN_CONFLICT, qui nomme l’autre Route. Les noms sont comparés sans tenir compte de la casse. Les Routes qui se chevauchaient déjà avant la mise à jour vers 2.11 conservent leur configuration ; voir Conflits résolus par la mise à jour 2.11.

Choisir le nœud Ingress

Une Route s’exécute sur un nœud Ingress nginx, ou sur chaque membre d’un groupe d’ingress. Dans la boîte de dialogue Create Route, choisir un domaine enregistré renseigne son nœud. Les utilisateurs qui peuvent créer des Routes de manière large ou dans un dossier peuvent aussi sélectionner Automatic (from the registered domain) et laisser Opfield choisir ; s’il n’y parvient pas, l’erreur liste les nœuds parmi lesquels choisir. Via l’API et MCP, nodeId est facultatif sur POST /api/proxy-hosts et create_route, et Opfield résout le nœud dans cet ordre :

1. Un nodeId explicite est utilisé tel quel.
2. Les domaines enregistrés parmi les noms de la Route imposent leur nœud Ingress, par correspondance exacte ou via un wildcard couvrant. Des domaines enregistrés sur des nœuds différents ne peuvent pas partager une Route : 409 DOMAIN_NGINX_NODE_MISMATCH.
3. Sinon, le seul nœud nginx sur lequel l’appelant peut créer des Routes à cette destination est utilisé, à condition qu’il soit en ligne. Les nœuds encore en attente d’enrôlement ne sont jamais choisis ni proposés. Une Route n’est jamais placée automatiquement sur un nœud déconnecté ; passez explicitement l’identifiant de ce nœud si vous voulez l’y placer.
4. Sinon, la requête échoue : 409 ROUTE_INGRESS_NODE_REQUIRED lorsque plusieurs nœuds conviennent ou que le seul candidat est hors ligne, avec les nœuds listés dans le message et dans details.eligibleNodes ; 409 ROUTE_INGRESS_NODE_UNAVAILABLE lorsqu’aucun n’est disponible ; ou 403 lorsque l’appelant n’a aucun droit proxy:create pour la destination.

GET /api/proxy-hosts/ingress-nodes, ou list_route_ingress_nodes via MCP, liste les nœuds éligibles avec uniquement leur identifiant, leur nom d’affichage, leur nom d’hôte et leur état. Il nécessite un droit proxy:create quelconque et aucune permission sur les nœuds. Un droit proxy:create large ou sur un dossier couvre chaque nœud nginx, un droit sur node/<nodeId> ne couvre que ce nœud, et les nœuds verrouillés pour les nouveaux services ne sont jamais proposés. Passez folderId lorsque la Route sera créée dans un dossier ; un créateur limité à un dossier doit le passer dans tous les cas. Le nœud résolu passe les contrôles habituels : le droit sur le nœud, le dossier de destination, le placement du domaine et le verrou de création de services.

Migration

Utilisez le processus explicite de migration de l’ingress pour déplacer un domaine et ses Routes. Le DNS Cloudflare peut être modifié pendant la bascule ; le DNS externe nécessite une mise à jour confirmée par l’opérateur. Vérifiez la cible avant de retirer le placement source. Si une Route activée sur le nœud cible sert déjà l’un des noms déplacés, la migration est refusée avec 409 DOMAIN_INGRESS_TARGET_DOMAIN_CONFLICT avant toute modification.

Prérequis et permissions

Le nœud Ingress cible doit être en ligne, signaler une adresse de service utilisable et prendre en charge le défi de certificat prévu. L’appelant doit avoir accès au domaine, à la Route, au certificat, à la charge de travail cible et à toute Access List réutilisable concernée par le changement.

Pour un DNS géré en externe, abaissez le TTL avant une migration planifiée et consignez les enregistrements actuels. Pour un DNS géré par Cloudflare, vérifiez le périmètre du connecteur et la liste d’autorisation des zones avant de demander à Opfield de modifier des enregistrements.

Configurer la chaîne complète

1. Créez ou sélectionnez le domaine et placez-le sur un nœud Ingress.
2. Confirmez que le DNS pointe vers l’adresse de service publique sélectionnée.
3. Émettez ou téléversez un certificat couvrant le nom d’hôte exact.
4. Créez la Route et sélectionnez le comportement proxy, redirection ou 404.
5. Sélectionnez l’upstream et le protocole applicatif.
6. Rattachez TLS, la politique d’accès, les vérifications de santé et les options de protocole.
7. Enregistrez et attendez la validation et l’application de nginx.
8. Vérifiez le point de terminaison public depuis l’extérieur du réseau géré.

Pour les certificats wildcard ou multi-noms, vérifiez chaque nom d’hôte avant de les réutiliser. L’existence d’un certificat ne signifie pas qu’il est distribué ; la distribution suit le placement des Routes TLS activées.

Conséquences des modifications et des suppressions

• Déplacer un domaine change l’endroit où toutes ses Routes sont servies.
• Remplacer un certificat affecte chaque Route TLS rattachée après distribution.
• Désactiver une Route préserve sa configuration, mais arrête l’hôte virtuel géré.
• Supprimer une Route met hors service les Secure Links qui lui appartiennent, mais ne supprime pas les certificats ou Access Lists réutilisables.
• Supprimer un domaine exige d’avoir d’abord retiré ou migré ses Routes dépendantes.
• Un certificat utilisé par une Route ou par le profil wildcard de Pages ne peut pas être supprimé : la requête échoue avec 409 CERT_IN_USE et les identifiants des Routes qui l’utilisent. Détachez d’abord le certificat ; sa suppression retire alors la copie gérée par Opfield.

Liste de vérification

• Le DNS externe se résout vers le nœud prévu.
• Le comportement HTTP est délibéré : redirection, réponse ou désactivation.
• HTTPS sert le certificat attendu et la chaîne complète.
• Les vérifications de santé utilisent le chemin et le code de réponse prévus.
• Les paramètres WebSocket et de délais correspondent à l’application.
• La configuration nginx est valide et la dernière révision est acquittée.
• Les journaux d’accès et d’erreurs montrent la requête de vérification externe.

Renouvellement et changements de placement

Le renouvellement d’un certificat et la migration d’un domaine sont des opérations distinctes. Un certificat renouvelé doit être émis avec succès, stocké par Opfield, distribué à chaque nœud Ingress éligible qui sert une Route TLS rattachée, et acquitté par nginx. Vérifiez la nouvelle période de validité et le certificat servi à l’extérieur ; un enregistrement d’émission réussie n’est pas à lui seul la vérification finale.

Pour les changements de placement, préparez le nœud cible avant de modifier le DNS. Confirmez la capacité nginx, les adresses de service publiques, la disponibilité du certificat, la configuration de la Route, la joignabilité de l’upstream et les vérifications de santé sur la cible. Lorsque le DNS est externe, ne modifiez les enregistrements qu’une fois la cible prête et gardez la source disponible au moins pendant la durée prévue du TTL et des caches. Lorsqu’Opfield gère le DNS Cloudflare, vérifiez malgré tout les réponses publiques obtenues plutôt que de supposer que l’opération du fournisseur s’est terminée partout immédiatement.

Frontières de défaillance et de retour arrière

Si la validation de la configuration échoue, la révision invalide ne doit pas remplacer la dernière configuration nginx acquittée. Lisez l’erreur de validation, corrigez le plus petit paramètre concerné et appliquez à nouveau. Ne détachez pas un certificat fonctionnel et ne déplacez pas le domaine simplement pour contourner une erreur de syntaxe ou de sélection d’upstream.

Si une migration échoue avant la bascule DNS, gardez le trafic sur la source et réparez la cible. Si le DNS externe a déjà été modifié, rétablissez les enregistrements source consignés ou terminez la réparation de la cible selon la décision prise pour l’incident ; évitez d’alterner les enregistrements à répétition, car les résolveurs récursifs peuvent observer des états différents. Après un retour arrière, vérifiez à la fois la résolution de l’adresse publique et le certificat réellement servi par la source.

Opfield ne peut pas annuler les écritures applicatives ni les modifications DNS externes effectuées hors de son processus géré. Conservez les valeurs DNS précédentes, l’attribution du certificat et la révision applicative dans l’enregistrement du changement.