archicratie-edition/docs/runbooks/EDGE-TRAEFIK.md

RUNBOOK — Edge Traefik (routing + SSO Authelia)

Objectif : comprendre et diagnostiquer rapidement qui route quoi, et pourquoi staging/live peuvent diverger.

0) Portée

Edge Traefik route plusieurs hosts vers des backends locaux (127.0.0.1:*), avec Auth via Authelia.

Répertoire :

• /volume2/docker/edge/config/dynamic/

Port d’entrée edge :

• http://127.0.0.1:18080/ (entryPoint web)
• Les hosts publics pointent vers cet edge.

1) Fichiers dynamiques (canon)

00-smoke.yml

• route /__smoke vers le service smoke_svc → 127.0.0.1:18081

10-core.yml

• définit les middlewares :
  • sanitize-remote
  • authelia (forwardAuth vers 9091)
  • chain-auth (chain sanitize-remote + authelia)

20-archicratie-backend.yml

• définit service archicratie_web → 127.0.0.1:8082 (live upstream)

21-archicratie-staging.yml

• route staging host vers 127.0.0.1:8081 (staging upstream)
• applique middlewares diag-staging@file et chain-auth@file
• IMPORTANT : diag-staging@file doit exister

22-archicratie-authinfo-staging.yml

• route / _auth / sur staging vers whoami@file
• applique diag-staging-authinfo@file + chain-auth@file
• IMPORTANT : diag-staging-authinfo@file doit exister

90-overlay-staging-fix.yml (overlay de diagnostic + fallback)

Rôle :

• fournir les middlewares manquants (diag-staging, diag-staging-authinfo)
• optionnel : fallback route si 21/22 sont cassés
• injecter un header X-Archi-Router pour identifier le routeur utilisé

92-overlay-live-fix.yml

• route live host archicratie.trans-hands.synology.me → archicratie_web@file (8082)
• route / _auth/whoami → whoami@file (18081)

2) Diagnostiquer rapidement : quel routeur répond ?

2.1 Test “host header” (sans UI)

en bash :

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/
| grep -iE 'HTTP/|location:|x-archi-router' | head -n 30

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/_auth/whoami
| grep -iE 'HTTP/|location:|x-archi-router' | head -n 30

Interprétation :

X-Archi-Router: staging@21 → routeur 21-archicratie-staging.yml OK

X-Archi-Router: staging-authinfo@22 → routeur authinfo OK

Si tu vois staging-fallback@90 → tu es tombé sur le fallback 90 (donc 21/22 potentiellement invalides)

2.2 Vérifier l’upstream direct derrière edge

curl -sSI http://127.0.0.1:8081/ | head -n 12 curl -sSI http://127.0.0.1:8082/ | head -n 12

Si 8081 et 8082 servent des versions différentes : c’est “normal” en blue/green, mais il faut savoir laquelle est censée être staging/live.

3) Diagnostiquer les erreurs Traefik (fichier invalide / middleware manquant)

3.1 Grep “level=error”

sudo docker logs edge-traefik --since 5m | grep -Ei 'level=error|middleware|router|service|yaml' | tail -n 80

Cas typique :

middleware "diag-staging@file" does not exist → 21-archicratie-staging.yml référence un middleware absent. Solution : le définir (souvent dans 90-overlay-staging-fix.yml).

4) Procédure safe de modification (jamais en aveugle)

4.1 Backup

cd /volume2/docker/edge/config/dynamic TS="$(date +%F-%H%M%S)" sudo cp -a 90-overlay-staging-fix.yml "90-overlay-staging-fix.yml.bak.$TS"

4.2 Édition (ex : ajouter middlewares diag)

Faire une modif minimale

Ne pas casser les règles existantes (Host + PathPrefix)

Respecter les priorités (voir section 5)

4.3 Reload Traefik

sudo docker restart edge-traefik

4.4 Tests immédiats

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/
| grep -iE 'HTTP/|location:|x-archi-router'

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/_auth/whoami
| grep -iE 'HTTP/|location:|x-archi-router'

5) Priorités Traefik (le point subtil)

Traefik choisit le routeur selon :

la correspondance de règle

la priority (plus grand gagne)

en cas d’égalité, l’ordre interne (à éviter)

5.1 Canon pour staging

21-archicratie-staging.yml : priority 10

22-archicratie-authinfo-staging.yml : priority 10000

90-overlay-staging-fix.yml :

fallback host : priority faible (ex: 5) pour ne PAS écraser 21

fallback whoami : priority < 10000 (ex: 9000) pour ne PAS écraser 22

=> On garde 90 comme filet de sécurité / diag, pas comme “source”.

6) Rollback (si un changement edge casse staging/live)

cd /volume2/docker/edge/config/dynamic

choisir le bon backup

sudo mv -f 90-overlay-staging-fix.yml "90-overlay-staging-fix.yml.BAD.$(date +%F-%H%M%S)" sudo cp -a 90-overlay-staging-fix.yml.bak.YYYY-MM-DD-HHMMSS 90-overlay-staging-fix.yml sudo docker restart edge-traefik

Puis re-tests section 2.

7) Remarques

Les 302 Authelia sont normaux si non authentifié.

Un 404 “Not Found” depuis edge alors que 8081 répond : souvent routeur manquant / invalidé / middleware absent.