traefikctl

Traefik Control — una herramienta CLI para gestionar las configuraciones del proxy Traefik.

Características

Instalación del binario: descarga e instala Traefik desde las releases de GitHub
Gestión de configuraciones: genera, visualiza y extiende configuraciones estáticas y dinámicas
Servicio Systemd: instalar, iniciar, detener, reiniciar, recargar y seguir los logs
Gestión de rutas: agregar, listar, validar, copiar, activar y desactivar rutas HTTP y TCP
Gestión de backends: agregar o quitar servidores upstream para load balancing
Gestión de middlewares: agregar, listar y quitar middlewares (redirect-https, rate-limit, basic-auth, strip-prefix)
HTTPS / Let’s Encrypt: configuración de TLS y ACME con un único comando
Dashboard de estado: estado del servicio, versión de Traefik y conteo de rutas en una sola pantalla
Self-update: descarga e instala la última release de traefikctl
Exportar HAProxy: convierte bloques frontend/backend/listen de HAProxy en archivos YAML dinámicos de Traefik

Instalación

Compilar desde el código

make build
sudo make install

Script de instalación rápida

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

Instalar el binario de Traefik

sudo traefikctl install
sudo traefikctl install --version v3.3.5   # versión específica
traefikctl install --check                 # verifica la versión instalada

Inicio Rápido

# 1. Instalar Traefik
sudo traefikctl install

# 2. Generar configuraciones iniciales
sudo traefikctl config --generate

# 3. Instalar e iniciar el servicio systemd
sudo traefikctl service install
sudo systemctl start traefikctl

# 4. Agregar tu primera ruta
sudo traefikctl resource add --name my-app --domain app.example.com --address 10.0.0.2:8080

# 5. Verificar el estado
traefikctl status

Comandos

version

traefikctl version
traefikctl --version

status

Muestra el estado del servicio, la versión de Traefik y un resumen de todas las rutas configuradas.

traefikctl status

logs

Sigue los logs de Traefik vía journalctl o archivo de log.

traefikctl logs                  # modo follow (por defecto)
traefikctl logs --follow=false   # imprime las últimas líneas y sale
traefikctl logs -n 100           # muestra las últimas 100 líneas

update

Auto-actualiza traefikctl a la última release de GitHub.

sudo traefikctl update                    # última release
sudo traefikctl update --version v0.1.0  # versión específica

config

# Genera los archivos de configuración estática y dinámica
sudo traefikctl config --generate

# Sobrescribe configuraciones existentes
sudo traefikctl config --generate --force

# Muestra todas las configuraciones (con comentarios)
traefikctl config --view

# Muestra solo la configuración activa (sin comentarios)
traefikctl config --view --clean

# Agrega configuración ACME de Let's Encrypt
sudo traefikctl config --acme --acme-email [email protected]

service

sudo traefikctl service install     # instala la unit de systemd
sudo traefikctl service uninstall   # quita la unit de systemd
traefikctl service status           # verifica el estado del servicio
traefikctl service logs             # sigue los logs del servicio
sudo traefikctl service restart     # restart completo
sudo traefikctl service reload      # hot reload (sin downtime)

resource add

Agrega una ruta HTTP o TCP a la configuración dinámica.

# Ruta HTTP básica
sudo traefikctl resource add --name my-app --domain app.example.com --address 10.0.0.2:8080

# HTTPS con 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

# Adjunta un 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

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

Flag	Por defecto	Descripción
`--name`	requerido	Nombre del router y service
`--address`	requerido	Dirección del backend (`ip:puerto`)
`--domain`	—	Regla de host (`Host(\`…`)`)
`--entrypoint`	`web`	Entrypoint de Traefik
`--type`	`http`	`http` o `tcp`
`--middleware`	—	Adjunta middleware(s) por nombre (puede repetirse)
`--redirect-https`	false	Redirección automática HTTP→HTTPS
`--tls`	false	Habilita TLS en el router
`--cert-resolver`	—	Nombre del resolver de Let’s Encrypt

resource list

Lista todas las rutas HTTP y TCP configuradas en todos los archivos de configuración dinámica.

traefikctl resource list

resource check

Prueba la conectividad de los backends de todas las rutas.

traefikctl resource check
traefikctl resource check --timeout 5s

resource enable / disable

Activa o desactiva una ruta sin borrarla.

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

Las configuraciones desactivadas quedan en /etc/traefikctl/disabled/.

resource copy

Clona una ruta existente con un nombre y/o dominio nuevo.

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

resource backend add / remove

Agrega o quita servidores upstream del pool de load balancing de un 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

# Redirección 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

Convierte una configuración existente de HAProxy en archivos YAML dinámicos de Traefik. Cada bloque frontend y listen produce un archivo, listo para colocar en /etc/traefik/dynamic/.

# Desde un archivo — escribe directamente en /etc/traefik/dynamic (por defecto)
sudo traefikctl haproxy export --file /etc/haproxy/haproxy.cfg

# Directorio de salida personalizado
traefikctl haproxy export --file /etc/haproxy/haproxy.cfg --output-dir /tmp/traefik-preview

# Desde una configuración en base64 (útil en pipelines)
B64=$(base64 -w0 /etc/haproxy/haproxy.cfg)
sudo traefikctl haproxy export --base64 "$B64"

Flag	Por defecto	Descripción
`--file`	—	Path al archivo de configuración de HAProxy
`--base64`	—	Configuración de HAProxy en base64 (alternativa a `--file`)
`--output-dir`	`/etc/traefik/dynamic`	Directorio donde se escriben los archivos YAML generados

Reglas de conversión:

frontend (modo HTTP) → routers y services HTTP de Traefik
- ACL hdr(host) -i domain → regla Host(\domain`)` (prioridad 10)
- default_backend → regla catch-all PathPrefix(\/`)` (prioridad 1)
listen (modo TCP) → router y service TCP de Traefik con HostSNI(\*`)`
- El puerto 443 obtiene TLS passthrough; el resto de los puertos TCP no
listen (modo HTTP) → mismo comportamiento que frontend
Puerto duplicado entre bloques → se imprime un aviso, el segundo bloque se omite
Entrypoints: puerto 80 → web, puerto 443 → websecure, otros → nombre del frontend

Archivos de Configuración

Configuración estática (`/etc/traefik/traefik.yaml`)

Controla entrypoints, TLS, providers y logging. Generada por traefikctl config --generate.

Configuración dinámica (`/etc/traefik/dynamic/*.yaml`)

Define routers, services y middlewares. Traefik observa este directorio y aplica los cambios automáticamente — no requiere reinicio.

Estructura de Directorios

/etc/traefik/
├── traefik.yaml           # Configuración estática
├── acme.json              # Certificados Let's Encrypt
└── dynamic/               # Configuraciones con hot-reload
    └── *.yaml

/etc/traefikctl/
└── disabled/              # Snapshots de rutas desactivadas

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

/usr/local/bin/
├── traefik                # Binario de Traefik
└── traefikctl             # Esta CLI