kestractl

kestractl 是一个基于 Go 的命令行界面，用于管理 Kestra 工作流及相关资源。它针对 Kestra 2.x（v1 版本覆盖完整的 Kestra 1.x 功能集），并通过 e2e 矩阵对 Kestra 2.0、1.3、1.2、1.1 和 1.0 进行测试；兼容性的权威来源是 COMPATIBLE_KESTRA_VERSION.properties。 安装方式包括便捷脚本（curl | bash），该脚本通过 GitHub REST API 解析最新版本，直接从 GitHub Releases 下载二进制文件，发布到 Docker Hub 和 GHCR 的多架构容器镜像（Alpine 和 distroless 变体），或使用 Go 1.25+ 从源码构建。安装脚本接受 VERSION 和 INSTALL_DIR 覆盖，并可使用 GITHUB_TOKEN 对 GitHub API 调用进行身份验证，以避免匿名速率限制。 配置支持存储在 ~/.kestractl/config.yaml 中的多个命名上下文（dev、staging、prod），支持令牌或基本认证、可选持久化 HTTP 头，以及默认上下文选择器。配置优先级遵循 12-factor 模型：命令行标志，然后是 KESTRACTL_* 环境变量，然后是配置文件，最后是默认值。全局标志涵盖 --host、--token、--username/--password、--tenant、--header、--output（table 或 json）、--config 和 --verbose。 命令组涵盖 Kestra API 的广度。流程：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 门禁。 执行：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）。 触发器：list、search-for-flow、enable、disable、unlock、restart、update、delete，以及按 ID（namespace/flowId/triggerId）和按查询的批量变体，以及回填管理（create-backfill 带 --start/--end、backfill-pause、backfill-unpause、backfill-delete，及其 by-ids 和 by-query 变体）。触发器也可以导出为 CSV。 命名空间：list、带 --query 的 list、autocomplete、get、create、update、delete，以及通过可重复的 --variable 或 --variables-file 设置命名空间变量，并查看 inherited-secrets 和 inherited-variables。 键值存储：list、set、update、get、delete，支持类型 STRING、NUMBER、BOOLEAN、DATETIME、DATE、DURATION、JSON，以及可选的 ISO 8601 --ttl。 命名空间文件：list（带 --path 和 --recursive）、get（带 --revision）、upload（单个文件或目录，带 --override、--fail-fast、--allow-missing-namespace）、delete（带 --recursive 和 --force）。 插件：将给定 Kestra 版本的所有插件 JAR 下载到目标目录，带 --concurrency 进行并行下载，以及 --from-config 通过仅拉取 Kestra application.yaml 所需的核心插件（内部存储、密钥管理器、队列/仓库后端）来引导独立或远程工作器。list 命令预览所需的核心插件而不下载。 工作器：registration-tokens 生成离线运行，以产生工作器注册令牌，无需 Kestra 实例。 仪表板（企业版）：list、get、从 YAML 创建、update 及相关管理命令。 其他组涵盖应用、蓝图、测试套件和 IAM（用户、组、角色、服务账户、绑定、邀请）。 操作细节：kestractl 发送匿名遥测，从不阻塞命令执行，可通过 KESTRACTL_TELEMETRY_DISABLED=true 禁用。更新通知缓存 24 小时在 ~/.kestractl/check_for_new_available_version.json，与命令异步运行，在 CI 和开发构建中跳过，可通过 KESTRACTL_VERSION_CHECK_DISABLED=true 禁用。容器镜像以非 root 用户运行，因此配置文件应挂载在 /home/kestractl/.kestractl（Alpine）或 /home/nonroot/.kestractl（static）。GitLab CI 和 GitHub Actions 容器作业覆盖入口点并通过 shell 运行脚本，因此建议使用默认 Alpine 标签；-static 标签没有 shell，仅适用于 docker run 或 kubectl run 风格的调用。