Ir para o conteúdo
Promovaweb

Providers e labels do Traefik

Um app novo ganha domínio e HTTPS sem nenhuma alteração na configuração do Traefik porque a rota vem de um provider, a fonte de onde o Traefik lê os serviços. O provider Docker acompanha os containers pela API do Docker Engine e transforma as labels de cada container em routers e services, por isso a rota fica escrita no Compose do próprio app.

Ficha e sumário da página
Referência técnica
Traefik v3.7.19
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Quatro famílias de providers
  2. Como o provider Docker lê os containers
  3. O que cada label declara
  4. As mesmas labels no Docker Swarm
  5. O provider de arquivo
  6. A rede proxy entre o Traefik e os apps

Quatro famílias de providers

O Traefik conversa com a API de cada provider, encontra os serviços declarados ali e monta a configuração de roteamento com o que leu. Quando algo muda na fonte, as rotas acompanham a mudança sem reinício do Traefik. A documentação agrupa os providers pelo jeito de declarar a rota:

  • Labels: no Docker e no Docker Swarm, a rota fica escrita no próprio container ou serviço.
  • Kubernetes: a rota vem de objetos do cluster, como o Ingress, o IngressRoute e o Gateway API.
  • Chave e valor: no Consul, no Etcd, no ZooKeeper e no Redis, a rota fica gravada num banco de chaves.
  • Manuais: a rota fica num arquivo YAML ou TOML, ou chega por HTTP.

Mais de um provider pode funcionar ao mesmo tempo. Numa VPS com Docker, a combinação usual junta o provider Docker, que publica os apps, ao provider de arquivo, que cobre alguma peça que não mora num container.

Como o provider Docker lê os containers

O provider Docker lê os containers pela API do Docker Engine, em geral pelo socket /var/run/docker.sock montado no container do Traefik. Com a opção watch, ligada por padrão, ele acompanha os eventos do Docker, por isso a rota aparece quando o container sobe e some quando ele para.

Três opções do provider explicam a maior parte do comportamento que você observa nas stacks:

  • exposedByDefault: vem ligada por padrão. Nesse modo, todo container ganha um router, mesmo sem label nenhuma. Com exposedByDefault=false, o Traefik ignora os containers sem a label traefik.enable=true. As stacks dos portais usam o valor false para que nenhum banco de dados ganhe rota por acidente.
  • network: escolhe a rede Docker pela qual o Traefik alcança os containers. Num container ligado a várias redes, sem essa escolha, o Traefik usa qualquer uma delas, ao acaso.
  • defaultRule: define a condição usada quando o container não declara a dele. O padrão monta um Host com o nome do container, que raramente coincide com o domínio que você quer publicar.

Para a porta do app, o Traefik usa a única porta exposta pela imagem ou, quando a imagem expõe várias, a menor delas. Quando a imagem não expõe nenhuma, ou quando a porta escolhida não é a do app, a label loadbalancer.server.port informa a porta certa.

O que cada label declara

Num container, a configuração de roteamento vira labels cujo nome segue o caminho da peça: traefik.http.routers.<nome>.<opção> para o router e traefik.http.services.<nome>.<opção> para o service. No Compose de estudo do n8n, as labels do serviço ficam assim:

compose.yaml, labels do serviço n8n

Publicação e router

traefik.enable=
Autoriza o Traefik a publicar este container. Obrigatória com exposedByDefault desligado.
traefik.http.routers.n8n.rule=
A condição do router, com o domínio do app dentro de Host().
traefik.http.routers.n8n.entrypoints=
A porta de entrada que o router escuta, como websecure.
traefik.http.routers.n8n.tls.certresolver=
O resolvedor que emite e renova o certificado do domínio.

Service e rede

traefik.http.services.n8n.loadbalancer.server.port=
A porta do app dentro do container: 5678 no n8n.
traefik.http.routers.n8n.middlewares=
Opcional: os middlewares aplicados no caminho, em ordem.
traefik.docker.network=
Opcional: a rede pela qual o Traefik alcança este container.
O Traefik lê essas labels quando o container sobe. Outro app web usa o mesmo conjunto com outro nome, outro domínio e outra porta.

Para cada container publicado, o Traefik cria um router e um service. Quando as labels declaram um router e um service sem dizer qual service o router usa, o Traefik liga os dois. Quando o router não tem service declarado, o Traefik cria um service e o liga ao router. Por isso a label service raramente aparece no Compose de um app. Ela entra quando o destino é outro, como o api@internal que serve o dashboard.

As mesmas labels no Docker Swarm

No Swarm, o Traefik usa o provider swarm e lê as labels do serviço, não as de cada container. Num Compose usado com docker stack deploy, essas labels ficam dentro de deploy.labels.

Como o Swarm não informa as portas dos serviços ao Traefik, a label loadbalancer.server.port é obrigatória em todo serviço publicado no Swarm. O provider Swarm também não acompanha eventos, por isso consulta o Swarm a cada intervalo, de 15 segundos por padrão. Como no Docker, o exposedByDefault continua ligado por padrão.

O provider de arquivo

O provider de arquivo lê a configuração de roteamento de arquivos YAML ou TOML. Ele cobre as peças que não moram num container, como um app que roda em outro servidor, um middleware compartilhado por vários apps ou uma opção de TLS. Nas labels de um container, uma peça do arquivo aparece com o sufixo @file, como em seguranca@file.

A rede proxy entre o Traefik e os apps

Para repassar a requisição, o Traefik precisa alcançar o container pela rede. Containers de stacks diferentes não se enxergam por padrão, porque cada Compose cria a própria rede. As stacks dos portais contornam essa separação com uma rede criada uma vez na VPS, com o nome proxy, declarada como external no Compose do Traefik e no Compose de cada app.

Só o serviço web de cada app entra na rede proxy, porque o banco de dados precisa ser alcançado apenas pelo próprio app, na rede interna da stack. Para o app que está nas duas redes, a opção providers.docker.network=proxy indica ao Traefik qual delas usar.

Com os serviços descobertos e as rotas montadas, a página seguinte trata do que acontece entre o router e o app: os middlewares.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.