# Runbooks の概要

> Source: https://docs.lorel.ai/guides/runbooks/

インシデント対応や定常運用などの定型的な作業手順を、事前に定義した一連のステップとして自動実行・管理する機能について説明します。

## 概要

Lorel.ai の Runbooks は、コマンドの実行、スクリプトの実行、外部 API の呼び出し、クラウド操作、承認フロー、条件分岐などを組み合わせて、運用のワークフローを自動化できる機能です。

作成した Runbook は、［下書き］［有効］［無効］のいずれかのステータスを持ち、有効になっているものだけが実行できます。

実行は、ユーザーによる手動実行のほか、インシデントポリシーによる自動起動など、複数の起点から開始されます。

- **ステップの定義。** シェルコマンド、Python や Bash などのスクリプト、外部 API、クラウド操作、通知、承認などを組み合わせて定義します。
- **実行の制御フロー。** 条件分岐、リトライループ、繰り返し、並列実行、条件待機に対応しています。
- **安全な運用の設計。** 承認者による手動承認のステップ、ステップが失敗したときの自動リカバリー（ジャンプ・スキップ・停止）、暴走を防ぐための上限を、標準で備えています。

## できること

Runbooks でできる主な機能・操作と、必要なプロジェクトのロールの一覧です。

| 機能・操作 | 説明 | 必要なロール |
|---|---|---|
| ステップの定義 | コマンド、スクリプト（Python や Bash など）、外部 API の呼び出し、クラウド操作、通知など、多彩なステップを組み合わせて、手順を定義します。 | プロジェクト管理者 / 編集者 |
| 制御フローの構築 | 条件分岐、リトライループ、繰り返し、並列実行、条件待機により、実行の順序を柔軟に制御できます。 | プロジェクト管理者 / 編集者 |
| クラウド操作の自動化 | 接続先のクラウド環境の管理 API の操作を、踏み台サーバーなしで、直接実行します。 | プロジェクト管理者 / 編集者 |
| 承認フローの設定・判定 | 重要なステップの前に承認者を指定して、実行前の承認を必須にします（承認・否認の判定を含みます）。 | 設定はプロジェクト管理者 / 編集者。承認・否認は、指定された承認者（プロジェクト管理者 / 編集者） |
| 変数・出力の連携 | 前のステップの実行結果（出力値）や、定義した変数を、後続のステップへ引き継いで参照します。 | プロジェクト管理者 / 編集者 |
| テスト実行 | 原則として実際の環境に変更を加えずに、モックの応答を使って、ステップの設定や変数の連携を事前に検証します。コマンドとスクリプトは実行されませんが、接続先のインスタンスへの読み取り専用の到達確認は実際に行われ、失敗するとテスト実行も失敗します（例外は、後述の制限事項にあるテスト実行の項目を参照してください）。 | プロジェクト管理者 / 編集者 / ワーカー（クラウド操作を含む Runbook は、ワーカーの実行を許可した場合のみ） |
| 手動実行・実行の中断 | 有効な Runbook を画面から手動で実行したり、進行中の実行を中断したりします。 | プロジェクト管理者 / 編集者 / ワーカー（クラウド操作を含む Runbook の実行は、ワーカーの実行を許可した場合のみ。中断は常に可能） |
| 手動リトライ・スキップ | エラーや承認の否認で一時停止しているステップを、手動でリトライまたはスキップして、処理を進めます。 | プロジェクト管理者 / 編集者 / ワーカー（クラウド操作を含む Runbook は、ワーカーの実行を許可した場合のみ） |
| ライフサイクルの管理 | 下書きの作成、有効化・無効化、複製、削除などのステータスを管理します。 | 作成・編集・有効化・複製・削除はプロジェクト管理者 / 編集者。無効化と下書きに戻す操作はプロジェクト管理者 / 編集者 / ワーカー |

## Runbook のライフサイクル

Runbook は、次の3つのステータスで管理されます。

［下書き］ → ［有効］ ⇄ ［無効］、［無効］ → ［下書き］

- **下書き。** 作成中または編集中で、まだ実行できない状態です（［下書きとして保存］で保存した状態）。
- **有効。** 利用できる状態です。手動実行や自動起動の対象になります（［保存して有効化］で保存した状態）。
- **無効。** 一時的に利用を停止している状態です。新しい実行は開始できません（過去の実行履歴は保持されます）。無効の状態からは、有効に戻すか、下書きに戻せます。

有効な Runbook は削除できません。削除する場合は、先に無効にしてください。

## 実行の起点

Runbook の実行は、次のいずれかを起点として開始されます。

| 起点 | 説明 |
|---|---|
| 手動実行 | ユーザーが画面上の［実行］ボタンから、明示的に開始します。 |
| インシデントからの自動起動 | インシデントポリシーに、あらかじめ既定の Runbook として設定しておくと、新しいインシデントが起票されたときに、自動で起動します。1つのインシデントポリシーには、既定の Runbook と AI エージェントの自動起動を同時に設定できません。詳細は、[Rules の概要](/guides/rules/)を参照してください。 |
| Tasks からの自動起動 | Tasks で作成した繰り返しのタスクに Runbook が紐付けられている場合、タスクが自動生成されるときに、有効な Runbook が起動します。 |
| AI エージェントの提案の承認 | AI エージェント（カスタムエージェント）が、インシデントの分析の結果として提案した Runbook を、担当者が画面上で承認したときに起動します。詳細は、[AI Agents の概要](/guides/ai-agents/)を参照してください。 |
| 制御フローからの子の実行 | 並列実行や、サブ Runbook を呼び出すステップから、子の実行として自動的に起動します。 |

