前の章で、フィルタリングされたノードセットに横断的にアドホックコマンドを実行する方法を学びました。 この章では Rundeck の基本機能である ジョブ 機能を紹介します。 しかしその前に、アドホックコマンド実行機構の上に別のレイヤを導入する理由が気になると思います。

時間の経過と共に発生する可能性のある問題がいくつかあります：

• ひとつは、アドホックコマンドは繰り返し実行されること。そしてたぶんそれがルーチンワークになること。
• あなたのチームの人は、ノードセットに向けて1人でプロシージャを実行できるシンプルなインターフェースが必要なこと。
• ルーチンプロシージャを他のルーチンプロシージャの要素とするために、カプセル化する必要があること。

ジョブ機能はプロシージャを論理的にカプセル化して ジョブ と名付けます。 ジョブはプロシージャ内のステップ、ノードフィルタ、実行時の制御パラメータの設定です。 ジョブへのアクセスは、どのユーザがどのジョブをどう使うかを許可するか、という形式で記述されている ACL ポリシーで制御されます。

Rundeck はジョブの構築と実行、動作状況の確認をおこなえます。 現在実行中のジョブリストでは実行状況を動的に確認できます。 必要な時に停止することも可能です。

ジョブには、いつ実行されたかのログがひも付いており、その時のアウトプットを閲覧可能です。

次の章では既存ジョブの導入と実行について説明します。 最終的にはジョブ作成全般をカバーします。

もし先に進みたければ、ジョブ作成の部分へ進んで下さい。

ジョブグループ

ジョブがたまってきたときは、ジョブをグループ化するのが有効です。 グループはジョブの論理的なまとまりで、さらに他のジョブグループの中に入れ子にすることもできます。 Rundeck はジョブに定義されたグループ構造をフォルダにしてジョブリストを表示します。

ジョブを構造化してグループにすると、アクセスコントロールポリシーを定義しやすくなります。 これについては認証の章で説明します。

ジョブ UUID

作成されたジョブにはユニークな UUID が付与されます。 対応するフォーマットをつかってジョブ定義をかけば、自分自身で UUID を付与することも可能です。

UUID は、ジョブのリネームやジョブグループの変更を確かめるために使えます。 適切にジョブを編集できるでしょう。

UUID は Rundeck 間でジョブ定義を移植するときにも便利です。

注記：Rundeck は各ジョブに内部的な "ID" を付与していますが、これは Rundeck 間で移植できません。 Rundeck 1.3 以上では UUID を ID の代わりに利用するようになっています。

ジョブリストとフィルタリング

ジョブ操作は全て Rundeck の "Jobs" ページから開始します。 ログインしたら、ナビゲーションバーのトップにある "Jobs" ボタンをおせば、あなたの権限で見られるジョブの一覧が表示されます。

もしジョブがグループ内に定義されていれば、フォルダライクな構造でグループ化されて表示されます。 フォルダは先述したジョブグループを表しています。 フォルダアイコンを押すことでその内部をたどっていくことができます。

ジョブにたどりつくと、その名前、詳細、何回起動されたかのサマリが表示されるでしょう。

ジョブ名をクリックすると、ウィンドウが開かれて、より詳細な情報が表示されます。 あなたが操作可能なアイコンが並んだバーも表示されるでしょう。 他に、実行時に走るコマンドやフィルタ定義、ディスパッチオプションもあるはずです。

ジョブのフィルタリング

ジョブページではフィルタをかけてジョブを検索できます。

"Filter" リンクを押下すればフィルタオプションが表示されます:

フィルタフィールドが出てくるので必要な箇所を入力して下さい:

• Job Name: ジョブ名
• Group: ジョブグループ名
• Description: 説明文

部分文字列か正規表現を利用できます。

"Filter" ボタンを押すと、ジョブリストはフィルタ条件にマッチしたリストになるでしょう。

フィルタを変更するには、青く囲われたフィルタ定義をクリックして再入力して下さい。

フィルタをリセットするには全ジョブのページに、もどってフィルタフィールドにある "Clear" ボタンを押して下さい。

ジョブ詳細の確認

ジョブ一覧をフィルタリングしてから、ジョブ名にマウスポインタを合わせるとジョブ詳細をポップアップで確認することができます。 ポップアップの外をクリックすれば消えます。

