ワークフロー(Pro)
ワークフローを使用すると、複数のタスクテンプレートを分岐、承認、時限停止を含む 有向グラフ(DAG)として連結できます。ワークフローの実行は各ステップの完了に応じて 自動的に進行します。ビジュアルエディターでグラフを一度設計すれば、 あとは Workflows ページから実行を開始できます。
ワークフローは Semaphore Pro の機能です。Workflows メニュー項目は、 サブスクリプションにワークフローが含まれている場合にのみ表示されます。
概要
ワークフローは次の要素で構成されます。
- ノード — グラフ内のステップ(テンプレートの実行、承認待ち、遅延による一時停止、 またはノートによる注釈)。
- エッジ — ノード間の接続。それぞれに下流ノードをいつ開始するかを制御する 条件 が付けられます。
ワークフローを開始すると、Semaphore は ワークフロー実行 を作成します。進行は サーバーが制御します。タスクの完了、承認の解決、遅延の期限切れに応じて、 エッジの条件に従って下流ノードが起動されます。
ワークフローの作成
- プロジェクトを開き、Workflows に移動します。
- New Workflow をクリックします。
- グラフィカルエディターで次の操作を行います。
- パレットからキャンバスへノードをドラッグします。
- あるノードの出力ハンドルから別のノードへドラッグしてノードを接続します。
- ノードまたはエッジをクリックして、サイドパネルでプロパティを編集します。
- 名前 を設定します(実行のバージョン管理のために、必要に応じて 開始バージョン も設定します)。
- Problems パネルに表示された問題を修正し、Save をクリックします。
エディターは保存前にグラフを検証します。有効なワークフローには、少なくとも 1 つのノード、 ちょうど 1 つの開始ノード(入力エッジを持たないノード)があり、循環がなく、 実行可能なすべてのノードの設定が完了している必要があります。
ノードの種類
| 種類 | 目的 |
|---|---|
| Task | タスクテンプレートを実行します。task params を使用して、ノードごとにテンプレートのパラメーター(inventory、環境、Ansible の limit、追加の CLI 引数)を上書きできます。 |
| Approval | 権限を持つユーザーが承認または却下するまで実行を一時停止します。必要に応じてタイムアウト(秒)と承認メッセージを設定できます。 |
| Delay | 設定された秒数だけ待機してから下流ノードへ進みます。クールダウン期間、メンテナンスウィンドウ、依存するステップの間隔調整に便利です。 |
| Note | キャンバス上の自由形式の注釈です。Note ノードは実行されず、エッジで接続されることもありません。ドキュメント目的専用です。 |
収束
複数の入力エッジを持つノードでは、すべて の上流ノードの完了を要求する(デフォルト)か、 いずれか 1 つの完了を要求するかを選べます。ノードのプロパティパネルで Convergence を設定します。
Delay ノード
Delay ノードは、設定された時間(最小 1 秒)だけワークフロー実行を一時停止します。 待機中は次のようになります。
- 実行は running ステータスのままです。
- 実行ビューの Delay ノードにライブカウントダウンが表示されます。
- エッジで接続された下流ノードは、遅延が完了するまで開始されません。
遅延がアクティブな間にワークフロー実行が 停止 された場合、遅延はキャンセルされ、 実行は stopped ステータスで終了します。
Approval ノード
実行が Approval ノードに到達すると、誰かが承認または却下するまでステータスは approval に変わります。実行ビューに Approve/Reject のコントロールが表示されます。 却下された承認は、接続されたエッジの条件に従って実行を失敗させます。
エッジの条件
各エッジには、下流ノードがいつ準備完了になるかを決定する条件があります。
| 条件 | 上流ノードが次の状態になったときに下流が開始… |
|---|---|
| On success | 正常に完了したとき(デフォルト)。 |
| On failure | エラーで完了したとき。 |
| Always | いずれかの終了状態(成功または失敗)で完了したとき。 |
補償アクションや通知には On failure の分岐を使用します。結果にかかわらず次のステップを 実行したい場合は Always を使用します。
実行と監視
- Run workflow — Workflows 一覧から新しい実行を開始します。
- 実行ビュー — 各ノードのライブステータス(running、success、failed、approval、 遅延のカウントダウン)を表示する全画面グラフです。
- Stop — 実行が
runningまたはapprovalの間、run_project_tasksを持つユーザーは 実行を停止できます。アクティブなタスクはすべて停止され、保留中の承認は却下され、 実行は stopped としてマークされます。
実行ステータス: running、approval、success、failed、stopped。
実行のバージョン管理
ワークフローに Start version(例: 1.0.0)を設定すると、各実行にバージョンラベルが
付与されます。Semaphore はビルドテンプレートと同様に、実行のたびにバージョンを
インクリメントします。
ワークフローアーティファクト(set_stats)
ワークフロー内の Ansible タスクが set_stats を使用すると、その変数はその実行の
ワークフローアーティファクト として保存されます。同じ実行内の下流の Task ノードは、
それらを追加変数として自動的に受け取ります。
ワークフ ロー内のステップが リモート runner で実行される場合、ワークフローアーティファクトは まだリモート runner のステップ間では受け渡されません。アーティファクトは Semaphore サーバー上で ローカルに実行されるタスク間でのみ渡されます。アーティファクトの受け渡しを考慮して計画するか、 アーティファクトを生成するステップと消費するステップを同じ実行経路に配置してください。
権限
- ワークフローの管理(作成、編集、削除)には、プロジェクトリソースの管理権限が 必要です。
- ワークフローの実行には
run_project_tasksが必要です。 - 承認の解決には適切なプロジェクトアクセス権が必要です(プロジェクトでタスクを実行できる ユーザーと同じです)。
API
ワークフローテンプレートと実行は
/api/project/{project_id}/workflows で利用できます。delay ノードのフィールド(delay_seconds)や
停止エンドポイント(POST …/runs/{run_id}/stop)を含むリクエストおよびレスポンスのスキーマについては、
API ドキュメント を参照してください。