traefikctl

Traefik Control — uma ferramenta CLI para gerenciar configurações do proxy Traefik.

Recursos

Instalação do binário: baixa e instala o Traefik a partir das releases do GitHub
Gerenciamento de configurações: gera, visualiza e estende configurações estáticas e dinâmicas
Serviço Systemd: instalar, iniciar, parar, reiniciar, recarregar e seguir os logs
Gerenciamento de rotas: adicionar, listar, validar, copiar, ativar e desativar rotas HTTP e TCP
Gerenciamento de backends: adicionar ou remover servidores upstream para load balancing
Gerenciamento de middlewares: adicionar, listar e remover middlewares (redirect-https, rate-limit, basic-auth, strip-prefix)
HTTPS / Let’s Encrypt: configuração de TLS e ACME com um único comando
Dashboard de status: estado do serviço, versão do Traefik e contagem de rotas em uma só tela
Self-update: baixa e instala a última release do traefikctl
Exportar HAProxy: converte blocos frontend/backend/listen do HAProxy em arquivos YAML dinâmicos do Traefik

Instalação

Compilar a partir do código

make build
sudo make install

Script de instalação rápida

curl -fsSL https://eliasmeireles.com.br/tools/traefikctl/install.sh | bash

Instalar o binário do Traefik

sudo traefikctl install
sudo traefikctl install --version v3.3.5   # versão específica
traefikctl install --check                 # verifica a versão instalada

Início Rápido

# 1. Instalar o Traefik
sudo traefikctl install

# 2. Gerar configurações iniciais
sudo traefikctl config --generate

# 3. Instalar e iniciar o serviço systemd
sudo traefikctl service install
sudo systemctl start traefikctl

# 4. Adicionar sua primeira rota
sudo traefikctl resource add --name my-app --domain app.example.com --address 10.0.0.2:8080

# 5. Verificar o status
traefikctl status

Comandos

version

traefikctl version
traefikctl --version

status

Mostra o estado do serviço, a versão do Traefik e um resumo de todas as rotas configuradas.

traefikctl status

logs

Acompanha os logs do Traefik via journalctl ou arquivo de log.

traefikctl logs                  # modo follow (padrão)
traefikctl logs --follow=false   # imprime as últimas linhas e sai
traefikctl logs -n 100           # mostra as últimas 100 linhas

update

Atualiza o traefikctl para a última release do GitHub.

sudo traefikctl update                    # última release
sudo traefikctl update --version v0.1.0  # versão específica

config

# Gera os arquivos de configuração estático e dinâmico
sudo traefikctl config --generate

# Sobrescreve configurações existentes
sudo traefikctl config --generate --force

# Mostra todas as configurações (com comentários)
traefikctl config --view

# Mostra apenas a configuração ativa (sem comentários)
traefikctl config --view --clean

# Adiciona configuração ACME do Let's Encrypt
sudo traefikctl config --acme --acme-email [email protected]

service

sudo traefikctl service install     # instala o systemd unit
sudo traefikctl service uninstall   # remove o systemd unit
traefikctl service status           # verifica o estado do serviço
traefikctl service logs             # acompanha os logs do serviço
sudo traefikctl service restart     # restart completo
sudo traefikctl service reload      # hot reload (sem downtime)

resource add

Adiciona uma rota HTTP ou TCP à configuração dinâmica.

# Rota HTTP simples
sudo traefikctl resource add --name my-app --domain app.example.com --address 10.0.0.2:8080

# HTTPS com Let's Encrypt
sudo traefikctl resource add --name my-app --domain app.example.com --address 10.0.0.2:8080 \
  --redirect-https --tls --cert-resolver letsencrypt

# Anexa um middleware existente
sudo traefikctl resource add --name my-api --domain api.example.com --address 10.0.0.3:3000 \
  --entrypoint websecure --middleware my-rate-limit

# Rota TCP
sudo traefikctl resource add --name postgres --address 10.0.0.10:5432 --type tcp --entrypoint postgres