ジョブ名のリンクをクリックすると、ジョブ詳細とコントロールバーがあるページに遷移します。 バーにはジョブの削除・コピー・編集・エクスポート・実行に対応するボタンが表示されます。

表示されるボタンは 権限の付与 でユーザに設定した内容に対応します。

ジョブ詳細ページには、以下の情報が含まれます:

• 名前・説明・グループ
• ジョブを最後に実行したときの統計（平均成功率や遅延など）
• プロジェクト名とワークフローステップ、ログレベルを含む詳細

"Show Matches" リンクからジョブ実行予定のノード一覧を見ることが出来ます。

ジョブの実行

ジョブはシェルか GUI から実行できます。

コマンドラインからの場合、run というシェルツールを利用します。 たとえば "myproject" プロジェクトの "apps/web" ジョブグループに属する "restart" というジョブがあると仮定すればこのようなかんじです。

$ run -j apps/web/restart -p myproject
Job execution started:
[51] restart <http://strongbad:4440/execution/follow/51>

GUI からの場合、ジョブページからさまざまなジョブを実行できます。 フィルタリングで目的のジョブを探し出し、緑色の "Run" アイコンを押せば、 ただちにキューにジョブが入って実行されます。 Run アイコンがない場合はログインしていないか、あなたに "run" 権限がないということです。

ジョブ詳細ページにたどり着いたら、ここから "Run" ボタンをおせます。

Run ボタンが押されると、ダイアログが開いて実行オプションを選択できます。

実行オプションの選択

ジョブにはオプション入力用のプロンプトを定義することができます。 このページではジョブの様々なオプションを紹介します。

いくつかのオプションはデフォルト値をもち、その他については選択肢が表示されます。 また、いくつかのオプションの入力は任意であり、他は必須になります。 最終的に、受け入れ可能な値を管理し、その中から選択させるパターンになるでしょう。

いろいろなジョブオプションがあっても、ジョブが実行される前に変更可能です。

準備ができたら "Run Job Now" を押しましょう。 ジョブが実行キューに入って Now running セクションで実行状況を追うことが出来るようになります。

実行中ジョブのフォロー

ジョブ実行を開始したら実行詳細ページでアウトプットをフォローできます。

ジョブページに "Now running" と表示されているとき、ジョブ名の行にある "output >>" リンクをクリックしてください。

もしジョブ詳細ページから "run" ボタンを押していれば、ブラウザは実行詳細ページを表示するでしょう。

ジョブの作成

Rundeck では 2 種類のジョブをつくることができます。

• Temporary : Temporary ジョブ は実行コマンドセットとノードフィルタ設定を定義します。
• Saved: Saved ジョブ は実行コマンドセットとディスパッチオプションを定義しますが、名前をつけることができ、ジョブグループに格納できます。さらに、Saved ジョブは実行スケジュールを持つことが出来ます。

ジョブを作成するには Jobs ページから「New Job」ボタンを押します。

Temporary ジョブ

Temporary ジョブはアドホックコマンドに少しだけ似ています。 違うのは、コマンドの実行方法について、より多くのコントロールが効くということと、Rundeck の Web アプリでよりよいトラッキングができるという点です。

Temporary ジョブをつくるためには、まず Rundeck の画面にログインして "Jobs" タブを押してください。

1. 右のほうにある "New Job" ボタンをおして "Create New Job" フォームを表示させて下さい。
2. ジョブは 1 つ以上のワークフローステップで定義されます。ワークフローエリアで "Add a step" リンクをクリックして下さい。
3. ワークフローステップには数種類のタイプがあります。"Script" ワークフローステップタイプを選択して下さい。
4. "Script" タイプは任意のスクリプトを対象のホストで実行できるタイプです。 ディスパッチを使う前には "info" シェルスクリプトが実行されています。
5. フォームの下まできたら、実行開始するために "Run and Forget" ボタンを押して下さい。
6. 実行結果の出力がサブシーケンスページに表示されていきます。

Saved ジョブ

アドホックコマンドや Temporary ジョブの実行は管理者の日常業務の一部です。 時にはアドホックコマンドがルーチンワーク化し、再利用可能にすることで価値が出るようになるでしょう。 そのようなジョブはチームメンバから引き渡されたり、他のジョブから派生してくるかもしれません。 Rundeck はジョブを宣言して保存するために、グラフィカルもしくは XML ファイルで定義するインタフェースを提供します。

シンブルな Saved ジョブ

Saved ジョブの例として、内部でスクリプトを呼び出すジョブをつくってみます。