## Runbooks の一覧画面の見方と操作

サイドバーの［Runbooks］を開くと、プロジェクトに登録されているすべての Runbook が、一覧で表示されます。

### 画面上部の操作エリア

画面上部のバーから、Runbook の絞り込みや検索、新規作成を行えます。

| 操作の要素 | 説明 |
|---|---|
| ステータスの切り替え | ［すべて］［下書き］［有効］［無効］をクリックして、該当するステータスの Runbook だけを表示します。 |
| タグでの絞り込み | ［タグ］のプルダウン（［タグを選択］）からタグを選択して、そのタグが付いた Runbook を絞り込みます。複数のタグを選択した場合は、いずれかのタグが付いた Runbook が表示されます。 |
| Runbook 名での検索 | 入力欄にキーワードを入力して、Runbook の名前で部分一致の検索を行います。 |
| ［ランブックを作成］ | 新しい Runbook の作成画面を開きます。 |

### 一覧テーブルの表示項目

一覧の各行をクリックすると、その Runbook の詳細画面に移動します。各列には、次の情報が表示されます。

| 列 | 表示内容 | 並び替え |
|---|---|---|
| ステータス | 現在の状態（［有効］［無効］［下書き］）が、色分けしたバッジで表示されます。 | できます |
| ［ランブック名］ | Runbook の名称と、設定されたタグ（例：db、production、critical）が表示されます。タグは先頭の3個まで表示され、残りは +N の形で個数だけが表示されます。 | できません |
| 最新実行 | 直近の実行の結果が、色分けしたバッジで表示されます（［成功］［未完了］［キャンセル］［進行中］。実行がまだない場合は「-」）。一時停止と失敗の実行は［未完了］、実行中・承認待ち・キャンセル処理中の実行は［進行中］として表示されます。 | できません |
| 目安時間 | ［基本情報］で設定した、標準的な想定時間（例：30分）が表示されます。 | できません |
| 成功率 | 完了した実行にもとづく成功率が表示されます。 | できます |
| 実行回数 | 完了した実行の回数が表示されます。 | できます |
| 最終実行日時 | 最後に完了した実行からの経過時間・日時（例：10日前）が表示されます。完了した実行がまだない場合は、［未実行］と表示されます。 | できます |
| 更新日時 | 最後に更新してからの経過時間・日時（例：100日前）が表示されます。 | できます |

実行回数、成功率、最終実行日時は、完了した実行だけをもとに集計されます。テスト実行、サブ Runbook や並列実行から起動された子の実行、中断された実行や失敗した実行は含まれません。

一方、［最新実行］のバッジは、直近の実行の状態をそのまま表します。テスト実行や子の実行、失敗した実行や中断された実行も対象です。［キャンセル］のバッジは、実行詳細で「中断」と表示される状態と同じです。

※並び替えができる列は、列ヘッダーの↑↓のアイコンをクリックして、昇順・降順を切り替えます。

## Runbook の作成手順

新しい Runbook を作成するには、サイドバーの［Runbooks］を開き、画面右上の［ランブックを作成］をクリックします。

作成画面は、［基本情報］［ナレッジ］［ステップ］の3つのタブで構成されています。［下書きとして保存］または［保存して有効化］を選択できます。

### 基本情報（必須）の設定

Runbook の名称や説明、実行時間の制約、タグなどの基本設定を行います。

| 設定項目 | 区分 | 説明・設定内容 |
|---|---|---|
| 名前 | 必須（最大255文字） | Runbook の名称を入力します（例：データベース障害対応手順）。 |
| 説明 | 任意（最大4,000文字） | Runbook の目的、対象のシステム、発動する条件などを、具体的に入力します。AI エージェントに Runbook を紐付ける場合、エージェントが実行を提案する Runbook を判断するための重要な材料として、この説明が参照されます。 |
| 目安実行時間（分） | 任意 | 実行にかかる標準的な想定時間を、分単位で入力します（例：30）。 |
| 最大実行時間（分） | 任意 | 実行全体の制限時間を、分単位で指定します。実行中または一時停止中のまま設定時間を超えると、自動的に失敗として終了します。設定時間に達した時点で承認待ちだった実行は、その後も最大実行時間による失敗の対象になりません。未設定の場合は、制限がありません。 |
| タグ | 任意（最大50個） | 分類や検索に使うタグを入力し、Enter またはカンマ（,）で追加します。 |

#### わかりやすい「説明」の書き方（AI エージェント・運用者向けのガイド）

説明欄の横にある［書き方ガイド］をクリックすると、書き方のガイドを確認できます。

- **目的・実行内容。** 何のための手順で、何をするかを書きます。（例：サービスの復旧のために対象を再起動する、ディスクが逼迫したときに古いログを退避して空き容量を確保する）
- **対象・環境。** 対象のシステムや環境を、固有名で特定して書きます。（例：本番の Aurora（MySQL）クラスタ、検証環境の Web サーバー群（EC2））
- **発動条件・しきい値。** どんな状態のときに使うかを、具体的な数値で書きます。（例：CPU 使用率が90%を10分以上超えたとき、レプリカラグが5分以上続くとき）
- **使わない場面。** 使わない条件や、似た手順との違いを書きます。（例：ラグが5分未満のときは使わない、検証環境には適用しない）
- **結果・副作用。** 実行後に何が起きるか、元に戻せない影響を書きます。（例：再起動中は数分間アクセスできなくなる、削除したデータは復元できない）

