kestractl

kestractl — это интерфейс командной строки на Go для управления рабочими процессами Kestra и связанными ресурсами. Он ориентирован на Kestra 2.x (релизы v1 покрывают полный набор функций Kestra 1.x) и проверяется на Kestra 2.0, 1.3, 1.2, 1.1 и 1.0 через матрицу e2e-тестов; источником истины для совместимости является COMPATIBLE_KESTRA_VERSION.properties. Установка предлагается через удобный скрипт (curl | bash), который определяет последний релиз через GitHub REST API, прямое скачивание бинарных файлов с GitHub Releases, многоплатформенные контейнерные образы, публикуемые в Docker Hub и GHCR (варианты Alpine и distroless), или сборку из исходников с Go 1.25+. Скрипт установки принимает параметры VERSION и INSTALL_DIR, а также может аутентифицировать запросы к GitHub API с помощью GITHUB_TOKEN для обхода анонимных лимитов скорости. Конфигурация поддерживает несколько именованных контекстов (dev, staging, prod), хранящихся в ~/.kestractl/config.yaml, с токеном или базовой аутентификацией, опциональными постоянными HTTP-заголовками и селектором контекста по умолчанию. Приоритет конфигурации соответствует модели 12 факторов: флаги командной строки, затем переменные окружения KESTRACTL_*, затем файл конфигурации, затем значения по умолчанию. Глобальные флаги охватывают --host, --token, --username/--password, --tenant, --header, --output (table или json), --config и --verbose. Группы команд охватывают весь спектр API Kestra. Потоки (Flows): list, list-by-namespace, list-deprecated, get, task, deploy (один файл или каталог, с --namespace, --override, --fail-fast), validate (локальный файл, каталог или validate-by-query для сохранённых потоков), 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. Команда usage-report помогает проверять миграции с 1.x на 2.0, а validate-by-query завершается с ненулевым кодом при нарушениях, поэтому может использоваться как CI-шлюз. Выполнения (Executions): run (с --wait), get, list, watch (следует в реальном времени и завершается ненулевым кодом при сбое), 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 с опциональным суффиксом пути), flow-graph, flow-info, flow-info-by-id, download-file, file-metadata, eval-expression, change-status, update-taskrun, delete. Фильтры запросов используют форму FIELD:OPERATION:VALUE (например, STATE:EQUALS:RUNNING). Триггеры (Triggers): list, search-for-flow, enable, disable, unlock, restart, update, delete, а также массовые варианты по идентификаторам (namespace/flowId/triggerId) и по запросу, и управление бэкфиллом (create-backfill с --start/--end, backfill-pause, backfill-unpause, backfill-delete, а также их варианты by-ids и by-query). Триггеры также можно экспортировать в CSV. Пространства имён (Namespaces): list, list с --query, autocomplete, get, create, update, delete, а также установка переменных пространства имён через повторяемый --variable или --variables-file, и просмотр inherited-secrets и inherited-variables. Key-Value хранилище: list, set, update, get, delete, с поддерживаемыми типами STRING, NUMBER, BOOLEAN, DATETIME, DATE, DURATION, JSON и опциональным --ttl в формате ISO 8601. Файлы пространств имён (Namespace files): list (с --path и --recursive), get (с --revision), upload (один файл или каталог, с --override, --fail-fast, --allow-missing-namespace), delete (с --recursive и --force). Плагины (Plugins): загрузка всех JAR-файлов плагинов для заданной версии Kestra в целевой каталог, с --concurrency для параллельных загрузок и --from-config для начальной настройки автономного или удалённого воркера путём загрузки только основных плагинов, необходимых для Kestra application.yaml (внутреннее хранилище, менеджер секретов, бэкенд очереди/репозитория). Команда list показывает предварительный список требуемых основных плагинов без загрузки. Воркеры (Workers): registration-tokens generate работает офлайн для создания токена регистрации воркера без экземпляра Kestra. Дашборды (Enterprise Edition): list, get, create из YAML, update и связанные команды управления. Дополнительные группы охватывают приложения, блюпринты, тестовые наборы и IAM (пользователи, группы, роли, сервисные аккаунты, привязки, приглашения). Операционные детали: kestractl отправляет анонимную телеметрию, которая никогда не блокирует выполнение команд и может быть отключена с помощью KESTRACTL_TELEMETRY_DISABLED=true. Уведомления об обновлениях кэшируются на 24 часа в ~/.kestractl/check_for_new_available_version.json, выполняются асинхронно вместе с командой, пропускаются в CI и dev-сборках и могут быть отключены с помощью KESTRACTL_VERSION_CHECK_DISABLED=true. Контейнерные образы работают от непривилегированного пользователя, поэтому файлы конфигурации следует монтировать в /home/kestractl/.kestractl (Alpine) или /home/nonroot/.kestractl (static). Контейнерные задания GitLab CI и GitHub Actions переопределяют точку входа и запускают скрипты через оболочку, поэтому там рекомендуется тег Alpine по умолчанию; тег -static не имеет оболочки и работает только с вызовами docker run или kubectl run.