kestractl

kestractl은 Kestra 워크플로우 및 관련 리소스를 관리하기 위한 Go 기반 명령줄 인터페이스입니다. 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의 범위를 포괄합니다. 흐름(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는 위반 시 0이 아닌 종료 코드를 반환하여 CI 게이트 역할을 할 수 있습니다. 실행(Executions): run(--wait 포함), get, list, watch(실시간으로 추적하고 실패 시 0이 아닌 종료 코드 반환), 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, 그리고 ID(namespace/flowId/triggerId)별 및 쿼리별 대량 변형, 백필 관리(create-backfill with --start/--end, backfill-pause, backfill-unpause, backfill-delete 및 해당 by-ids 및 by-query 변형)를 포함합니다. 트리거는 CSV로 내보낼 수도 있습니다. 네임스페이스(Namespaces): list, list with --query, autocomplete, get, create, update, delete, 그리고 반복 가능한 --variable 또는 --variables-file을 통한 네임스페이스 변수 설정, 상속된 시크릿 및 상속된 변수 보기를 포함합니다. 키-값 저장소(Key-Value store): list, set, update, get, delete, 지원 유형은 STRING, NUMBER, BOOLEAN, DATETIME, DATE, DURATION, JSON이며, 선택적 ISO 8601 --ttl이 있습니다. 네임스페이스 파일(Namespace files): list(--path 및 --recursive 포함), get(--revision 포함), upload(단일 파일 또는 디렉토리, --override, --fail-fast, --allow-missing-namespace 포함), delete(--recursive 및 --force 포함). 플러그인(Plugins): 주어진 Kestra 버전의 모든 플러그인 JAR을 대상 디렉토리에 다운로드하며, 병렬 다운로드를 위한 --concurrency, Kestra application.yaml에 필요한 핵심 플러그인(내부 저장소, 시크릿 관리자, 큐/리포지토리 백엔드)만 가져와 독립형 또는 원격 작업자를 부트스트랩하는 --from-config를 포함합니다. list 명령은 다운로드 없이 필요한 핵심 플러그인을 미리 봅니다. 작업자(Workers): registration-tokens generate는 Kestra 인스턴스 없이 작업자 등록 토큰을 생성하기 위해 오프라인으로 실행됩니다. 대시보드(Dashboards, Enterprise Edition): list, get, YAML에서 create, update 및 관련 관리 명령을 포함합니다. 추가 그룹은 앱, 블루프린트, 테스트 스위트 및 IAM(사용자, 그룹, 역할, 서비스 계정, 바인딩, 초대)을 포함합니다. 운영 세부 사항: kestractl은 명령 실행을 차단하지 않는 익명 텔레메트리를 전송하며 KESTRACTL_TELEMETRY_DISABLED=true로 비활성화할 수 있습니다. 업데이트 알림은 ~/.kestractl/check_for_new_available_version.json에 24시간 동안 캐시되며, 명령과 함께 비동기적으로 실행되고, CI 및 개발 빌드에서는 건너뛰며, KESTRACTL_VERSION_CHECK_DISABLED=true로 비활성화할 수 있습니다. 컨테이너 이미지는 비루트 사용자로 실행되므로 구성 파일은 /home/kestractl/.kestractl(Alpine) 또는 /home/nonroot/.kestractl(static)에 마운트해야 합니다. GitLab CI 및 GitHub Actions 컨테이너 작업은 엔트리포인트를 재정의하고 셸을 통해 스크립트를 실행하므로 기본 Alpine 태그를 권장합니다. -static 태그에는 셸이 없으며 docker run 또는 kubectl run 스타일 호출에서만 작동합니다.