書くときは、主語を明確にした能動態・現在形で、客観的な事実として記述します（「〜せよ」などの命令形は避けます）。コマンドや個々の作業手順は、説明欄には書かず、［ステップ］や［ナレッジ］に記載してください。

### ナレッジ（任意）の設定

Runbook に関連する詳細な運用マニュアル、トラブルシューティングのノウハウ、構成メモなどを、Markdown 形式で自由に記録できます（最大20,000文字）。

入力エリアの下部にあるリンクから、2つの編集モードをいつでも切り替えられます。

- **リッチな入力に切り替える。** 見出しや太字、リストなどの装飾を視覚的に確認しながら、直感的なリッチテキストとして編集できます。
- **シンプルな入力に切り替える。** 装飾のない、標準的な Markdown のテキストとして直接編集できます。

### ステップ（有効化には1件以上が必要）の設定

Runbook で実際に実行する、一連の処理のステップを定義します。下書きとして保存するだけなら、ステップが0件でも保存できます。

ステップがまだない新規作成の状態では、画面中央の［ステップを追加］をクリックして、ステップを追加します。ステップを追加すると、画面上部に［ステップ一覧］と［フロー図］の切り替えタブが表示され、好みの表示形式で、構成をいつでも確認できます。

#### ステップカードの操作と並び替え

追加した各ステップカードでは、次の操作を行えます。

- **実行順序の並び替え。** カード左側のドラッグハンドルにカーソルを合わせて、上下にドラッグ＆ドロップします。
- **表示の折りたたみ・展開。** カード右側のシェブロンのアイコン（展開中は下向き、折りたたみ中は右向き）をクリックして、設定内容を開閉します。
- **ステップの削除。** カード右上のゴミ箱のアイコンをクリックします。

#### ステップ共通の基本項目

- **種別（必須）。** プルダウンから、実行したいステップの種別を選択します。
- **ステップ名（必須）。** ステップの名称を入力します。半角の英字（a-z、A-Z）、数字、アンダースコア、ハイフンのみ使え、同じ Runbook の中で重複できません（例：check_db_process）。後続のステップから出力を参照するときのキーになります。式の中ではハイフンが引き算として解釈されるため、ハイフンは避けてください。
- **説明（任意）。** このステップで行う処理の内容や目的を入力します。

#### ステップ共通の実行制御

各ステップカードの「詳細設定」の中にある「実行制御」を開くと、ステップ単位の時間制限や、エラー時の自動リカバリーの設定を行えます。

| 設定項目 | 区分 | 説明・設定内容 |
|---|---|---|
| タイムアウト（秒） | 任意 | ステップ単位の最大実行時間を、秒単位で指定します（1〜300秒、最大5分）。コマンドとスクリプトは、安全に処理を完了させるため、30〜300秒の範囲でのみ指定できます。指定できるのは、コマンド、スクリプト、API 呼び出し、クラウド操作のステップです。待機、承認、通知、変数設定、条件分岐と、リトライループ・繰り返し・並列実行・条件待機・サブ Runbook 呼び出しの各ステップでは、この欄を指定できません。 |
| リトライ回数 | 任意 | ステップが失敗したときの自動再試行の回数を指定します（既定値：0回）。クラウド操作は、リトライ回数を設定しても、失敗時に自動では再試行されません。この欄は、リトライループ・繰り返し・並列実行・条件待機・サブ Runbook 呼び出しのステップでは表示されません。 |
| 失敗時の動作 | 必須（プルダウン） | リトライの上限に達しても失敗した場合の動作を選択します。［停止］は、実行を一時停止して、ユーザーの介入（手動のリトライやスキップ）を待ちます（既定の安全な動作です）。［スキップ］は、エラーを無視してこのステップをスキップし、後続のステップに進みます。［分岐先へ移動］は、あらかじめ指定した別のリカバリー用のステップにジャンプします。 |

##### 分岐先へ移動（ジャンプ）の動作のルール

失敗時の動作で［分岐先へ移動］を選択した場合、ジャンプ先の位置によって、次の動作になります。

- **ジャンプ先が、現在のステップより後ろにある場合。** 失敗したステップとジャンプ先の間にある、未実行のステップは、すべて自動的にスキップされ、ジャンプ先のステップから処理が続きます。
- **ジャンプ先が、現在のステップと同じか、それより前にある場合。** ジャンプ先から現在のステップまでの範囲が、リカバリー用のループとして再実行されます。
- **ジャンプ先のステップが見つからない場合（安全対策）。** ジャンプ先の設定が不正な状態になっている場合などは、予期しない誤動作を防ぐため、安全側の動作として、自動的に［停止］として扱われます。

### ステップ種別の一覧

Runbooks では、目的や役割に応じたステップを自由に組み合わせて、ワークフローを構築できます。画面のステップ種別のプルダウンでは、種別がひとつの一覧で表示されます。ここでは、役割ごとに整理して説明します。

#### アクション・連携系

EC2 インスタンスやクラウド環境、外部サービスに対して、実際の操作や確認を行います。

