ADR-0001. Traefik label-based dynamic routing over a static route table

Field	Value
Status	Accepted
Date	2025-01-20
Deciders	@platform
Supersedes	—

Context

• The platform runs ~13 backend services in Docker Compose, each owning its own /v1/api/<svc> prefix; the set grows over time.
• A hand-maintained central route table drifts: every new service or port change needs a coordinated edit + gateway reload.
• We want zero gateway redeploy when a service is added, and a mechanical migration path to Kubernetes.
• Each service already sets APP_ENV_SERVER_BASE_PATH=/v1/api/<svc> — routing is fully derivable from the service itself.

Decision

We will use Traefik v3.6 with the Docker provider: each service self-registers its router, load-balancer port, health check, and middleware references via Docker labels. There is no central route table in the production proxy layer.

Consequences

Pros	Cons
New service routes appear automatically — no gateway config change	Routing is decentralized; the full route map lives across many compose files
Labels convert mechanically to Traefik IngressRoute CRDs for K8s	PathPrefix is a pure prefix match — overlaps need explicit priority (see Routing)
Built-in resilience (circuit breaker, rate limit, health checks) without plugins	Traefik adds a dependency on the Docker socket
Hot-reload of shared middlewares via the file provider	Shared middlewares must use the @file suffix or fail silently

Alternatives Considered

Option	Pros	Cons	Why rejected
Static central route table (Nginx/HAProxy file)	One file to read; predictable	Manual edit + reload per change; drifts	Operational toil; no auto-discovery
Kong / APISIX (DB/etcd-backed routes)	Rich plugin ecosystem	Requires PostgreSQL/etcd; heavier footprint	Operational overhead for a gateway-only need
Envoy (xDS)	Most powerful, mesh-ready	Highest config complexity; no Docker label discovery	Overkill without a service mesh

References

• Gateway Selection Report — Traefik scored 4.60/5
• Routing