The Moving Parts
Traefik's whole vocabulary is five words. Everything in the configuration — and everything in this guide — is one of these, so it pays to learn them before touching a file.
| Part | What it is | Decided where |
|---|---|---|
| Entrypoint | A listening socket: a port Traefik accepts connections on | Static config |
| Provider | A source of truth Traefik watches: Docker, Kubernetes, a folder of files | Static config |
| Router | A rule that matches requests and sends them to a service | Dynamic config |
| Service | The actual backends: one or more server addresses | Dynamic config |
| Middleware | A step that edits or judges a request on its way through | Dynamic config |
Static and dynamic: the one big split
Traefik keeps two kinds of configuration strictly apart, and confusing them is the beginner's main source of pain.
Static configuration is read once,
at startup, and never again. It says
which ports to listen on (entrypoints),
which providers to watch, and global
choices like log level. Change it and you
restart Traefik. It can live in a file
(traefik.yml), command-line flags, or
environment variables — pick one source;
they do not merge.
Dynamic configuration is everything a provider supplies: routers, services, middleware, certificates. It can change at any moment and Traefik applies changes as they arrive, in about the time it takes to notice them. The lab in this guide uses the file provider — a watched folder — because it shows the mechanism with nothing else in the way. Docker and Kubernetes are providers too, supplying the same objects in different clothing (chapter 9).
A request's walk through the parts
- A connection arrives at an
entrypoint — say the one listening
on port 8000, named
web. - Traefik tries the routers attached to that entrypoint, in priority order. A router's rule looks at the request: the host name it asked for, the path, headers, and so on (chapter 5).
- The first router whose rule matches wins. Its middlewares run in order: perhaps redirect to HTTPS, demand a password, strip a path prefix (chapter 6).
- The router's service picks one of
its healthy servers and forwards the
request, adding
X-Forwarded-*headers that tell the backend where the request really came from. The lab's transcripts show those headers arriving. - The backend's reply walks back the same path. If no router matched, Traefik itself answers 404. If a router matched but every server is down, it answers 502. Chapter 15 leans on that distinction hard.
Names with addresses
Objects from providers carry the
provider's name as a suffix: fern@file
is the router fern learned from the
file provider, dashboard@internal is
built into Traefik itself. When a router
refers to a middleware or service from
another provider, the suffix is how you
say which one. Most "my middleware is
ignored" mysteries are a missing or
wrong suffix — chapter 15 again.
What breaks when each part stops
- The static config is wrong — Traefik refuses to start, and says why in the log. Annoying and honest.
- A dynamic file is wrong — Traefik logs the parse error and keeps serving the last good configuration. Forgiving, and easy to miss if you never read logs.
- A provider goes away — its routers vanish with it. Stop Docker and every Docker-learned site is gone.
- A backend stops — its service returns 502 until a health check marks the server out and the survivors take over (chapter 10).