| ステップ種別 | 内容・用途 |
|---|---|
| コマンド | 接続先の Amazon EC2 インスタンス（SSM Agent インストール済み）上で、シェルコマンドを1つ実行します。終了コードや標準出力（JSONPath）を抽出できます。 |
| スクリプト | 接続先の Amazon EC2 インスタンス（SSM Agent インストール済み）上で、Bash / Python / PowerShell / Ruby の複数行のスクリプトを実行します。 |
| API 呼び出し | 外部の Web API（HTTPS）を、GET / POST / PUT / PATCH / DELETE で呼び出して、レスポンスを取得します。 |
| クラウド操作 | 接続先のクラウドの管理 API を1つ実行します。踏み台サーバーなしで、マネージドデータベースの再起動やログの参照などの操作を組み込めます。対応しているクラウドは AWS です。 |

#### コミュニケーション・承認系

運用担当者への通知や、重要なステップを実行する前の判断を行います。

| ステップ種別 | 内容・用途 |
|---|---|
| 通知 | 指定したプロジェクトのメンバーまたはロールへ、アプリ内の通知（Jinja2 のテンプレートに対応）を送信します。既定では、アプリ内の通知が作成されたときにメールでも届きますが、受信者がその種類の通知またはメール転送を通知設定でオフにしている場合は、メールでは届きません。Slack、Teams、PagerDuty への送信には対応していません。 |
| 承認 | 指定したロール（プロジェクト管理者 / 編集者）またはメンバーの承認を待ちます。タイムアウト時の自動承認・自動却下・エスカレーションを設定できます。 |

#### 制御フロー・変数系

ステップの実行順序の分岐、繰り返し、並列処理、変数の受け渡しなどを制御します。リトライループ・繰り返し・並列実行は、枠の中に別のステップ（内部のステップ）を組み込んで実行します。内部に置けるステップの種別には、次の制限があります。

- **リトライループ・繰り返し。** コマンド、スクリプト、API 呼び出し、変数設定、通知、クラウド操作、サブ Runbook 呼び出し、条件分岐だけを置けます。
- **並列実行のブランチ。** コマンド、スクリプト、API 呼び出し、通知、待機、条件待機だけを置けます。

| ステップ種別 | 内容・用途 |
|---|---|
| 待機 | 指定した秒数だけ待機してから、次のステップに進みます（最大300秒）。 |
| 変数設定 | Jinja2 の式を評価して、結果を後続のステップで使える変数（`ctx.<変数名>`）として保存・更新します。 |
| 条件分岐 | 設定した条件を上から順に判定して、最初に一致した分岐先のステップに進みます（どの条件にも一致しない場合は、［デフォルト分岐先（全条件不成立時）］を指定していればそのステップへ、未指定なら次のステップへ進みます）。 |
| 条件待機 | 参照先の API 呼び出しのステップを一定の間隔（5〜900秒）でポーリングして、指定した条件に一致するまで待機します（最大24時間）。参照できる API 呼び出しは、GET のものだけです。 |
| リトライループ | 成功条件が一致するまで、指定した一連のステップを、間隔を空けながら繰り返し実行します（最大10回）。ヘルスチェックが OK になるまで、確認と再起動を繰り返す場合などに使います。 |
| 繰り返し | リスト（配列）に含まれるデータごとに、指定した一連のステップを順番に繰り返して実行します（最大100件）。複数台のサーバーに、同じ手順を1台ずつ順番に適用する場合などに使います。 |
| 並列実行 | 複数のブランチ（独立した処理）を同時に実行して、すべて完了してから次のステップに進みます（最大10ブランチ）。既定では、いずれかのブランチが失敗した時点で、ほかのブランチは直ちにキャンセルされます（フェイルファスト）。 |
| サブ Runbook 呼び出し | 作成済みの別の有効な Runbook を呼び出して、実行します。共通の手順を部品にして再利用する場合に適しています。 |

### ステップ間での出力・変数の利用方法

前のステップで得られた実行結果や、あらかじめ設定した変数は、後続のステップのメッセージ本文、条件式などの入力欄に差し込んで、動的に利用できます。

各ステップの実行結果は `steps.<ステップ名>.<項目名>` という形式で、それまでに設定した変数は `ctx.<変数名>` という形式で、後続のステップから呼び出して利用できます。この2つは性質が異なります。

- **ステップの出力（`steps.*`）。** 一度記録されると、値は保持され、後から上書きされることはありません。ただし、失敗時のジャンプで、そのステップに戻って再実行する場合は、前回の出力が破棄されて、新しい結果が記録されます。
  - 通知の本文では、`{{ steps.check_process.stdout }}` のように記述します。
  - 条件分岐では、`steps.check_db.exit_code == 0` のように記述します。
- **変数（`ctx.*`）。** 「変数設定」のステップを複数回実行することで、同じ名前の変数に新しい値を代入して、繰り返し上書き・更新できます。
  - リトライの条件では、`ctx.retry_count < 3` のように記述します。

#### 制御フローのステップでの出力・変数の引き継ぎのルール

枠の中に内部のステップを持つ制御フローのステップでは、内部のステップの実行結果や変数を、後続のステップから利用できるかどうかが、種別ごとに異なります。