1. これまでの例と同じく、"New Job" ボタンをクリックしてください。
2. new job フォーム内で:
   • "Save this job?" プロンプトに対しては "Yes" を選択してください。すると、ジョブの名前とグループ、説明を記入するフォームが出ます。
   • "Job Name" に "info"、"Group" に "adm/resources" を入力します。
   • もし UUID を自分で定義したければ入力することが可能です。入れない場合は自動でセットされます。
   • 説明を記入しておくと他のユーザがそのジョブの意図・目的を理解するのに有用です。
   • "Dispatch to Nodes" にチェックを入れます。
   • "Node Exclude Filters" を選択して、Rundeck Server の名前を入れます。これでリモートノードのみにジョブが実行されるようになります。（たとえば centos54 や ubuntu）
   • info script を入力します
   • ワークフローステップを保存します
   • ページ下部にある "Create" ボタンを押します。
3. ジョブが作成されると、ブラウザが Jobs ページにリダイレクトされます。グループ名のついたフォルダにジョブがあるでしょう。
   • フォルダボタンによって新しいジョブまでいけます
4. 緑色の矢印のボタンがあります
   • ジョブを実行するにはこのボタンを押します
5. "Run Job Now" ボタンを押して実行開始します。
   • ジョブがキューに入って実行されます
6. "Now Running" セクションを見て下さい。
   • "output >>" リンクを押すことで実行フォローページにいけます

並列実行

デフォルトでは saved job は "Single Execution" で1度に1回実行できます。 これは同じノード（群）で動作している他のプロセスにジョブのステップが妨害される可能性があるときに便利です。

しかし、場合によっては同時に1つ以上のジョブを実行した方が便利なことがあります。

以下のようにジョブエディタで "Multiple Executions" を Yes に切り替えることでそれが可能になります。

ノードディスパッチとフィルタリング

ジョブを作るときに、ローカルだけで動かすか（Rundeck Server 上のみ）、複数のノードで動かすか（Rundeck Server を含めることも可能）を選択することができます。

GUI では、"Dispatch to Nodes" のチェックボックスでノードディスパッチを有効にできます。 有効にした場合、ノードフィルタリングインタフェースが表示されます。

フィルタ

フィルタ値を入力するため、"Name" と "Tags" の異なるフィルタフィールドをクリックできます。 条件を更新すると、"Matched Nodes" の欄にそれを反映したリストが表示されます。 より多くの組み込みフィルタを確認するには "More" をクリックします。 また、外部フィルタを同じフィールドに入力するには "Extended Filters" をクリックします。

スレッドカウント

"Thread Count" ボックスを変更することで同時に実行されるスレッドの最大数を設定できます。 1を入れると全てのノードに対して直列で実行されます。 それ以上の値を入れればそれに応じた数で並行に実行されます。

ランクオーダー

"Rank Attribute" と "Rank Order" を設定することでノードの実行オーダーを変更することができます。デフォルトでは、ノードは "nodename" 属性値で昇順オーダーされます。 このノード属性値は、たとえば "rank" のように変更でき、オーダー順は降順にすることで逆転できます。

もし属性値に整数値を利用する場合、ノードはレキシカルではなく数値でソートされるようになります。言い換えれば、ソートは基本的に整数値ではなく文字列で行われます。

特に属性値が入力されていないノードの場合は、その名前がソートの基準となります。

キープゴーイング

"Keep going on error?" を "Yes" に設定すると、ノードへのディスパッチが失敗しても、全てが実行されるまで動作が継続されます。 全てのノードのワークフローが終了したときに、いずれかのノードで失敗していれば実行結果は失敗となります。

"No" に設定すると、残りのジョブの実行は継続されず、直ちに終了します。

ダイナミックノードフィルタ

ノードにマッチする為、静的な値のほかに動的な値を利用することも出来ます。

ジョブ用にオプションを定義してあれば（詳細はジョブオプションを参照）、ジョブ実行時にユーザが送信した値をノードフィルタリングの条件として利用できます。

${option.name} のようにフィルタ値をいれてください。"name" にはオプション名が入ります。

ジョブ実行時、ユーザにはオプション値を入力するプロンプトが表示されますが、それは同時にどのノードにディスパッチするかという条件にも使われるのです。