Flag	Padrão	Descrição
`--name`	obrigatório	Nome do router e do service
`--address`	obrigatório	Endereço do backend (`ip:porta`)
`--domain`	—	Regra de host (`Host(\`…`)`)
`--entrypoint`	`web`	Entrypoint do Traefik
`--type`	`http`	`http` ou `tcp`
`--middleware`	—	Anexa middleware(s) por nome (pode ser repetido)
`--redirect-https`	false	Redirecionamento automático HTTP→HTTPS
`--tls`	false	Habilita TLS no router
`--cert-resolver`	—	Nome do resolver Let’s Encrypt

resource list

Lista todas as rotas HTTP e TCP configuradas em todos os arquivos de configuração dinâmica.

traefikctl resource list

resource check

Testa a conectividade dos backends de todas as rotas.

traefikctl resource check
traefikctl resource check --timeout 5s

resource enable / disable

Ativa ou desativa uma rota sem apagá-la.

sudo traefikctl resource disable --name my-app
sudo traefikctl resource enable  --name my-app

Configurações desativadas ficam em /etc/traefikctl/disabled/.

resource copy

Clona uma rota existente para um novo nome e/ou domínio.

sudo traefikctl resource copy --from my-app --name my-app-staging --domain staging.example.com

resource backend add / remove

Adiciona ou remove servidores upstream do pool de load balancing de um service.

sudo traefikctl resource backend add    --name my-app --address 10.0.0.3:8080
sudo traefikctl resource backend remove --name my-app --address 10.0.0.3:8080

middleware add

# Redirecionamento HTTP → HTTPS
sudo traefikctl middleware add --name redirect-to-https --type redirect-https

# Rate limit (10 req/s, burst 20)
sudo traefikctl middleware add --name api-limit --type rate-limit \
  --opt average=10 --opt burst=20

# Basic auth
sudo traefikctl middleware add --name admin-auth --type basic-auth \
  --opt users=admin:$$apr1$$...

# Strip prefix
sudo traefikctl middleware add --name strip-api --type strip-prefix \
  --opt prefix=/api

middleware list

traefikctl middleware list

middleware remove

sudo traefikctl middleware remove --name api-limit

haproxy export

Converte uma configuração existente do HAProxy em arquivos YAML dinâmicos do Traefik. Cada bloco frontend e listen gera um arquivo, pronto para colocar em /etc/traefik/dynamic/.

# A partir de um arquivo — escreve direto em /etc/traefik/dynamic (padrão)
sudo traefikctl haproxy export --file /etc/haproxy/haproxy.cfg

# Diretório de saída customizado
traefikctl haproxy export --file /etc/haproxy/haproxy.cfg --output-dir /tmp/traefik-preview

# A partir de uma configuração em base64 (útil em pipelines)
B64=$(base64 -w0 /etc/haproxy/haproxy.cfg)
sudo traefikctl haproxy export --base64 "$B64"

Flag	Padrão	Descrição
`--file`	—	Caminho para o arquivo de configuração do HAProxy
`--base64`	—	Configuração do HAProxy em base64 (alternativa a `--file`)
`--output-dir`	`/etc/traefik/dynamic`	Diretório onde os arquivos YAML gerados serão escritos

Regras de conversão:

frontend (modo HTTP) → routers e services HTTP do Traefik
- ACL hdr(host) -i domain → regra Host(\domain`)` (prioridade 10)
- default_backend → regra catch-all PathPrefix(\/`)` (prioridade 1)
listen (modo TCP) → router e service TCP do Traefik com HostSNI(\*`)`
- A porta 443 ativa TLS passthrough; demais portas TCP não
listen (modo HTTP) → mesmo comportamento de frontend
Porta duplicada entre blocos → emite aviso e o segundo bloco é ignorado
Entrypoints: porta 80 → web, porta 443 → websecure, demais → nome do frontend

Arquivos de Configuração

Configuração estática (`/etc/traefik/traefik.yaml`)

Controla entrypoints, TLS, providers e logging. Gerada por traefikctl config --generate.

Configuração dinâmica (`/etc/traefik/dynamic/*.yaml`)

Define routers, services e middlewares. O Traefik observa esse diretório e aplica mudanças automaticamente — não é preciso reiniciar.

Estrutura de Diretórios

/etc/traefik/
├── traefik.yaml           # Configuração estática
├── acme.json              # Certificados Let's Encrypt
└── dynamic/               # Configurações com hot-reload
    └── *.yaml

/etc/traefikctl/
└── disabled/              # Snapshots de rotas desativadas

/var/log/traefik/
├── traefik.log
└── access.log

/usr/local/bin/
├── traefik                # Binário do Traefik
└── traefikctl             # Esta CLI