kestractl

kestractl est une interface en ligne de commande basée sur Go pour gérer les workflows Kestra et les ressources associées. Il cible Kestra 2.x (les versions v1 couvrant l'ensemble des fonctionnalités de Kestra 1.x) et est testé contre Kestra 2.0, 1.3, 1.2, 1.1 et 1.0 via une matrice e2e ; la source de vérité pour la compatibilité est COMPATIBLE_KESTRA_VERSION.properties. L'installation est proposée via un script pratique (curl | bash) qui récupère la dernière version via l'API REST GitHub, des téléchargements directs de binaires depuis GitHub Releases, des images conteneur multi-arch publiées sur Docker Hub et GHCR (variantes Alpine et distroless), ou la compilation depuis les sources avec Go 1.25+. Le script d'installation accepte les surcharges VERSION et INSTALL_DIR, et peut authentifier les appels API GitHub avec GITHUB_TOKEN pour éviter les limites de débit anonymes. La configuration prend en charge plusieurs contextes nommés (dev, staging, prod) stockés dans ~/.kestractl/config.yaml, avec jeton ou authentification basique, en-têtes HTTP persistants optionnels, et un sélecteur de contexte par défaut. La précédence de configuration suit le modèle 12-factor : les options de ligne de commande, puis les variables d'environnement KESTRACTL_*, puis le fichier de configuration, puis les valeurs par défaut. Les options globales couvrent --host, --token, --username/--password, --tenant, --header, --output (table ou json), --config et --verbose. Les groupes de commandes couvrent l'étendue de l'API Kestra. Flows : list, list-by-namespace, list-deprecated, get, task, deploy (fichier unique ou répertoire, avec --namespace, --override, --fail-fast), validate (fichier local, répertoire, ou validate-by-query contre les flows stockés), 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. Une commande usage-report aide à vérifier les migrations de 1.x vers 2.0, et validate-by-query se termine avec un code non nul en cas de violations, ce qui lui permet de servir de contrôle CI. Exécutions : run (avec --wait), get, list, watch (suit en temps réel et se termine avec un code non nul en cas d'échec), 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 avec suffixe de chemin optionnel), flow-graph, flow-info, flow-info-by-id, download-file, file-metadata, eval-expression, change-status, update-taskrun, delete. Les filtres de requête utilisent le format FIELD:OPERATION:VALUE (par ex. STATE:EQUALS:RUNNING). Déclencheurs : list, search-for-flow, enable, disable, unlock, restart, update, delete, plus des variantes en masse par IDs (namespace/flowId/triggerId) et par requête, et la gestion du backfill (create-backfill avec --start/--end, backfill-pause, backfill-unpause, backfill-delete, et leurs variantes by-ids et by-query). Les déclencheurs peuvent également être exportés en CSV. Espaces de noms : list, list avec --query, autocomplete, get, create, update, delete, plus la définition de variables d'espace de noms via --variable répétable ou --variables-file, et la consultation de inherited-secrets et inherited-variables. Stockage Key-Value : list, set, update, get, delete, avec les types pris en charge STRING, NUMBER, BOOLEAN, DATETIME, DATE, DURATION, JSON, et un --ttl ISO 8601 optionnel. Fichiers d'espace de noms : list (avec --path et --recursive), get (avec --revision), upload (fichier unique ou répertoire, avec --override, --fail-fast, --allow-missing-namespace), delete (avec --recursive et --force). Plugins : télécharge tous les JAR de plugins pour une version donnée de Kestra dans un répertoire cible, avec --concurrency pour les téléchargements parallèles, et --from-config pour amorcer un worker autonome ou distant en ne récupérant que les plugins de base requis par un application.yaml de Kestra (stockage interne, gestionnaire de secrets, backend de file d'attente/dépôt). Une commande list prévisualise les plugins de base requis sans les télécharger. Workers : registration-tokens generate fonctionne hors ligne pour produire un jeton d'enregistrement de worker sans instance Kestra. Tableaux de bord (Enterprise Edition) : list, get, create from YAML, update, et les commandes de gestion associées. D'autres groupes couvrent les applications, les blueprints, les suites de tests et l'IAM (utilisateurs, groupes, rôles, comptes de service, bindings, invitations). Détails opérationnels : kestractl envoie une télémétrie anonyme qui ne bloque jamais l'exécution des commandes et peut être désactivée avec KESTRACTL_TELEMETRY_DISABLED=true. Les notifications de mise à jour sont mises en cache pendant 24 heures dans ~/.kestractl/check_for_new_available_version.json, s'exécutent de manière asynchrone en parallèle de la commande, sont ignorées sur les builds CI et de développement, et peuvent être désactivées avec KESTRACTL_VERSION_CHECK_DISABLED=true. Les images conteneur s'exécutent en tant qu'utilisateur non-root, donc les fichiers de configuration doivent être montés dans /home/kestractl/.kestractl (Alpine) ou /home/nonroot/.kestractl (static). Les jobs conteneur GitLab CI et GitHub Actions remplacent l'entrypoint et exécutent des scripts via un shell, donc le tag Alpine par défaut est recommandé dans ce cas ; le tag -static n'a pas de shell et ne fonctionne qu'avec des invocations de type docker run ou kubectl run.