- **繰り返し。** 処理中のデータには、`{item}`（現在のデータの値）や `{index}`（0から始まる位置）を使ってアクセスします。`{item}` の値をコマンドやスクリプトで使う場合、値に使える文字は、英数字と _ - . / : = + @ , のみです（空白は使えません）。これ以外の文字が含まれると、ステップは失敗します。クラウド操作、通知、サブ Runbook 呼び出しのパラメータで使う場合は、値に波括弧を含められません。API 呼び出しのパラメータで使う場合は、値に改行を含められません。いずれも該当するとステップは失敗します。内部のステップの実行結果と、内部で設定した変数（`ctx.*`）は、いずれも周回ごとに破棄されます。繰り返しが完了した後のステップからも、次の周回からも利用できません（最後の周回の結果も保持されません）。
- **リトライループ。** 再試行が成功した場合は、成功した回の内部のステップの実行結果と、内部で設定した変数（`ctx.*`）だけが、後続のステップに引き継がれます。
- **並列実行。** すべてのブランチが正常に完了した場合は、各ブランチの内部のステップの実行結果（`steps.*`）が、まとめて後続のステップに引き継がれます。並列実行のブランチの中では、変数を設定できません。
- **サブ Runbook 呼び出し（同期実行の場合）。** 呼び出し先の Runbook の中で設定された変数は、呼び出し元のステップ自身の実行結果として、まとめて引き継がれます。ただし、呼び出し元では、`execution_mode` という名前の値がシステムの予約名として定義されているため、呼び出し先で同じ `execution_mode` という名前の変数を出力している場合は、予約名の値によって上書きされます。

## Runbook の詳細画面の構成と見方

作成・保存した Runbook の詳細画面では、定義した内容の確認・編集のほか、運用の実績のメトリクス、連携先、過去の実行履歴を確認できます。

### 画面上部の操作

詳細画面の上部から、次の操作を行えます。

- **実行。** 有効な Runbook を、その場で実行します。［実行］をクリックすると確認のダイアログが開きます。［テスト実行］が既定でオンになっているため、本番で実行する場合は、チェックを外して実行します。テスト実行では、原則として実際の環境に変更を加えません（例外は、後述の制限事項にあるテスト実行の項目を参照してください）。
- **編集。** 設定内容やステップの編集画面を開きます。
- **複製。** 既存の Runbook をもとにして、新しい下書きの Runbook を作成します。
- **有効・無効の切り替え。** タイトルの横にあるスイッチで、ステータスを［有効］と［無効］で切り替えます。
- **削除。** 不要になった Runbook を、プロジェクトから削除します。［その他の操作］のメニューにあります。有効な Runbook は削除できないため、先に無効にしてください。
- **下書きに戻す。** 無効の Runbook を、下書きに戻します。［その他の操作］のメニューにあります。
- **実行権限。** クラウド操作を含む Runbook について、ワーカーの実行を許可するかどうかを設定します（［WORKER の実行を許可］）。

### 各セクションの表示内容

| セクション | 表示内容 |
|---|---|
| 基本情報 | 説明、タグ、更新日時、目安・最大の実行時間に加えて、完了した実行の回数と成功率が表示されます（集計の対象は、一覧画面と同じです）。 |
| 関連 | この Runbook が割り当てられているインシデントポリシーや、提案のツールとして登録されている AI エージェント（組み込み・カスタム）が、一覧で表示されます。 |
| ナレッジ | Markdown で記述された、運用の手順、トラブルシューティングの情報、調査用のクエリなどが表示されます。 |
| ステップ | 登録されているすべてのステップが、カードの形式で展開されます。コードの内容、接続先、実行制御のパラメータ（タイムアウト、リトライ、失敗時の動作）を確認できます。 |
| 実行履歴 | 過去の実行履歴が、新しい順に一覧で表示されます。各ログから、ステップごとの実行結果や、標準出力（ログ）の詳細を確認できます。 |

## 実行の管理とトラブルシューティング

Runbook の実行のステータスやステップの進捗は、Runbook の詳細画面の「実行履歴」、または実行履歴で実行を選択して開く「実行詳細」で、リアルタイムに確認できます。「実行詳細」には、［ステップ・ログ］と［フロー図］の2つのタブがあります。実行履歴の［実行モード］の列には、テスト実行が［ドライラン］、本番の実行が［本番］と表示されます（実行のダイアログの［テスト実行］と、同じものを指します）。一時停止などの異常が起きたときは、画面上から手動の操作で、リカバリーできます。

### 実行全体のステータス

Runbook の実行全体は、次のステータスを遷移します。

| ステータス | 内容・説明 |
|---|---|
| 実行中 | 実行が始まった直後の状態です。ステップを順番に処理しています。 |
| 一時停止 | ステップが失敗して（失敗時の動作が［停止］の場合など）、承認が否認されて、または承認のタイムアウトで自動的に却下されて、ユーザーの介入（手動のリトライやスキップ）を待って一時停止している状態です。 |
| 承認待ち | 承認のステップで、指定された承認者の承認・否認の判断を待っている状態です。 |
| 完了 | すべてのステップが正常に完了した状態です。 |
| 失敗 | 次のいずれかで終了した状態です。ステップの失敗による一時停止が一定時間続いた場合と、最大実行時間を超えた場合は、自動的に失敗になります（自動失効）。 |
| キャンセル処理中… | 中断の操作を受け付けて、実行中のコマンド、スクリプト、API 呼び出しを止めている状態です。これらのステップが実行中でない場合は、この状態を経ずに、すぐに「中断」になります。一覧画面の最新実行のバッジでは、［進行中］として表示されます。 |
| 中断 | ユーザーの中断の操作によって、実行の終了が確定した状態です。並列実行のフェイルファストで、ほかのブランチが取り消された場合など、システムによって確定することもあります。 |

### 各ステップの実行ステータス

