migrar traefik v2 para v3 o que muda

O que muda entre o Traefik v2 e v3

A migração do Traefik v2 para o v3 consiste principalmente em renomeações. A mudança mais conhecida é o middleware ipWhiteList, que passou a se chamar ipAllowList. Além disso, a v3 torna a sintaxe das regras de roteamento mais rigorosa (PathPrefix perde recursos de regex, vários matchers foram renomeados ou removidos), remove alguns providers e opções, e mantém o restante funcional: entrypoints, configuração de certificados ACME, workflow de labels do Docker e seu acme.json continuam operacionais. A v3 também inclui um modo de compatibilidade que mantém a sintaxe de regras da v2, permitindo atualizar o binário primeiro e reescrever as regras de um serviço por vez, em vez de fazer tudo em uma única noite de risco.

Este guia assume o setup de Docker Compose baseado em labels do guia do reverse proxy Traefik. Aquela página é nativa da v3; esta é para sistemas que ainda utilizam uma tag traefik:v2.

Renomeações e remoções

• ipWhiteList agora é ipAllowList, tanto para o middleware HTTP quanto para o TCP. As opções internas permanecem as mesmas, portanto sourcerange mantém seu significado exato. As versões atuais da v3, incluindo a v3.5, ainda aceitam o nome antigo como um alias depreciado e continuam aplicando a lista; portanto, esta renomeação não causará falhas imediatas. Renomeie de qualquer forma: o alias tem previsão de remoção e desaparecerá da lista de depreciação silenciosamente.
• providers.docker.swarmMode=true foi removido. O Swarm possui seu próprio provider, configurado como providers.swarm.endpoint.
• A seção pilot foi totalmente removida.
• experimental.http3 foi removido. O HTTP/3 é habilitado diretamente no entrypoint.
• tls.caOptional foi removido dos providers e do middleware forwardAuth.
• O provider de métricas InfluxDB v1, o provider Rancher e o provider Marathon foram removidos.
• O Tracing foi movido para o OpenTelemetry. Os backends de tracing dedicados, incluindo as integrações Jaeger e Zipkin, foram removidos; a v3 exporta OTLP (o protocolo OpenTelemetry) em seu lugar.
• As opções depreciadas ssl* dentro do middleware headers (sslRedirect, sslHost e demais) foram removidas. Redirecionamentos de entrypoint e o middleware redirectScheme os substituíram.

Estas remoções são mais críticas do que parecem, pois o Traefik recusa-se a iniciar se a configuração estática contiver uma opção desconhecida. Uma linha pilot ou swarmMode remanescente impede o boot do container com uma mensagem de erro incompatible deprecated static option found que identifica o item; uma opção que o Traefik nunca conheceu (um erro de digitação ou tls.caOptional) interrompe o processo com field not found. Limpe a configuração estática antes de alterar a tag da imagem.

Um nome de middleware que o Traefik realmente não conhece (um erro de digitação ou um nome que foi removido em vez de receber um alias) falha de forma diferente: o router que o referencia carrega com um erro em vez de uma rota, o dashboard o sinaliza e a API reporta middleware "offce@docker" does not exist. Requisições para esse hostname retornam 404 porque o router não foi iniciado. Note que ipwhitelist NÃO pertence a esta categoria na v3 atual: ele permanece como um alias depreciado, então um label não renomeado continuará funcionando silenciosamente.

A sintaxe das regras mudou

As regras são onde a reescrita real acontece. As mudanças na v3:

• Crases são obrigatórias para valores dentro de matchers. A v2 também aceitava aspas duplas; a v3 não aceita, portanto Host("app.example.com") deve se tornar Host(app.example.com).
• PathPrefix não entende mais expressões regulares ou placeholders no estilo {id}. Uma regra da v2 como PathPrefix(/api/{version:v[0-9]+}) deve se tornar um matcher PathRegexp escrito em sintaxe de expressão regular Go.
• Matchers agora aceitam um único valor. A v2 permitia Host(app.example.com,www.example.com); a v3 exige Host(app.example.com) || Host(www.example.com). As exceções são Header, HeaderRegexp, Query, e QueryRegexp, que ainda aceitam um nome mais um valor.
• Headers e HeadersRegexp foram renomeados para Header e HeaderRegexp.
• HostHeader foi removido. Use Host, que faz o mesmo correspondimento na v3.
• Dois matchers são novos: QueryRegexp, e ClientIP para correspondência do endereço do cliente dentro de uma regra.

A boa notícia: uma regra simples Host(app.example.com) escrita com crases já é uma sintaxe v3 válida. A maioria das configurações pequenas de Compose usa exatamente isso, o que significa que a maioria dos labels migra sem edições de regras.

Audite seus labels antes de começar

Você pode medir o tamanho da sua migração com apenas uma busca, pois cada alteração de label que quebra a compatibilidade deixa um padrão que o grep pode encontrar:

grep -rnE 'ipwhitelist|HostHeader|Headers\(|PathPrefix\(`[^`]*\{|Host\(`[^`]*`,' docker-compose*.yml

Cada ocorrência é uma linha para editar. ipwhitelist torna-se ipallowlist. HostHeader torna-se Host. Headers torna-se Header. Um placeholder {...} dentro de PathPrefix torna-se um matcher PathRegexp. Uma vírgula dentro de Host() torna-se dois matchers Host() unidos por ||. Zero ocorrências significam que seus labels já utilizam a sintaxe v3 válida, e a migração se resume à configuração estática mais a tag da imagem.

O que permanece igual

Os entrypoints e o redirecionamento de HTTP para HTTPS, os ACME resolvers com ambos os tipos de challenge, exposedByDefault, os router e service labels, loadbalancer.server.port, e o dashboard funcionam na v3 da mesma forma que na v2. Seus certificados também são mantidos, pois a v3 continua lendo o acme.json que a v2 escreveu. Faça um backup do arquivo antes de começar, pois um rollback que perca esse arquivo causará o erro de limite de taxa de certificados duplicados do Let's Encrypt:

cp ./letsencrypt/acme.json ./letsencrypt/acme.json.v2-backup

O caminho de migração

Passo 1: fixe a versão atual. Altere qualquer tag traefik:latest ou traefik:v2 para a versão exata que você está usando, por exemplo traefik:v2.11, e faça o commit de todo o diretório do compose no git. Todos os passos seguintes tornam-se reversíveis com um checkout. Se recriar um único serviço com docker compose up -d <service> ainda não for algo natural para você, o guia básico de Docker Compose cobre as operações necessárias para esta migração.

Passo 2: limpe a configuração estática e ative o modo de compatibilidade. Remova todas as opções removidas na v3 (pilot, swarmMode, tls.caOptional, experimental.http3) e configure a v3 para tratar regras como sintaxe v2 por padrão. Em traefik.yml:

core:
  defaultRuleSyntax: v2

Ou como uma flag na lista command: do compose: --core.defaultRuleSyntax=v2. O modo de compatibilidade cobre apenas a sintaxe das regras. Ele não restaura opções removidas e não renomeia middlewares para você.

Passo 3: prepare a renomeação dos middlewares. Busque nos seus arquivos compose pelos nomes antigos: grep -rn ipwhitelist docker-compose*.yml. Edite cada label ipwhitelist para ipallowlist, mas não aplique a mudança ainda, pois o novo nome não existe na v2. Essas edições devem ser aplicadas juntas no próximo passo. (Se algum erro passar, a v3 atual ainda aceita o nome antigo como um alias depreciado, então a lista continuará funcionando; corrija na próxima etapa em vez de fazer às 2 da manhã.)

Passo 4: altere a tag da imagem. Defina a imagem do Traefik para a versão v3 atual, traefik:v3.5 no momento desta escrita, então:

docker compose up -d
docker compose logs -f traefik

Como o modo de compatibilidade está ativo, suas regras v2 continuarão funcionando, e como o up -d também recriou os serviços cujos labels de middleware você renomeou, esses routers subirão corretamente. Um log saudável não possui linhas com field not found nem com does not exist.

Seja realista sobre o tempo de indisponibilidade que este passo gera. Um router que referencia um nome de middleware que a v3 realmente não conhece (um erro de digitação ou uma opção removida) ficará offline desde o início do novo Traefik até que o container da aplicação seja recriado, o que em uma máquina leva apenas os segundos que o docker compose up -d precisa para processar a lista. Se uma rota não puder ficar offline de forma alguma, remova o middleware renomeado do label middlewares desse router antes da mudança e adicione-o novamente depois; decida com antecedência se essa rota pode operar sem sua lista de IPs permitidos durante esse intervalo.

Passo 5: migre as regras serviço por serviço. Trabalhe em um app por vez: reescreva sua regra para a sintaxe v3, recrie apenas esse serviço com docker compose up -d app e teste antes de prosseguir. Se um serviço tiver uma regra que você ainda não consegue reescrever, adicione o label de escape traefik.http.routers.app.ruleSyntax=v2 a esse router específico e continue o processo.

Passo 6: desative o modo de compatibilidade. Quando todas as regras estiverem na sintaxe v3, delete o defaultRuleSyntax e quaisquer labels ruleSyntax, reinicie o Traefik e confirme se todos os routers ainda aparecem em verde no dashboard. Não permaneça com o modo de compatibilidade ativo: o Traefik depreciou ambas as opções na v3.4 e as removerá na próxima versão major; elas são uma ponte, não um destino.

Antes e depois: labels de um serviço

