Runbooks の概要

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

概要

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

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

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

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

できること

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

Runbook のライフサイクル

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

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

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

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

実行の起点

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

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

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

画面上部の操作エリア

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

一覧テーブルの表示項目

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

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

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

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

Runbook の作成手順

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

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

基本情報（必須）の設定

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

わかりやすい「説明」の書き方（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）。後続のステップから出力を参照するときのキーになります。式の中ではハイフンが引き算として解釈されるため、ハイフンは避けてください。
• 説明（任意）。 このステップで行う処理の内容や目的を入力します。

ステップ共通の実行制御

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

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

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

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

ステップ種別の一覧

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

アクション・連携系

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

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

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

制御フロー・変数系

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

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

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

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

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

実行全体のステータス

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

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

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

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

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

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

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

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

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

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

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

ロールと権限

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

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

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

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

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

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

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

詳細は、ロールと権限を参照してください。

上限値と暴走防止の制約

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

入力の上限

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

タイムアウトの制約

• ステップ単位のタイムアウト。 コマンド、スクリプト、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 の概要（インシデントの検知と、Runbook を自動起動するインシデントポリシー）
• AI Agents の概要（インシデントの分析の結果として提案された Runbook の承認）
• Incidents / Tasks の概要（タスクへの Runbook の紐付けと、実行状況の確認）
• Integration の概要（クラウド操作で利用する Access）
• ロールと権限（プロジェクト管理者・編集者・ワーカー・閲覧者の権限の詳細）
• 取得データの取り扱い（Runbook の実行履歴の保存期間は、全プラン共通で90日間）