実行全体の状態とは別に、個々のステップ単位でも、次の状態を持ちます。「実行詳細」では、ステップの状態は主にアイコンと色で表示され、ステップの行に「完了」「失敗」のような専用の状態ラベルはありません。次の表は、状態の意味を説明するものであり、画面上のラベル名ではありません。

| ステータス | 内容・説明 |
|---|---|
| 待機中 | 前のステップが完了しておらず、まだ実行が始まっていない状態です。 |
| 実行中 | 現在、そのステップの処理を実行している状態です。 |
| 完了 | そのステップの処理が正常に完了した状態です。 |
| 失敗 | エラーが発生して、処理が失敗した状態です。 |
| スキップ | 実行されずに通過した状態です。実行全体が中断された場合、その時点で完了していないステップ（承認待ち・子の実行待ち、実行中のクラウド操作や通知を含みます）は、コマンド、スクリプト、API 呼び出しの実行中のものを除き、この状態として記録されます。すでに失敗・完了・スキップしたステップは、そのままです。 |
| 承認待ち | 承認者の承認・否認の判断を待っている状態です。 |
| 子の実行待ち | 並列実行やサブ Runbook 呼び出しなどで、子の実行の完了を待っている状態です。この間も、実行全体の状態は「実行中」のままです。 |
| 中断 | 実行の中断によって、コマンド、スクリプト、API 呼び出しの実行が中断された状態です。 |

### 手動でのリカバリー操作（手動リトライ・手動スキップ）

実行が一時停止または承認待ちで止まっている場合、原因になっている個別のステップを、ユーザーが手動でリトライまたはスキップして、処理を再開できます。

これは、ステップ設定の自動リトライや失敗時の自動スキップとは異なり、運用者が画面上から個別に行う手動の操作です。

- **手動リトライ（ステップ行の［リトライ］ボタン）。** 承認が否認された承認ステップでは、ボタンの名前は［再度承認を求める］になります。実行全体が「一時停止」で、対象のステップが「失敗」の状態のときに実行できます。対象のステップは「待機中」に戻り、実行全体は「実行中」に戻って処理が再開されます（リトライ回数のカウントは加算されます）。
- **手動スキップ（ステップ行の［スキップ］ボタン）。** 実行全体が「一時停止」または「承認待ち」で、対象のステップが「失敗」または「承認待ち」の状態のときに実行できます。対象のステップは「スキップ」の状態になり、実行全体は「実行中」に戻って、後続のステップに処理が進みます。
- **実行の中断（［実行を中断］ボタン）。** 対応の継続が難しい場合に、実行全体を「中断」として安全に終了します。確認のダイアログで［中断する］をクリックします。中断しても、すでに実行されたステップの結果（コマンド実行や API 呼び出しなどの副作用）は、取り消されません。

### 自動的に失敗（失効）する条件

次のいずれかに該当した場合、実行中の Runbook は、ユーザーの介入を待たずに、自動的に「失敗」の状態になって終了します。

- **一時停止の状態が、一定時間以上続いた場合。** 一時停止のまま放置された場合の安全装置として、ステップの失敗による一時停止に適用されます。承認の否認や、承認のタイムアウトによる自動却下で一時停止した場合には適用されないため、手動のリトライ・スキップ・中断が必要です。
- **実行全体の制限時間（最大実行時間）を超えた場合。** ［基本情報］で最大実行時間があらかじめ設定されている場合にのみ適用されます（未設定の場合は、実行全体のタイムアウトは発生せず、無制限です）。

なお、インシデント・Tasks・サブ Runbook の呼び出しから自動で起動された実行の承認ステップで、タイムアウトが設定されていない場合は、60分の既定のタイムアウトが適用されます（AI エージェントの提案による起動と、手動実行には、この既定値はありません）。承認のタイムアウトになると、既定では自動的に却下され、実行は一時停止の状態になります。

## ロールと権限

Runbooks の各操作には、プロジェクトのロールの権限が必要です。

| 操作 | 必要なロール |
|---|---|
| 閲覧・一覧の確認・履歴の確認 | プロジェクト管理者 / 編集者 / ワーカー / 閲覧者（プロジェクトのメンバー全員） |
| 手動実行・テスト実行 | プロジェクト管理者 / 編集者 / ワーカー（クラウド操作を含む Runbook は、ワーカーの実行を許可した場合のみ） |
| 実行の中断 | プロジェクト管理者 / 編集者 / ワーカー |
| ステップの手動リトライ・手動スキップ | プロジェクト管理者 / 編集者 / ワーカー（クラウド操作を含む Runbook は、ワーカーの実行を許可した場合のみ） |
| 無効化・下書きに戻す | プロジェクト管理者 / 編集者 / ワーカー |
| 作成・編集・有効化・複製・削除 | プロジェクト管理者 / 編集者 |
| ステップの承認・否認 | プロジェクト管理者 / 編集者（かつ、そのステップで指定された承認者） |
| ワーカーへの実行権限の付与 | プロジェクト管理者 / 編集者（手動承認された Access に到達する Runbook は、プロジェクト管理者のみ） |

※手動承認で有効化された Access を参照するステップを持つ Runbook では、ステップの追加・変更と複製は、プロジェクト管理者のみが行えます。有効化も、サブ Runbook 経由で参照する場合を含めて、プロジェクト管理者のみです。

※テスト実行では、既定で、指定された承認者でなくても、プロジェクト管理者 / 編集者であれば承認・否認できます（詳細は、後述の制限事項を参照してください）。

※手動で実行した本人であっても、承認者として指定されていれば、その実行の承認のステップを承認・否認できます。承認した人と実行した人は、記録されます。