Aqui está um app com todas as mudanças famosas de uma vez: um Host de múltiplos valores, um placeholder PathPrefix e um middleware ipWhiteList. O bloco v2:

  app:
    image: app:1.4
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=Host(`app.example.com`,`www.example.com`) && PathPrefix(`/api/{version:v[0-9]+}`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=le
      - traefik.http.routers.app.middlewares=office
      - traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24
      - traefik.http.services.app.loadbalancer.server.port=8080

E o mesmo serviço migrado para v3:

  app:
    image: app:1.4
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=(Host(`app.example.com`) || Host(`www.example.com`)) && PathRegexp(`^/api/v[0-9]+`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=le
      - traefik.http.routers.app.middlewares=office
      - traefik.http.middlewares.office.ipallowlist.sourcerange=10.0.0.0/24
      - traefik.http.services.app.loadbalancer.server.port=8080

Duas labels mudaram. A regra dividiu seu Host de múltiplos valores em dois matchers unidos por || e substituiu o placeholder por PathRegexp, e a label do middleware trocou ipwhitelist por ipallowlist. O entrypoint, o certificate resolver, a conexão router-to-middleware e a porta do serviço não mudaram.

Teste cada serviço com o dashboard

Após cada alteração, abra a página de HTTP routers do dashboard. Todos os routers devem estar verdes. Um router com um selo de erro indica o problema exato; geralmente é um middleware que não existe com o novo nome ou uma regra que o v3 não consegue processar. Em seguida, confirme externamente, um hostname por vez:

curl -sI https://app.example.com/api/v1/status

Um 200 ou o redirecionamento normal do seu app significa que o roteamento e o TLS funcionaram. Um 404 do Traefik significa que o router não iniciou; volte ao dashboard e leia o erro. Mantenha o docker compose logs -f traefik aberto em um segundo terminal enquanto trabalha, pois qualquer falha de parsing aparecerá lá no momento em que um container reiniciar.

Integridade do Rollback

Mantenha o arquivo compose v2, sua configuração estática e o backup acme.json até que todos os serviços estejam roteando na v3 e tenham sido testados em produção. O rollback consiste em realizar o checkout do commit anterior à migração e executar o docker compose up -d. É necessário usar o arquivo completo, não apenas a tag da imagem, pois labels exclusivas da v3 são incompatíveis com a v2, da mesma forma que as labels da v2 falham na v3: o ipallowlist não existe na v2, e um matcher PathRegexp também não será processado. Se o acme.json for perdido ou corrompido durante o processo, restaure a cópia de backup antes de iniciar a v2, para evitar que o rollback esgote o limite de taxa do Let's Encrypt ao reemitir cinco certificados simultaneamente.

FAQ

Eu preciso reescrever todas as regras de router para o Traefik v3?

Não. Uma regra Host(app.example.com) simples escrita com backticks é válida em ambas as versões, o que cobre a maioria das configurações de Compose. A reescrita só é necessária onde uma regra utilizava recursos exclusivos da v2: regex ou placeholders dentro de Path e PathPrefix, vários hostnames dentro de um único Host(), aspas em vez de backticks, ou os matchers Headers, HeadersRegexp e HostHeader que foram removidos.

O que aconteceu com o ipWhiteList no Traefik v3?

Foi renomeado para ipAllowList, com a configuração interna permanecendo a mesma; assim, uma label da v2 como traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 torna-se a mesma linha contendo ipallowlist. As versões atuais da v3, incluindo a v3.5, ainda aceitam o nome antigo como um alias depreciado, portanto, uma label não renomeada continua aplicando a allowlist silenciosamente. Considere isso apenas um prazo temporário e não um motivo para não renomear: o alias tem previsão de remoção e, quando um middleware com nome desconhecido pelo Traefik é usado, o erro ocorre de forma explícita com um erro de router e um 404. O dashboard exibirá o erro e as requisições para aquele hostname retornarão 404.

O Traefik v3 ainda consegue ler a sintaxe de regras da v2?

Sim. Defina core.defaultRuleSyntax: v2 na configuração estática para manter a sintaxe da v2 como padrão durante a migração, e use a label ruleSyntax=v2 por router para casos individuais após retornar o padrão. Considere ambos como temporários: o Traefik os depreciou na v3.4 e os removerá na próxima versão major.

Meus certificados Let's Encrypt sobreviverão ao upgrade?

Sim. O Traefik v3 continua lendo o arquivo acme.json que a v2 escreveu, portanto, os certificados não são reemitidos apenas porque o binário mudou. De qualquer forma, copie o arquivo para um local seguro antes de começar, pois um rollback ou um volume deletado que cause a perda de acme.json forçará a reemissão de todos os certificados de uma vez, e o Let's Encrypt permite apenas cinco certificados duplicados por semana para o mesmo conjunto de hostnames.

Por que o Traefik v3 falha ao iniciar após o upgrade?

Quase sempre porque a configuração estática ainda contém uma opção removida na v3, e o Traefik recusa a inicialização se encontrar opções que não reconhece. Para os resíduos conhecidos (pilot, providers.docker.swarmMode, experimental.http3), o log exibe incompatible deprecated static option found e nomeia o culpado; para qualquer item que a v3 nunca tenha conhecido, como tls.caOptional, ele exibe field not found junto ao nó. Delete ou substitua cada um e reinicie o container.