Ir para o conteúdo
Promovaweb

Certificados HTTPS no Traefik

O Traefik obtém o certificado HTTPS de cada domínio pelo protocolo ACME, com um resolvedor de certificados que conversa com o Let's Encrypt. O resolvedor prova ao Let's Encrypt que o domínio responde pelo Traefik, guarda o certificado no arquivo acme.json e renova cada certificado 30 dias antes do vencimento.

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. O Let’s Encrypt e o resolvedor ACME
  2. Três formas de provar o domínio
  3. O ciclo de vida de um certificado
  4. O que o acme.json guarda
  5. O aviso de conexão insegura

O Let’s Encrypt e o resolvedor ACME

O Let’s Encrypt é uma autoridade certificadora gratuita que emite certificados pelo protocolo ACME. Nesse protocolo, um programa cliente solicita o certificado, prova que controla o domínio e recebe o certificado assinado. No Traefik, esse cliente é o resolvedor de certificados, configurado em certificatesResolvers.

Com um nome escolhido por você, como letsencrypt, o resolvedor faz parte da configuração de instalação, ao lado dos entrypoints e dos providers. As opções principais ocupam poucas linhas: o e-mail cadastrado no Let’s Encrypt, o arquivo onde os certificados ficam guardados e o desafio usado para provar o domínio. O servidor padrão é o de produção do Let’s Encrypt, https://acme-v02.api.letsencrypt.org/directory. A opção caServer aceita outro endereço, como o do ambiente de testes do Let’s Encrypt.

A emissão parte de um router: a label traefik.http.routers.<nome>.tls.certresolver=letsencrypt indica que aquele router atende HTTPS com certificado desse resolvedor. O domínio do certificado vem da função Host na condição do router, por isso um app novo com essa label ganha certificado sem nenhuma mudança na stack do Traefik.

Três formas de provar o domínio

Antes de assinar, o Let’s Encrypt exige uma prova de que você controla o domínio, chamada desafio. O Traefik oferece os três tipos do protocolo, cada um com uma exigência diferente de rede ou de DNS:

DesafioOpção no TraefikO que exige
TLS-ALPN-01tlsChallengeO Let's Encrypt alcança o Traefik pela porta 443.
HTTP-01httpChallenge.entrypointO entrypoint indicado é alcançado pela porta 80.
DNS-01dnsChallenge.providerO Traefik cria um registro no DNS do domínio, pela API do seu provedor de DNS.

O desafio TLS é o caminho mais simples numa VPS que já atende HTTPS. Ele usa a própria porta 443 e dispensa configuração no DNS além do registro A. O desafio HTTP usa a porta 80, cujo entrypoint precisa continuar respondendo mesmo com o redirecionamento para HTTPS ligado.

O desafio DNS é o único que emite certificado curinga, como *.seudominio.com.br. Como a prova acontece no DNS, ele também dispensa as portas 80 e 443 abertas para o Let’s Encrypt. Em troca, o Traefik precisa de uma credencial da API do seu provedor de DNS. Para esse desafio, o Traefik usa a biblioteca Lego, cuja documentação traz a lista de provedores aceitos, com as variáveis de ambiente de cada um.

O ciclo de vida de um certificado

O ciclo de um certificado começa quando o Traefik encontra um router com resolvedor e termina só quando o domínio sai da configuração:

  1. Router com resolvedor

    tls.certresolver=letsencrypt

    O Traefik encontra um domínio sem certificado válido.

  2. Desafio

    tlsChallenge

    O Let's Encrypt confere se o domínio responde pelo Traefik.

  3. Emissão

    90 dias

    O Let's Encrypt assina o certificado do domínio.

  4. Armazenamento

    acme.json

    O Traefik grava o cadastro ACME e os certificados no arquivo.

  5. Renovação

    30 dias antes

    O Traefik solicita um certificado novo antes do vencimento.

A renovação repete o desafio e a emissão sem tirar o certificado atual do ar, por isso o visitante não percebe a troca.

Por padrão, o Traefik trabalha com certificados de 90 dias e começa a renovar cada um 30 dias antes do vencimento. A opção certificatesDuration, de 2160 horas por padrão, serve só para calcular essas datas e não altera a validade concedida pelo Let’s Encrypt.

O que o acme.json guarda

A opção storage é obrigatória e aponta o arquivo, acme.json por padrão, onde o resolvedor guarda o cadastro ACME e os certificados emitidos, com as chaves privadas. Esse arquivo evita uma nova solicitação de certificado a cada reinício do Traefik.

Num container, o acme.json precisa morar num volume, porque a recriação de um container sem volume apaga o arquivo. O Traefik então solicita todos os certificados de novo, um por domínio, ao mesmo tempo, o que pode esbarrar nos limites de emissão que o Let’s Encrypt aplica por domínio e por cadastro ACME.

O aviso de conexão insegura

Enquanto o certificado verdadeiro não sai, o Traefik serve um certificado autoassinado, gerado por ele, que o navegador recusa com o aviso de conexão insegura. As causas mais comuns ficam fora do Traefik: o registro A do domínio aponta para outro IP, a porta 443 ou a 80 está fechada no firewall do provedor, ou a mudança no DNS ainda não propagou.

O motivo da falha aparece nos logs do Traefik, junto do nome do resolvedor, como mostra a página Dashboard, logs e métricas. Durante o teste de uma configuração nova, o ambiente de testes do Let’s Encrypt, apontado pelo caServer, preserva os limites de emissão do ambiente de produção.

A página seguinte mostra como acompanhar o trabalho do Traefik pelo dashboard, pelos logs e pelas métricas.

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.