注：動的オプションは値がまだセットされていない為、フィルタリング結果の "Matched Nodes" の欄でマッチ状況が "None" となるでしょう。 そのため、ジョブ実行時に "Warning: このジョブが指定するフィルタにはノードがマッチしませんでした。実行が失敗する恐れがあります。" とメッセージがでます。 このような場合はユーザがオプション値を入れた後にノードが決定されます。

スケジュール付きジョブ

Saved ジョブは周期的な基準にそって実行されるよう設定できます。 そのようなスケジュールされたジョブをつくりたいのなら、"Schedule to run repeatedly?" の下を Yes にしてください。

スケジュールはシンプルなセレクタから選ぶか Unix Crontab フォーマット形式で定義します。

セレクタを使う場合、時分を決めます。 デフォルトでは "Every Day（毎日）" となっていますが、そのチェックをはずせば個別に一週間のうちの日を指定できます。 同様に "Every Month（毎月）" がデフォルトですがチェックを外せば年のうちの月を指定できます。

もし crontab のフォーマットが好きなら、cron 表現で入力します。

Crontab の文法についてはここを参照して下さい: CronExpresssion

スケジュールを追加してアップデートすると、ジョブがリストに記載されたときに時計アイコンが出てきます。

ジョブ通知

ジョブが終了したときに成否を通知するよう設定できます。

通知を受信したい場合は "Send Notification?" の下を Yes にしてください。

成否の通知を有効にし、email か webhooks で受信することができます。チェックボックスを有効にしたら通知タイプの欄にすすんでください。

email 通知用にはコンマ区切りで email アドレスを入力して下さい。webhook 通知用には同様に URL を入れます。

ジョブ実行が完了すると、ジョブが成功したなら全ての "success" 通知が流れます。逆に、全ての "failure" 通知はジョブが失敗するかキャンセルされると流れます。

Webhooks

Rundeck のジョブは成否を webhook URL に POST するよう設定できます。

• webhook 通知の設定手法については Jobs - Job Notifications を参考にして下さい
• webhook 全般については http://webhooks.pbwiki.com/ を参照して下さい

Rundeck ジョブの webhook 通知が起動されると、サーバは1つ以上の URL に POST リクエストを送信します。 そのリクエストは実行結果情報を含む XML コンテンツを持ち、通知と実行についての情報を含む特別なヘッダを持ちます。 同様に、webhook リクエストが送信される前に、ジョブや実行結果、通知に関する具体的な詳細と取り替えられるプロパティトークンを URL に設定することもできます。

実行通知の内容

POST リクエストの中身は <notification> をルート要素に持つ XML になります。 この要素の中身は <executions..><execution>...</execution></executions> になります。 これは実行情報の Web API が返す XML と同一のフォーマットです。 詳しくは API - Listing Running Executions を参照して下さい。

notification 要素の属性は以下のような者を含みます:

trigger

通知のトリガー種別。成功・失敗（"success" or "failure")

executionId

実行 ID

status

実行結果。成功・失敗・中断（"succeeded", "failed" or "aborted")

Example

<notification trigger="success" executionId="[ID]" status="[STATUS]">
    <executions count="1">
        <execution ...>
            ...
        </execution>
    </executions>
</notification>

実行通知ヘッダー

POST リクエストはいくつかのカスタム HTTP ヘッダも含みます。webhook 情報を受信する別の手段を提供するためです:

X-Rundeck-Notification-Trigger

通知のトリガー種別。成功・失敗（"success" or "failure")

X-Rundeck-Notification-Execution-ID

実行 ID

X-Rundeck-Notification-Execution-Status

実行結果。成功・失敗・中断（"succeeded", "failed" or "aborted")

実行通知 URL トークンの展開

トークンを含んだ　webhook 通知用に URL は構成されます。 トークンは ${job.name} などの関連づけられたジョブとその実行結果から取得した値で展開されます。

展開可能なトークンは:

job.PROPERTY

ジョブに関するプロパティ。以下を含む:

name

ジョブ名

group

ジョブグループもしくは空文字列

id

ジョブ ID

project

プロジェクト名

execution.PROPERTY

実行に関するプロパティ。以下を含む:

id

実行 ID

user

ジョブを実行したユーザ

status

実行結果。成功・失敗・中断（"succeeded", "failed" or "aborted")

notification.trigger

"success", "failure" 通知にひもづくトリガー

たとえば、この URL の場合:

http://server/callback?id=${execution.id}&status=${execution.status}&trigger=${notification.trigger}

