---
title: Infra — Patterns validés : Docker networking
domain: infra
bucket: patterns
tags: [docker, networking, bridge, traefik, host-gateway, firewall]
applies_to: [architecture, implementation, debug]
severity: medium
validated_on: 2026-06-25
source_projects: [_Assistant_Cuisine]
---

# Infra — Patterns validés : Docker networking

> Extrait de la base de connaissance Lead_tech. Voir `knowledge/infra/patterns/README.md` pour l'index complet.

---

<a id="pattern-bridge-isole-service-hote"></a>
## Bridges Docker isolés — un container ne peut pas joindre un service hôte par défaut

### Constat

Un container connecté à un bridge custom (ex. `traefik-net` en `172.21.0.0/16`) ne peut **pas** atteindre par défaut :

- l'IP hôte côté `docker0` (`172.17.0.1`)
- l'IP hôte sur d'autres interfaces (ex. IP Tailscale `100.x.x.x`)
- `host.docker.internal` (qui résout vers `172.17.0.1`, donc même blocage)

Même quand l'hôte écoute bien sur `0.0.0.0:PORT`, l'appel depuis le container part en timeout. Cause : sous Docker 29 + iptables/nftables strict, les bridges sont isolés entre eux et le forward bridge → host est bloqué par défaut.

**Conséquence** : faire pointer un router Traefik vers `host.docker.internal:PORT` pour atteindre un service systemd hôte ne fonctionne pas en bridge mode.

### Bonnes pratiques / solutions (par ordre de propreté)

**Solution 1 (préférée) — Conteneuriser le service hôte**

Mettre le service dans un container connecté au même bridge (`traefik-net`). La communication passe par le DNS Docker interne (`servicename:port`). Aucune complexité réseau, fonctionne nativement. C'est presque toujours possible (ex. code-server via l'image `lscr.io/linuxserver/code-server`).

**Solution 2 — Traefik en `network_mode: host`**

Traefik abandonne son bridge custom et écoute directement sur les interfaces hôte. Il atteint tous les services hôte trivialement, MAIS perd l'accès aux containers via bridge : il faut alors leur publier des ports hôte, ce qui défait l'intérêt du reverse proxy interne. Réservé aux setups simples où Traefik ne sert que des services hôte.

**Solution 3 — Ouvrir manuellement le firewall**

```bash
sudo iptables -I DOCKER-USER -s 172.21.0.0/16 -d 172.21.0.1 -p tcp --dport <PORT> -j ACCEPT
```

Fragile : règle volatile, à refaire au reboot ou à l'upgrade Docker. Si on prend ce chemin, documenter et provisionner via une unit systemd.

### Anti-pattern : `extra_hosts: host.docker.internal:host-gateway`

Cette ligne déclare seulement un alias DNS dans le `/etc/hosts` du container ; elle ne crée **aucune route réseau**. Si le firewall Docker bloque, l'alias ne sert à rien : le container résout `host.docker.internal` mais le SYN reste bloqué.

**Règle** : avant de partir sur la Solution 2 ou 3, toujours vérifier qu'on ne peut pas conteneuriser le service. C'est presque toujours possible et toujours plus propre.

- Contexte technique : Docker 29 / Traefik / NUC — _Assistant_Cuisine 04-05-2026