※ワーカーに実行を許可できるのは、クラウド操作を含む Runbook（サブ Runbook 経由を含みます）だけです。クラウド操作を含まない Runbook は、追加の設定なしで、ワーカーも実行できます。

※手動承認で有効化された Access に到達する Runbook（サブ Runbook 経由を含みます）で［WORKER の実行を許可］をオンにできるのは、プロジェクト管理者のみです。オフにする操作は、常に可能です。

※定義の変更によって、クラウド操作を含むかどうか、または呼び出すサブ Runbook の組み合わせが変わった場合、ワーカーの実行権限は自動的に取り消されます。

詳細は、[ロールと権限](/getting-started/roles-and-permissions/)を参照してください。

## 上限値と暴走防止の制約

Runbook の作成と実行では、リソースの過度な消費や無限ループを防ぐため、次の制約が適用されます。

### 入力の上限

| 項目 | 上限 | 補足 |
|---|---|---|
| Runbook 名 | 最大255文字 | Runbook の識別名 |
| 説明 | 最大4,000文字 | 目的、対象の環境、発動条件など |
| ナレッジ欄 | 最大20,000文字 | Markdown 形式の手順・メモ |
| タグ | 最大50個 | 分類・検索用（1つのタグは64文字以内） |
| ステップ数 | 最大100件 | 1つの Runbook に配置できるステップの数 |

### 制御フロー・実行制御の上限（暴走の防止）

| 項目（制御フロー） | 上限・制約 | 補足 |
|---|---|---|
| リトライループ | 最大10回（内部のステップの総実行回数は最大200回） | 成功条件が成立するまでの最大の試行回数 |
| 繰り返し | 最大100件（最大の繰り返し回数 ×（内部の各ステップの（1 + リトライ回数）の合計）≦ 200） | リストのデータの最大の処理件数。内部のステップの総実行回数にも上限があります |
| 並列実行 | 最大10ブランチ（全ブランチの内部のステップの総実行回数は最大200回） | 1つの並列実行に定義できるブランチの数 |
| サブ Runbook 呼び出し | ネストは最大3階層まで。1つの実行（その子の実行を含みます）から累積して生成できるサブ Runbook の子の実行は、合計50件まで。並列実行のブランチを含む子の実行の総数は、200件まで | 循環した呼び出しは、自動で検知して防止します |
| 指定ステップへのジャンプ（ステップの再訪） | ステップごとに10回まで | ステップごとに開始できる回数の合計（最初の実行と手動リトライも含みます）の上限で、失敗時の［分岐先へ移動］によるループを止めるためのものです。画面からは変更できません |
| 条件分岐の移動先 | 後ろのステップのみ | 条件分岐は、前のステップには戻れません（デフォルト分岐先も同様です） |
| クラウド操作の実行頻度 | 同じ AWS アカウントあたり、一度に30回まで。以降は60秒あたり30回のペースで回復します | 上限を超えたステップは失敗し、自動では再試行されません。しばらく待つと、再び実行できます |
| 条件待機（総ポーリング回数） | 最大5,000回（最大待機時間は24時間） | 完了を待つ最大のポーリング回数 |
| ステップのタイムアウト | 1〜300秒（コマンド・スクリプトは30〜300秒） | ステップ単位の最大実行時間 |
| 推定の合計実行時間 | 最大24時間 | リトライループ・繰り返し・並列実行・待機の推定の最大時間の合計が24時間を超える定義は、保存できません（並列実行のブランチの外にある待機は、待機秒数 × ジャンプの上限回数として計算されます。それ以外のステップ種別は、合計に含まれません） |

### タイムアウトの制約

- **ステップ単位のタイムアウト。** コマンド、スクリプト、API 呼び出し、クラウド操作のステップで指定できます。範囲は1〜300秒（最大5分）で、コマンドとスクリプトは、安全に処理を完了させるため30〜300秒です。
- **制御フローのステップのタイムアウト。** リトライループ・繰り返し・並列実行・条件待機・サブ Runbook 呼び出しのステップは、ステップ単位の1〜300秒のタイムアウト欄を使いません。それぞれのステップ種別ごとに、専用の時間・回数の設定（ポーリングの最大待機時間やループ回数など）を持っています。

## 制限事項

Runbooks を設計・運用するうえで、あらかじめご理解いただきたい仕様と制限事項です。

- **コマンドとスクリプトの対象。** Amazon EC2 インスタンス（SSM Agent インストール済み）だけを指定できます。オンプレミスのサーバーや ECS のコンテナは、対象に指定できません。
- **実行の中断と接続先のインスタンス側の動作。** 実行を中断したとき、コマンド、スクリプト、API 呼び出しのステップが実行中の場合は、実行は「キャンセル処理中…」を経て「中断」になります。実行中のものがない場合は、すぐに「中断」になります。コマンド、スクリプト、API 呼び出しが実行中だったステップは「中断」として記録され、それ以外の完了していないステップ（承認待ち・子の実行待ちのステップ、実行中のクラウド操作や通知のステップなどを含みます）は「スキップ」として記録されます。すでに失敗・完了・スキップしたステップは、そのままです。接続先のインスタンスで、すでに開始された処理は、完了まで進むことがありますが、その結果は Runbook のログには反映されません。また、中断より前に実行済みのステップの結果（コマンド実行や API 呼び出しなどの副作用）は、取り消されません。
- **クラウド操作におけるセキュリティ・機密情報の制限。** セキュリティを保護するため、クラウド側のアカウントの権限に関わらず、次のような操作は一律に制限されています。
  - シークレット管理サービス（AWS Secrets Manager など）からの、シークレットの直接取得
  - 一時的な認証情報（AWS STS など）の発行
  - IAM アクセスキーの新規作成や、ログイン情報の変更
  - 暗号化されたパラメータ（AWS Systems Manager Parameter Store の SecureString など）の復号による取得（暗号化されていないパラメータの取得は可能です）
  - 署名付き URL の生成など、クライアント側のライブラリに依存する補助機能の実行