トークンは webhook リクエストを作る前に適切な値にリプレースされます。

ジョブの実行履歴

ジョブページでは、"Executions" をクリックすると以前の実行結果を参照することができます。

そのジョブに関連するフィルタされたヒストリが返ってきます。 リスト内にある過去の実行をクリックすれば全ての状況を見ることができます。

ジョブ詳細ページからも、同様に過去の履歴を見ることができます。

ジョブの強制終了

実行中のジョブは、強制終了することができます。

警告：この機能はジョブを実行している Java のスレッドを強制的に kill するので気をつけて下さい。実行すると Rundeck サーバはフレーキー（はぐれ者）になるでしょう。 Java で非推奨となっている機能なので、本当にどうしても必要な時以外は使わないで下さい。

ヒストリビューの Now Running セクションか、ジョブ実行フォローページから、そのジョブの "Kill Job Now" ボタンを押して下さい。

すると、"Really kill this job?（本当にジョブを終了してもいいですか？）" と尋ねられるので "Yes" を押してください。

そのジョブは "Killed" 完了ステータスとして実行を打ち切られます。

参照: rd-queue.

ジョブの削除

ジョブ詳細ページから、赤い "X" アイコンを押すとジョブを削除できます。

"Really delete this job?（本当にジョブを削除してもいいですか？）" と聞かれたら "Yes" を押して下さい。

Updating and copying Jobs

ジョブを作るときにセットしたデータは UUID を除いて変更できます。 ジョブを編集するには、えんぴつアイコンをクリックしてください。

同じく、ジョブ定義を新しいジョブにコピーするときはコピーボタンを押して下さい。

ジョブ定義のエクスポート

Rundeck のグラフィカルコンソールで作成されたジョブ定義は、XML や YAML ファイル形式にエクスポートできます。 また、それをインポートすることもできます。

Rundeck のグラフィカルインタフェースか、rd-jobs シェルツールを通して、既存のジョブ定義を検索することができます。

ジョブ詳細ページ内のツールバーにドキュメントシンボルアイコンがあります。 マウスカーソルをあわせると "Download Job definition file（ジョブ定義ファイルのダウンロード）" とラベルがでます。 アイコンをクリックすると、XML か YAML でのジョブ定義ダウンロードを選べます。

好きなフォーマットをクリックするとダウンロードがはじまります。

コマンドラインを使いたい場合、まず Rundeck サーバでシェルを開いて下さい。 ディスクに書き込むために rd-jobs コマンドを実行します。 デフォルトでは rd-jobs は全てのジョブ定義を1つのファイルにダンプします。 特定のジョブのみに制限したい場合は、-n オプションで名前を指定するか、もしくは -i オプションで ID を指定します。

rd-jobs -p project -n "job-name" -f job.xml

この場合、job.xml に結果が保存されます。

YAML 形式でエクスポートしたい場合は -F オプションを使います。

rd-jobs -p project -n "job-name" -F yaml -f job.yaml

この場合、YAML フォーマットファイルにエクスポートされます。

XML および YAML フォーマットに関しては以下に記述されています。

• XML: job-v20(5)
• YAML: job-yaml-v12(5)

他の使い方については rd-jobs(1) を参照して下さい。

ジョブ定義のインポート

job.xml ファイルは Web インタフェースからそれをアップロードすることができます。

ジョブリスト内から "New Job" ボタンをクリックして下さい。

"Create New Job" フォーム内の右サイドにある "Upload Definition..." というボタンをクリックしてください。

job.xml ファイルを選択してアップロードします。

"同じ名前のジョブが既にあります（When a job with the same name already exists:）" と言われたらオプションを選んで下さい。

• Update - 同じ名前のジョブ定義を上書きしてアップデートします
• Skip - 何もせずに処理をスキップします
• Create - XML 内の情報を新規ジョブ作成用に利用します（同じ名前のジョブへの上書きはされません）

アップロードボタンをクリックして下さい。 もし XML にエラーがあれば、ページ内に表示されます。

まとめ

この章を読んだあとは、あなたはジョブの概要について理解して、検索したり実行できるようになっていなければなりません。 また、Temporary ジョブや saved jobs の作成方法、その履歴検索についても理解していなければなりません。 最終的に、XML 形式でのジョブ定義のエクスポート・インポートについて理解しておくべきです。

次は、Job Workflow を用いたマルチステップの実行について説明します。