kestractl

kestractl é uma interface de linha de comando baseada em Go para gerenciar fluxos de trabalho Kestra e recursos relacionados. Ele tem como alvo o Kestra 2.x (com versões v1 cobrindo o conjunto completo de recursos do Kestra 1.x) e é testado contra Kestra 2.0, 1.3, 1.2, 1.1 e 1.0 por meio de uma matriz e2e; a fonte da verdade para compatibilidade é COMPATIBLE_KESTRA_VERSION.properties. A instalação é oferecida por meio de um script de conveniência (curl | bash) que resolve o lançamento mais recente via API REST do GitHub, downloads diretos de binários dos GitHub Releases, imagens de contêiner multi-arquitetura publicadas no Docker Hub e GHCR (variantes Alpine e distroless), ou compilação a partir do código-fonte com Go 1.25+. O script de instalação aceita substituições de VERSION e INSTALL_DIR, e pode autenticar chamadas de API do GitHub com GITHUB_TOKEN para evitar limites de taxa anônimos. A configuração suporta múltiplos contextos nomeados (dev, staging, prod) armazenados em ~/.kestractl/config.yaml, com autenticação por token ou básica, cabeçalhos HTTP persistidos opcionais e um seletor de contexto padrão. A precedência de configuração segue o modelo de 12 fatores: flags de linha de comando, depois variáveis de ambiente KESTRACTL_*, depois o arquivo de configuração, depois padrões. As flags globais cobrem --host, --token, --username/--password, --tenant, --header, --output (table ou json), --config e --verbose. Os grupos de comandos cobrem a amplitude da API Kestra. Fluxos: list, list-by-namespace, list-deprecated, get, task, deploy (arquivo único ou diretório, com --namespace, --override, --fail-fast), validate (arquivo local, diretório ou validate-by-query contra fluxos armazenados), 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. Um comando usage-report ajuda a verificar migrações de 1.x para 2.0, e validate-by-query sai com código não zero em violações para servir como um portão de CI. Execuções: run (com --wait), get, list, watch (segue em tempo real e sai com código não zero em falha), 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 com sufixo de caminho opcional), flow-graph, flow-info, flow-info-by-id, download-file, file-metadata, eval-expression, change-status, update-taskrun, delete. Filtros de consulta usam a forma FIELD:OPERATION:VALUE (ex.: STATE:EQUALS:RUNNING). Gatilhos: list, search-for-flow, enable, disable, unlock, restart, update, delete, além de variantes em massa por IDs (namespace/flowId/triggerId) e por consulta, e gerenciamento de backfill (create-backfill com --start/--end, backfill-pause, backfill-unpause, backfill-delete, e suas variantes por IDs e por consulta). Gatilhos também podem ser exportados como CSV. Namespaces: list, list com --query, autocomplete, get, create, update, delete, além de definir variáveis de namespace via --variable repetível ou --variables-file, e visualizar inherited-secrets e inherited-variables. Armazenamento chave-valor: list, set, update, get, delete, com tipos suportados STRING, NUMBER, BOOLEAN, DATETIME, DATE, DURATION, JSON e --ttl ISO 8601 opcional. Arquivos de namespace: list (com --path e --recursive), get (com --revision), upload (arquivo único ou diretório, com --override, --fail-fast, --allow-missing-namespace), delete (com --recursive e --force). Plugins: baixar todos os JARs de plugins para uma versão Kestra dada em um diretório alvo, com --concurrency para downloads paralelos, e --from-config para inicializar um worker autônomo ou remoto puxando apenas os plugins principais necessários por um Kestra application.yaml (armazenamento interno, gerenciador de segredos, backend de fila/repositório). Um comando list pré-visualiza os plugins principais necessários sem baixar. Workers: registration-tokens gera offline um token de registro de worker sem uma instância Kestra. Dashboards (Enterprise Edition): list, get, create a partir de YAML, update e comandos de gerenciamento relacionados. Grupos adicionais cobrem apps, blueprints, suítes de teste e IAM (usuários, grupos, papéis, contas de serviço, vínculos, convites). Detalhes operacionais: kestractl envia telemetria anônima que nunca bloqueia a execução de comandos e pode ser desabilitada com KESTRACTL_TELEMETRY_DISABLED=true. Notificações de atualização são armazenadas em cache por 24 horas em ~/.kestractl/check_for_new_available_version.json, executadas assincronamente junto com o comando, são ignoradas em CI e builds de desenvolvimento, e podem ser desabilitadas com KESTRACTL_VERSION_CHECK_DISABLED=true. As imagens de contêiner executam como um usuário não root, então arquivos de configuração devem ser montados em /home/kestractl/.kestractl (Alpine) ou /home/nonroot/.kestractl (static). Trabalhos de contêiner GitLab CI e GitHub Actions substituem o entrypoint e executam scripts por meio de um shell, então a tag Alpine padrão é recomendada lá; a tag -static não tem shell e só funciona com invocações docker run ou kubectl run.