kestractl

kestractl es una interfaz de línea de comandos basada en Go para gestionar flujos de trabajo de Kestra y recursos relacionados. Está dirigida a Kestra 2.x (con versiones v1 que cubren el conjunto completo de funciones de Kestra 1.x) y se prueba contra Kestra 2.0, 1.3, 1.2, 1.1 y 1.0 a través de una matriz e2e; la fuente de verdad para la compatibilidad es COMPATIBLE_KESTRA_VERSION.properties. La instalación se ofrece mediante un script de conveniencia (curl | bash) que resuelve la última versión a través de la API REST de GitHub, descargas directas de binarios desde GitHub Releases, imágenes de contenedor multi-arquitectura publicadas en Docker Hub y GHCR (variantes Alpine y distroless), o compilando desde el código fuente con Go 1.25+. El script de instalación acepta anulaciones de VERSION e INSTALL_DIR, y puede autenticar llamadas a la API de GitHub con GITHUB_TOKEN para evitar límites de tasa anónimos. La configuración admite múltiples contextos con nombre (dev, staging, prod) almacenados en ~/.kestractl/config.yaml, con autenticación por token o básica, cabeceras HTTP opcionales persistidas y un selector de contexto predeterminado. La precedencia de configuración sigue el modelo de 12 factores: banderas de línea de comandos, luego variables de entorno KESTRACTL_*, luego el archivo de configuración, luego valores predeterminados. Las banderas globales cubren --host, --token, --username/--password, --tenant, --header, --output (table o json), --config y --verbose. Los grupos de comandos cubren la amplitud de la API de Kestra. Flujos: list, list-by-namespace, list-deprecated, get, task, deploy (archivo único o directorio, con --namespace, --override, --fail-fast), validate (archivo local, directorio o validate-by-query contra flujos almacenados), validate-task, validate-trigger, search-by-source, bulk-update, generate-graph-from-source, graph, expressions, namespace-dependencies, dependencies, enable/disable, delete, delete-by-query, disable-by-query, enable-by-query, export (namespace, by-ids, by-query), import, namespace-sync, revisions, delete-revisions, concurrency-limits, update-concurrency. Un comando usage-report ayuda a verificar migraciones de 1.x a 2.0, y validate-by-query sale con código no cero en caso de violaciones para que pueda servir como puerta de CI. Ejecuciones: run (con --wait), get, list, watch (sigue en tiempo real y sale con código no cero en caso de fallo), latest, kill, pause, resume, restart, force-run, replay, replay-with-inputs, unqueue, set-labels, set-labels-bulk, unqueue-bulk, change-status-by-ids, kill-by-query, pause-by-query, resume-by-query, restart-by-query, replay-by-query, force-run-by-query, delete-by-query, unqueue-by-query, set-labels-by-query, update-status-by-query, trigger-webhook (GET/POST/PUT con sufijo de ruta opcional), flow-graph, flow-info, flow-info-by-id, download-file, file-metadata, eval-expression, change-status, update-taskrun, delete. Los filtros de consulta usan la forma CAMPO:OPERACIÓN:VALOR (por ejemplo, STATE:EQUALS:RUNNING). Disparadores: list, search-for-flow, enable, disable, unlock, restart, update, delete, más variantes masivas por IDs (namespace/flowId/triggerId) y por consulta, y gestión de backfill (create-backfill con --start/--end, backfill-pause, backfill-unpause, backfill-delete, y sus variantes por IDs y por consulta). Los disparadores también se pueden exportar como CSV. Espacios de nombres: list, list con --query, autocomplete, get, create, update, delete, más configuración de variables de espacio de nombres mediante --variable repetible o --variables-file, y visualización de inherited-secrets e inherited-variables. Almacén clave-valor: list, set, update, get, delete, con tipos admitidos STRING, NUMBER, BOOLEAN, DATETIME, DATE, DURATION, JSON y --ttl opcional ISO 8601. Archivos de espacio de nombres: list (con --path y --recursive), get (con --revision), upload (archivo único o directorio, con --override, --fail-fast, --allow-missing-namespace), delete (con --recursive y --force). Complementos: descargar todos los JAR de complementos para una versión dada de Kestra en un directorio de destino, con --concurrency para descargas paralelas, y --from-config para iniciar un trabajador independiente o remoto extrayendo solo los complementos principales requeridos por un application.yaml de Kestra (almacenamiento interno, gestor de secretos, backend de cola/repositorio). Un comando list previsualiza los complementos principales requeridos sin descargarlos. Trabajadores: registration-tokens generate se ejecuta sin conexión para producir un token de registro de trabajador sin una instancia de Kestra. Paneles (Enterprise Edition): list, get, create desde YAML, update y comandos de gestión relacionados. Grupos adicionales cubren aplicaciones, planos, suites de prueba e IAM (usuarios, grupos, roles, cuentas de servicio, vinculaciones, invitaciones). Detalles operativos: kestractl envía telemetría anónima que nunca bloquea la ejecución de comandos y se puede deshabilitar con KESTRACTL_TELEMETRY_DISABLED=true. Las notificaciones de actualización se almacenan en caché durante 24 horas en ~/.kestractl/check_for_new_available_version.json, se ejecutan de forma asíncrona junto con el comando, se omiten en CI y compilaciones de desarrollo, y se pueden deshabilitar con KESTRACTL_VERSION_CHECK_DISABLED=true. Las imágenes de contenedor se ejecutan como un usuario no root, por lo que los archivos de configuración deben montarse en /home/kestractl/.kestractl (Alpine) o /home/nonroot/.kestractl (estático). Los trabajos de contenedor de GitLab CI y GitHub Actions anulan el entrypoint y ejecutan scripts a través de un shell, por lo que se recomienda la etiqueta Alpine predeterminada allí; la etiqueta -static no tiene shell y solo funciona con invocaciones de estilo docker run o kubectl run.