- **クラウド操作の対象の範囲。** ［許可操作のみ実行可］のタグが付いた Access では、選択した操作の範囲内でのみ実行できます。手動承認された Access（［任意実行可］のタグが付いたもの）には、選択した範囲による制限はありません。ステップで宣言するアクション（「宣言が必要な操作」「宣言済みのアクション」）が使えるのは、手動承認された Access だけです。宣言しても、［許可操作のみ実行可］の Access の制限は解除されません。
  - IAM、STS、Organizations、Account、請求関連のサービス（Billing など）の操作と、delete、terminate、create、run で始まる操作は、既定で拒否されます。ステップで宣言すると、手動承認された Access では実行できます。ただし、上記の一律に制限される操作は、宣言しても実行できません。
  - STS の操作は、宣言できません。常に実行できません。
  - 1つのステップで宣言できるアクションは、最大16件で、サービスの種類は最大12種類までです。
- **外部 API 呼び出しの通信の制限。** 安全な通信を確保するため、暗号化されていない HTTP や、プライベート IP アドレスなどの内部ネットワーク宛ての URL は、呼び出せません（HTTPS の通信のみに対応しています）。
- **変数の参照を展開できないステップ。** コマンドとスクリプトのパラメータでは、変数の参照（`{{ ... }}`）は展開されず、書いたとおりの文字列として扱われます。変数の参照は、通知の本文、クラウド操作の引数、サブ Runbook の入力のマッピング、条件式で利用できます。
- **繰り返しの内部のステップの出力と変数。** 繰り返しのステップの中で実行した各ステップの出力値と、内部で設定した変数（`ctx.*`）は、処理が完了した後のステップや、次の周回からは利用できません（最後の周回の結果も保持されません）。
- **並列実行での変数の設定と同時に実行するブランチの数。**
  - 変数の競合を防ぐため、並列実行のブランチの中には、「変数設定」のステップを配置できません。
  - 並列実行のブランチの数は、定義できる最大の数です。システムの負荷の状況などによって、実際に同時に動くブランチの数は、前後する場合があります。
- **条件待機での API の実行のタイミング。** 条件待機のステップが参照している「API 呼び出し」のステップは、通常の実行フローの中で1回実行されたうえで、条件待機のポーリングのたびに、さらに実行されます。参照できる API 呼び出しは GET のものだけで、ポーリングの間隔は5〜900秒です。
- **サブ Runbook の非同期の呼び出し。** サブ Runbook を［非同期（待たない）］で呼び出した場合、呼び出し先（子）の Runbook が後から失敗しても、呼び出し元（親）の実行ステータスには影響しません。
- **サブ Runbook の子の実行の時間。** 同期で呼び出したサブ Runbook の待ち時間は、呼び出し元（親）の最大実行時間に含まれます。サブ Runbook から起動された実行には、子の Runbook に設定した最大実行時間は適用されません。
- **テスト実行でのステップ種別ごとの動作。** テスト実行では、原則として実際の環境に変更を加えません。ステップ種別ごとの扱いは、次のとおりです。
  - **コマンド、スクリプト、クラウド操作。** コマンドとスクリプトは実行されませんが、接続先のインスタンスへの読み取り専用の到達確認は実際に行われ、失敗するとテスト実行も失敗します。クラウド操作は何も送信されず、シミュレーション（モックの動作）になります。
  - **通知。** 画面で新しく追加したステップは、既定ではテスト実行で送信されません。［テスト実行でも実際に通知する］をオンにすると、送信されます。［通知する］のスイッチがオフで配信しない設定のステップは、常に送信されません。
  - **待機。** 既定ではテスト実行でも実際に待機します（ステップの設定で、待機を省略できます）。
  - **API 呼び出し。** 既定ではテスト実行でスキップされます。［テスト実行でも実際にリクエストを送信する］をオンにすると、送信されます。
  - **承認。** テスト実行でも、実際の承認を待ちます。既定では、指定された承認者でなくても、プロジェクト管理者 / 編集者であれば、承認・否認できます。ステップの［テスト実行でも承認者を限定する］をオンにすると、指定した承認者だけに限定されます。

## 関連機能

- [Rules の概要](/guides/rules/)（インシデントの検知と、Runbook を自動起動するインシデントポリシー）
- [AI Agents の概要](/guides/ai-agents/)（インシデントの分析の結果として提案された Runbook の承認）
- [Incidents / Tasks の概要](/guides/incidents-and-tasks/)（タスクへの Runbook の紐付けと、実行状況の確認）
- [Integration の概要](/guides/integration/)（クラウド操作で利用する Access）
- [ロールと権限](/getting-started/roles-and-permissions/)（プロジェクト管理者・編集者・ワーカー・閲覧者の権限の詳細）
- [取得データの取り扱い](/specifications/data-handling/)（Runbook の実行履歴の保存期間は、全プラン共通で90日間）