nas-runbooks/common/nginx-proxy-dns-resolution.md

Règle d'Or : Résolution DNS Dynamique dans les Proxies Nginx Docker

1. Contexte du Problème (Cause Racine de l'Erreur 502)

Dans un environnement Docker où les conteneurs sont reliés par un réseau virtuel ( ou réseau nommé partagé comme n8n), chaque conteneur peut obtenir une nouvelle adresse IP interne (ex. 172.27.0.x) à chaque redémarrage, mise à jour ou recréation.

Par défaut dans Nginx, lorsqu'une directive proxy_pass utilise un nom d'hôte statique direct :

# ❌ CONFIGURATION VULNÉRABLE (Résolution DNS statique au boot)
location / {
    proxy_pass http://mon-backend:8080;
}

Nginx résout le nom mon-backend une seule fois au démarrage de Nginx et met l'adresse IP en cache de manière permanente en mémoire.

Conséquence :

Dès que mon-backend redémarre ou est mis à jour :

1. mon-backend reçoit une nouvelle adresse IP Docker (ex. 172.27.0.43).
2. Nginx continue d'envoyer les requêtes vers l'ancienne IP (ex. 172.27.0.37).
3. Nginx reçoit un Connection refused ou No route to host et renvoie un 502 Bad Gateway.
4. Le service reste en panne jusqu'à un redémarrage manuel du conteneur Nginx.

---

2. Le Pattern Requis : resolver 127.0.0.11 + Variable Dynamique

Pour forcer Nginx à réévaluer la résolution DNS selon le TTL Docker sans dépendre d'un cache figé, deux éléments sont indispensables :

1. La déclaration explicite du DNS interne Docker (127.0.0.11) avec un TTL court (ex. valid=10s).
2. L'assignation de l'URL cible dans une variable intermédiaire (set $upstream_var ...). Nginx est conçu pour ne pas pré-résoudre les variables au boot, mais au moment du traitement de la requête.

Configuration Standard Recommandée :

server {
    listen 80;
    server_name service.bolbol.tn;

    # 1. DNS interne Docker (127.0.0.11) avec re-résolution toutes les 10s
    resolver 127.0.0.11 valid=10s ipv6=off;

    # 2. Définition dynamique de l'amont via variable
    location / {
        set $backend_upstream http://mon-service:8080;
        proxy_pass $backend_upstream;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        chunked_transfer_encoding on;
    }
}

---

3. Périmètre Appliqué sur le NAS (21/08/2026)

Service Proxy	Fichier de Configuration	Statut
baserow-oauth-proxy	/volume1/docker/baserow-oauth-stub/nginx.conf	✅ Corrigé & Testé en direct
baserow-schema-mcp-proxy	/volume1/docker/baserow-schema-mcp/nginx.conf	✅ Corrigé & Validé
redaction-pro	/volume1/docker/redaction-pro/nginx.conf	✅ Corrigé & Validé
formation-consultant	/volume1/docker/formation-consultant/nginx.conf	N/A (fichiers statiques locaux, aucun upstream)

---

4. Protocole de Test de Résilience Obligatoire

Lors de la mise en place ou modification d'un reverse proxy Nginx :

1. Valider la syntaxe : docker exec <proxy> nginx -t
2. Recharger la config : docker exec <proxy> nginx -s reload
3. Test d'attribution dynamique : Redémarrer le conteneur backend (docker restart <backend>) et vérifier avec curl l'accès via le proxy sans toucher au conteneur proxy.