kestra-ops

Kestra 運用スキル

kestractl を使用して、日常的な Kestra 運用を行うためのスキルです。

使用する場面

次のようなリクエストがあった場合に、このスキルを使用します。

• フローの一覧表示、確認、検証、デプロイ
• 実行のトリガーと実行ステータスの確認
• 名前空間または名前空間ファイル（nsfiles）の管理
• Kestra CLI コンテキストの設定または切り替え

Kestra 2.0 への移行 — 委任してください。 Kestra 1.3 から 2.0 への移行またはアップグレードに関するリクエスト（準備状況の確認、kestra-migrate の警告、2.0 でフローの解析に失敗する問題）については、インストール済みのエージェントスキルから migrate-kestra-2 という名前のものを検索してください。ユーザーのスキルがインストールされている場所（プロジェクトまたはユーザーのスコープ）を問わず検索します。利用可能な場合は、そのスキルを使用してください。移行を進め、kestractl のサブ操作には kestra-ops を呼び出します。インストールされていない場合は、ユーザーにインストールを促してから、次のように委任してください。

npx skills add kestra-io/agent-skills@migrate-kestra-2

必要な入力

• 対象の環境またはコンテキスト（dev、staging、prod）
• ホスト URL、テナント、認証方法（通常はトークン）
• 名前空間、フロー ID、実行 ID、および／またはローカルファイルパス
• 出力形式（人が読みやすい形式なら table、自動化向けなら json）

前提条件

• kestractl がインストールされ、実行可能であること
• アクセストークンとテナントを利用できること
• ~/.kestractl/config.yaml に有効なコンテキストが存在するか、環境変数／フラグで値が指定されていること

設定の優先順位

設定は、優先順位の高いものから順に適用します。

1. コマンドフラグ（--host、--tenant、--token、--output）
2. 環境変数（KESTRACTL_HOST、KESTRACTL_TENANT、KESTRACTL_TOKEN、KESTRACTL_OUTPUT）
3. 設定ファイル（~/.kestractl/config.yaml）
4. 組み込みのデフォルト値

一般的なセットアップ：

kestractl config add dev http://localhost:8080 main --token DEV_TOKEN
kestractl config add prod https://prod.kestra.io production --token PROD_TOKEN
kestractl config use dev
kestractl config show

標準的なワークフロー

1. 対象のコンテキストを特定し、確認します。
2. まず読み取り専用の調査を行います。
3. デプロイ前にアーティファクトを検証します。
4. 明示的なフラグを指定して、依頼された操作を実行します。
5. 結果を確認します（必要に応じて実行操作に --wait を指定します）。
6. 結果と次のアクションを含む、簡潔な運用レポートを返します。

コマンドのパターン

フロー：

kestractl flows list my.namespace
kestractl flows get my.namespace my-flow
kestractl flows validate ./flows/
kestractl flows deploy ./flows/ --namespace prod.namespace --override --fail-fast

実行：

kestractl executions run my.namespace my-flow --wait
kestractl executions get 2TLGqHrXC9k8BczKJe5djX

名前空間：

kestractl namespaces list
kestractl namespaces list --query my.namespace

名前空間ファイル：

kestractl nsfiles list my.namespace --path workflows/ --recursive
kestractl nsfiles get my.namespace workflows/example.yaml --revision 3
kestractl nsfiles upload my.namespace ./assets resources --override --fail-fast
kestractl nsfiles delete my.namespace workflows --recursive

ガードレール

• 書き込み操作（deploy、upload、delete）の前に、本番環境のコンテキストであることを確認します。
• flows deploy の前に flows validate を実行することを推奨します。
• スクリプトや自動化の信頼性を高めるため、--output json を使用します。
• 認証情報が漏えいする可能性があるため、共有ログでは --verbose を使用しないでください。
• 破壊的な nsfiles 操作では、対象パスの範囲を確認し、意図した場合にのみ --force を使用します。

レスポンス形式

• 使用したコンテキスト（ホスト、テナント、コンテキスト名）
• 実行したコマンド（読み取り操作と書き込み操作に分けて記載）
• 結果（成功／失敗と主要な ID）
• リスク、ロールバックに関する注記、次のアクション

プロンプトの例

• 「kestra-ops を使って、./flows 内のすべてのフローを prod.namespace に fail-fast を有効にして検証・デプロイし、変更内容を報告してください。」
• 「kestra-ops を使って、my.namespace の my-flow を実行し、完了を待ってから実行ステータスを要約してください。」
• 「kestra-ops を使って、./assets を override を有効にして resources 配下の名前空間ファイルにアップロードし、アップロードしたファイルを再帰的に一覧表示してください。」