Documentation

14. ジョブテンプレート

job template (ジョブテンプレート) は、Ansible ジョブを実行するためのパラメーターの定義およびパラメーターセットです。ジョブテンプレートは同じジョブを何度も実行する場合に便利です。また、ジョブテンプレートは Ansible playbook コンテンツの再利用およびチーム間のコラボレーションを促進します。REST API はジョブの直接の実行を可能にしますが、Tower ではまずジョブテンプレートを作成することが求められます。

このメニューでは、現在利用可能なジョブテンプレートの一覧が表示されます。ジョブテンプレートの一覧は 名前 または 説明 で並べ替え、検索できます。テンプレート タブから、ユーザーはジョブテンプレートを起動し、スケジュールし、変更し、削除できます。

Job templates - home with example job template

14.1. ジョブテンプレートの作成

新規ジョブテンプレートを作成するには、以下を実行します。

  1. add ボタンをクリックしてから、メニュー一覧で ジョブテンプレート を選択します。

Job templates - create new job template

  1. 以下のフィールドに該当する詳細を入力します。
  • 名前: ジョブの名前を入力します。

  • 説明: 任意の説明を入力します (オプション)。

  • ジョブタイプ:

    • 実行: 起動時に Playbook を実行し、選択されたホストで Ansible タスクを実行します。
    • チェック: Playbook の「ドライラン」を実行し、実際に変更せずに変更について報告します。チェックモードをサポートしないタスクはスキップされ、予想される変更については報告されません。
    • 起動プロンプト: これが選択されている場合、デフォルト値が指定されている場合でも、起動時に実行またはチェックするジョブタイプを選択するようプロンプトが出されます。

    注釈

    ジョブタイプの詳細は、Ansible ドキュメントの Playbooks: Special Topics <http://docs.ansible.com/playbooks_special_topics.html> __セクションを参照してください。

  • インベントリー: このジョブテンプレートで使用するインベントリーを、現在ログインしている Tower ユーザーが利用できるインベントリーから選択します。

  • 起動プロンプト: これが選択されている場合、デフォルト値が指定されている場合でも、起動時にこのジョブテンプレート実行に使用するインベントリーの選択を求めるプロンプトが出されます。

  • プロジェクト: このジョブテンプレートで使用するプロジェクトを、現在ログインしている Tower ユーザーが利用できるプロジェクトから選択します。

  • Playbook: このジョブテンプレートで起動する Playbook を、利用可能な Playbook から選択します。このメニューには、選択したプロジェクトのプロジェクトベースパスにある Playbook の名前が自動的に設定されます。たとえば、プロジェクトパスにある「jboss.yml」という名前の Playbook は「jboss」としてメニューに表示されます。

  • 認証情報: search ボタンをクリックして別個のウィンドウを開きます。このジョブテンプレートで使用する選択可能なオプションから認証情報を選択します。一覧に多くのオプションが含まれる場合、ドロップダウンメニューの一覧を使用し、認証情報タイプでフィルターします。

_images/job-templates-credentials-selection-box.png
  • フォーク: Playbook の実行中に使用する並行または同時プロセスの数です。値がゼロの場合、/etc/ansible/ansible.cfg で上書きが実行されない限り Ansible のデフォルト設定 (5 つの並行プロセス) が使用されます。

  • 制限:

    • Playbook が管理または影響を与えるホストの一覧をさらに制限するためのホストのパターンです。複数のパターンは、コロン (「:」) で区切ることができます。Core Ansible の場合のように「a:b」は「in group a or b」を、「a:b:&c」は「in a or b but must be in c」を、「a:!b」は「in a, and definitely not in b」を意味します。
    • 起動プロンプト: これが選択されている場合、デフォルト値が指定されている場合でも、起動時に制限を選択するようプロンプトが出されます。

    注釈

    詳細および例については、Ansible ドキュメントの Patterns <http://docs.ansible.com/intro_patterns.html> __を参照してください。

  • 詳細: Playbook の実行時に Ansible が生成する出力レベルを制御します。詳細を「デフォルト」、「詳細」または「デバッグ」のいずれかに設定します。これは、「詳細」レポートビューにのみ表示されます。詳細ロギングには、すべてのコマンドの出力が含まれます。デバッグのロギングはきわめて詳細になり、特定のサポートインスタンスで役に立つ SSH 操作についての情報が含まれます。大半のユーザーは「デバッグ」モードの出力を確認する必要はありません。

    警告

    「詳細」の値が 5 の場合、Tower はジョブの実行時にブロックを実行し、これによりジョブが終了したことを示すレポートが遅延するため (レポートが作成されている場合でも)、ブラウザータブがロックアップする可能性があります。

  • インスタンスグループ: search ボタンをクリックして別個のウィンドウを開きます。このジョブ テンプレートの実行に使用するインスタンスグループを選択します。一覧に多くのオプションが含まれる場合、検索を使用してオプションの範囲を絞ります。

  • ジョブタグ:

    • Playbook タグのコンマ区切りの一覧を提供し、実行する Playbook の部分を指定します。
    • 詳細および例については、Ansible ドキュメントの Tags を参照してください。
    • 起動プロンプト: これが選択されている場合、デフォルト値が指定されている場合でも、起動時にジョブタグを選択するようプロンプトが出されます。
  • スキップタグ:

    • Playbook タグのコンマ区切りの一覧を提供し、特定のタスクまたは実行する Playbook の一部をスキップします。
    • 詳細および例については、Ansible ドキュメントの Tags を参照してください。
    • 起動プロンプト: これが選択されている場合、デフォルト値が指定されている場合でも、起動時にジョブタグを選択するようプロンプトが出されます。
  • 変更の表示: Ansible タスクで加えられた変更を表示できます。

  • オプション

    • 権限昇格の有効化: 有効にされている場合、Playbook を管理者として実行します。これは、--become オプションを ansible-playbook コマンドに渡すことに相当します。
    • プロビジョニングコールバックの許可: ホストが Tower API 経由で Tower に対してコールバックできるようにし、このジョブテンプレートからジョブを起動できるようにします。詳細は、プロビジョニングコールバック を参照してください。
    • 同時実行ジョブの有効化: キューにあるジョブが、相互に依存していない場合に同時に実行できるようにします。詳細は、ジョブの同時実行 を参照してください。
    • ファクトのキャッシュの使用: 有効にされている場合、Tower は、ジョブの実行に関連するインベントリーのすべてのホストに対して Ansible ファクトのキャッシュプラグインを有効にします。
  • ラベル: 「dev」または「test」などのこのジョブテンプレートを説明するオプションのラベルを指定します。ラベルを使用して Tower のディスプレイでのジョブテンプレートおよび完了したジョブの分類およびフィルターを実行します。

    • ラベルは、ジョブテンプレートに追加される際に作成されます。ラベルはジョブテンプレートで提供されるプロジェクトを使用する単一の組織に割り当てられます。組織のメンバーは、(管理者ロールなどの) 編集パーミッションがある場合にジョブテンプレートでラベルを作成できます。
    • ジョブテンプレートが保存されると、ラベルはジョブテンプレートの概要に表示されます。
    • ラベルの横にある「x」をクリックしてこれを削除します。ラベルが削除され、ジョブまたはジョブテンプレートの関連付けが解除されると、ラベルは組織ラベルの一覧から永久に削除されます。
    • ジョブは起動時にジョブテンプレートからラベルを継承します。ラベルがジョブテンプレートから削除される場合、ジョブからも削除されます。
_images/job-template-create-labels.png _images/job-template-saved-labels.png
  • 追加変数:

    • 追加のコマンドライン変数を Playbook に渡します。これは、Ansible ドキュメントの Passing Variables on the Command Line <http://docs.ansible.com/playbooks_variables.html#passing-variables-on-the-command-line> __に記載されている ansible-playbook の「-e」または「–extra-vars」コマンドラインパラメーターです。

    • YAML または JSON のいずれかを使用してキー/値のペアを指定します。これらの変数には、順序を示す最大値があり、他の場所で指定された他の変数を上書きします。値の例には、以下が含まれます。

      git_branch: production
      release_version: 1.5
      
    • 起動プロンプト: これが選択されている場合、デフォルト値が指定されている場合でも、起動時にコマンドライン変数を選択するようプロンプトが出されます。

    追加変数についての詳細は、追加変数 を参照してください。

  1. ジョブテンプレートの詳細の設定が完了したら、保存 を選択します。

テンプレートを保存してもジョブテンプレートのページを終了せず、追加の編集ができるように Job Template Details (ジョブテンプレートの詳細) ビューに留まります。保存したジョブの 詳細 タブからは、Survey の確認、編集、および追加を実行できます (ジョブタイプがスキャンでない場合)。

_images/job-templates-job-template-saved.png

新規に作成されたテンプレートが画面下部のテンプレートの一覧に表示される際に、テンプレートが保存されていることを確認できます。

_images/job-template-saved-labels.png

14.2. 完了したジョブの表示

完了したジョブ タブには、このジョブテンプレートが実行された方法の詳細が記載されます。完了時に ID、名前、ジョブタイプが表示され、ジョブの再起動や削除を実行できます。ジョブ ID、名前、タイプまたはジョブが失敗したかどうかによって完了したジョブの一覧をフィルターできます。

_images/job-template-completed-jobs-view.png

14.3. パーミッションの追加

パーミッション タブでは、ユーザーおよびチームメンバーに関連付けられたパーミッションの確認、付与、編集および削除を実行できます。特定のユーザーにパーミッションを割り当てるには以下を行います。

  1. パーミッション タブをクリックします。
  2. add ボタンをクリックして、ユーザー/チームの追加ウィンドウを開きます。
Add Permissions Form
  1. アクセス権を持ち、特定のロールを割り当てるユーザーまたはチームを指定します。
  1. クリックして、ユーザーまたはチームの名前の横にある 1 つまたは複数のチェックボックスを選択してこれらを選択します。

注釈

ユーザーチーム タブ間を保存せずに切り換えることで、複数のユーザーとチームを同時に選択することができます。

選択を終えると、ウィンドウが展開され、ドロップダウンメニューの一覧から選択した各ユーザーまたはチームのロールを選択できるようになります。

Roles Assignment for Selected Users

上記の例では、インベントリーに関連付けられたオプションが表示されます。リソースごとに利用できるオプションが異なります。

  • 管理者: 権限の読み取り、実行および編集を許可します (すべてのリソースに適用)。
  • 使用: ジョブテンプレートのリソースの使用を許可します (ジョブテンプレート以外の全リソースに適用)。
  • 更新: SCM 更新でのプロジェクトの更新を許可します (プロジェクトおよびインベントリーに適用)。
  • アドホック: アドホックコマンドの使用を許可します (インベントリーに適用)。
  • 実行: ジョブテンプレートの起動を許可します (ジョブテンプレートに適用)。

ちなみに

ロールの選択ペインの キー ボタンを使用して、各ロールの説明を表示します。

  1. 選択したユーザーまたはチームに適用する役割を選択します。

注釈

ユーザーチーム タブ間を保存せずに切り換えることで、複数のユーザーとチームにロールを割り当てることができます。
Add Permissions - Examples of users and teams selected
  1. 各ユーザーとチームの役割の割り当てを確認します。
Add Permissions - Examples of roles applied
  1. 完了したら 保存 をクリックすると、ユーザー/チームの追加ウィンドウが閉じ、各ユーザーやチームに割り当てられた更新済みのロールが表示されます。

    Permissions tab with Role Assignments

特定ユーザーのパーミッションを削除するには、そのリソースの横にある「関連付けの解除」 (x) ボタンをクリックします。

_images/permissions-disassociate.png

これにより確認ダイアログが起動し、関連付けの解除の確認が求められます。

_images/permissions-disassociate-confirm.png

14.4. 通知の使用

通知 をクリックすると、設定した通知の統合を簡単に確認できます。

add notifications ボタンをクリックして通知を作成します。

詳細は、通知 を参照してください。

_images/job-template-completed-notifications-view.png

14.5. Survey

「実行」または「チェック」のジョブタイプを選択すると、ジョブテンプレートの作成または編集画面で Survey を設定できます。Survey は、「Prompt for Extra Variables (追加変数のプロンプト)」と同様に Playbook の追加変数を設定しますが、ユーザーが使いやすい質問と回答を使ってこれを実行します。また、Survey ではユーザー入力を検証することもできます。survey ボタンをクリックして Survey を作成します。

Survey のユースケースは多岐に及びます。一例として、開発者に「push to stage」ボタンを付与する操作が必要な場合、これは Ansible の高度な知識がなくても実行できます。起動時に、このタスクは「What tag should we release?」などといった質問への回答を求めるプロンプトを出す可能性があります。

多項選択式の質問を含む、多くのタイプの質問を尋ねるようにすることができます。

注釈

Survey は Enterprise レベルのライセンスを持つユーザーのみが利用できます。

14.5.1. Survey の作成

Survey を作成するには、以下を実行します。

  1. survey ボタンをクリックして、Survey の追加 ウィンドウを起動します。
Job template - create survey

画面上部にある ON/OFF トグルボタンを使用すると、この survey プロンプトをすぐに有効化または無効化できます。

  1. Survey には複数の質問を含めることができます。それぞれの質問について、以下の情報を入力します。
  • 名前: ユーザーに尋ねる質問
  • 説明: (オプション) ユーザーに尋ねられる内容の説明。
  • Answer Variable Name (回答の変数名): ユーザーの応答の保存に使用する Ansible 変数名。これは Playbook で使用される変数です。変数名にはスペースを含めることができません。
  • 回答タイプ: 以下の質問のタイプから選択します。
    • テキスト: 単一行のテキスト。この回答の最小および最大の長さ (文字数) を設定できます。
    • Textarea (テキスト領域): 複数行のテキストフィールド。この回答の最小および最大の長さ (文字数) を設定できます。
    • パスワード: 応答は、実際のパスワードが処理される場合と同様に機密情報として処理されます。この回答の最小および最大の長さ (文字数) を設定できます。
    • Multiple Choice (single select) (複数の選択 (単一選択)): 1 度に 1 つのみを選択できるオプションの一覧。複数の選択オプション ボックスに 1 行に 1 つのオプションを入力します。
    • Multiple Choice (multiple select)(複数の選択 (複数選択)): 1 度に任意の数のオプションを選択できるオプションの一覧。複数の選択オプション ボックスに 1 行に 1 つのオプションを入力します。
    • Integer (整数): 整数。この回答の最小および最大の長さ (文字数) を設定できます。
    • Float (浮動): 10 進数。この回答の最小および最大の長さ (文字数) を設定できます。
  • Default Answer (デフォルトの回答): 質問に対するデフォルトの回答。この値は、回答がユーザーによって提供されていない場合にインターフェースに事前に入力され、使用されます。
  • 必須: この質問に対する回答がユーザーから求められているかどうかを示します。
  1. 質問の情報を入力したら、add ボタンをクリックして質問を追加します。

定型化されたバージョンの Survey が「プレビュー」ペインに表示されます。いずれの質問についても、編集 ボタンをクリックして質問を編集できます。削除 ボタンをクリックすると質問を削除でき、グリッドアイコンをクリックおよびドラッグして質問の順序を変更できます。

  1. 左ペインに戻り、質問を追加します。
  2. 完了したら、保存 をクリックして Survey を保存します。

job-template-completed-survey

14.5.2. オプションの Survey の質問

Survey の質問に対する 必須 の設定は、対話するユーザーにとって回答がオプションかどうかを決定します。

背後では、オプションの Survey 変数は入力されていない場合でも Playbook の extra_vars に渡されることがあります。

  • テキスト以外の変数 (入力タイプ) がオプションとマークされ、入力されていない場合、Survey の extra_var は Playbook に渡されません。
  • テキスト入力またはテキスト領域の入力がオプションとしてマークされ、入力されていない場合で、最小の length > 0 が設定されている場合、Survey の extra_var は Playbook に渡されません。
  • テキスト入力またはテキスト領域の入力がオプションとしてマークされ、入力されていない場合で、最小の length === 0 が設定されている場合、Survey の extra_var は、値が空のストリング ( “” ) に設定された状態で Playbook に渡されます。

14.6. ジョブテンプレートの起動

Ansible Tower の大きな利点として、Ansible Playbook のプッシュボタンによるデプロイメントが挙げられます。Tower 内でテンプレートを簡単に定義し、Playbook だけでなく、インベントリー、認証情報、追加変数およびコマンドラインで指定できるすべてのオプションと設定を含む、通常はコマンドで ansible-playbook に渡すすべてのパラメーターを保存することができます。

簡単になったデプロイメントによって毎回同じ方法で Playbook を実行できるため、一貫性が高まり、責任を委任することも可能になります。Ansible の専門家でないユーザーでも、他のユーザーが作成した Tower Playbook を実行できます。

ジョブテンプレートを起動するには、以下を実行します。

  1. テンプレート ナビゲーションリンクまたはジョブテンプレートの詳細ビューからジョブテンプレートにアクセスし、下方にスクロールしてテンプレートの一覧からこれにアクセスします。

Job Templates

  1. launch ボタンをクリックします。

ジョブを実行するには、追加の情報が必要になる場合があります。以下のデータは起動時に必要になることがあります。

  • 設定された認証情報
  • Ask に設定されたパスワードまたはパスフレーズ
  • Survey (ジョブテンプレート用に設定されている場合)
  • 追加変数 (ジョブテンプレートで必要な場合)

以下は、ジョブタグのプロンプトを出し、Survey で作成された Survey サンプルを実行するジョブの起動例です。

job-launch-with-prompt-job-tags

job-launch-with-prompt-survey

ジョブテンプレートおよび Survey に設定される追加変数と共に、Tower は以下の変数をジョブ環境に自動的に追加します。

  • tower_job_id: このジョブ実行のジョブ ID
  • tower_job_launch_type: ジョブが開始された方法を示す 手動コールバック、または スケジュール済み のいずれか。
  • tower_job_template_id: このジョブ実行が使用するジョブテンプレート ID
  • tower_job_template_name: このジョブが使用するジョブテンプレート名
  • tower_user_id: このジョブを開始した Tower ユーザーのユーザー ID。これはコールバックまたはスケジュール済みジョブでは利用できません。
  • tower_user_name: このジョブを開始した Tower ユーザーのユーザー名。これはコールバックまたはスケジュール済みジョブでは利用できません。

起動時に、Tower は web ブラウザーを ジョブ タブにあるこのジョブの「ジョブステータス」ページに自動的にリダイレクトします。

14.7. スケジューリング

ジョブテンプレートの起動は、schedule ボタンを使ってスケジュールすることもできます。このボタンをクリックすると、スケジュール ページが開きます。

Job Templates - schedule launch

このページには、選択された ジョブテンプレート で現在利用できるスケジュールの一覧が表示されます。スケジュールの一覧は、以下のいずれかで並び替え、検索できます。

  • 名前: スケジュール名をクリックすると、スケジュールの編集 ダイアログが開きます。
  • 初回実行日時: このタスクの最初にスケジュールされる実行
  • 次回実行日時: このタスクの次回にスケジュールされる実行
  • 最終実行日時: タスクに終了日時が設定されている場合、これはタスクの最後の実行になります。

スケジュール 画面の右上にあるボタンから以下のアクションを実行できます。

  • アクティビティーストリームの表示
  • 新規スケジュールの追加

14.7.1. ジョブテンプレートのスケジュール

新規スケジュールを作成するには、以下を実行します。

  1. スケジュール画面で、add ボタンをクリックします。
  2. 以下のフィールドに該当する詳細を入力します。
  • 名前
  • 開始日
  • 開始時間
  • ローカルタイムゾーン: 入力した開始時間はこのタイムゾーンの時間になります。
  • 繰り返しの頻度: 更新頻度の変更に合わせて適切なオプションが表示されます。

注釈

ジョブは UTC でスケジュールされます。ジョブが 1 日の特定の時間に繰り返し実行される場合には、夏時間 (DST) へ/からの切り替えがあると、ローカルタイムゾーンに合わせてこれらのジョブのスケジュールは移動します。

以下のスケジュールの説明には、スケジュールの具体的な内容と選択されたローカルタイムゾーンのスケジュール済みのオカレンスの一覧が表示されます。

Job Template - schedule add

  1. スケジュールの詳細が正しければ、保存 をクリックします。

スケジュールが保存されると、関連付けられたジョブテンプレートについてのスケジュールの一覧が表示されます。

ON/OFF トグルボタンを使用すると、このスケジュールをすぐに有効化または無効化できます。

スケジュールの他のアクションは「アクション」列で選択できます。

  • スケジュールの編集
  • スケジュールの削除

14.8. ジョブテンプレートのコピー

Ansible Tower 3.0 では、ジョブテンプレートのコピー機能が導入されています。ジョブテンプレートのコピーを選択した場合、関連付けられたスケジュール、通知、またはパーミッションのコピーは 実行されません。スケジュールおよび通知は、ジョブテンプレートのコピーを作成するユーザーまたは管理者によって再作成される必要があります。ジョブテンプレートをコピーするユーザーには管理者権限が付与されますが、パーミッションはジョブテンプレートには割り当てられたり (コピーされたり) しません。

  1. テンプレート ナビゲーションリンクまたはジョブテンプレートの詳細ビューからコピーするジョブテンプレートにアクセスし、下方にスクロールしてテンプレートの一覧からこれにアクセスします。

Job Templates

  1. copy ボタンをクリックします。

新規テンプレートが、コピーしたテンプレートの名前とタイムスタンプが設定された状態で開きます。

  1. 名前 フィールドの内容を新規の名前に置き換え、他のフィールドのエントリーを指定または変更してこのページを完了します。
  2. 完了したら 保存 をクリックします。

14.9. スキャンジョブテンプレート

スキャンジョブは Ansible Tower 3.2 以降ではサポートされなくなりました。このシステムトラッキング機能は、履歴データとしてファクトをキャプチャーし、保存する方法として使用されてきました。ファクトはファクトのキャッシュにより Tower に保存されるようになりました。詳細は、ファクトのキャッシング を参照してください。

Ansible Tower 3.2 よりも前のバージョンのシステムにジョブテンプレートのスキャンジョブがある場合、それらはタイプの実行 (通常のジョブテンプレートと同様) に変換されており、それらの関連リソース (インベントリー、認証情報など) を保持しています。関連プロジェクトのないジョブテンプレートのスキャンジョブにはデフォルトで特殊な Playbook が割り当てられるか、またはユーザーは独自のスキャン Playbook でプロジェクトを指定することができます。https://github.com/ansible/tower-fact-modules をポイントするプロジェクトが各組織に作成され、ジョブテンプレートは Playbook に設定されていました (https://github.com/ansible/tower-fact-modules/blob/master/scan_facts.yml)。

14.9.1. ファクトスキャン Playbook

スキャンジョブ Playbook scan_facts.yml には、3 つの fact scan modules パッケージ、サービスおよびファイルの呼び出し機能が Ansible の標準的なファクト収集機能と共に含まれます。scan_facts.yml playbook ファイルは以下のようになります。

- hosts: all
  vars:
    scan_use_checksum: false
    scan_use_recursive: false
  tasks:
    - scan_packages:
    - scan_services:
    - scan_files:
        paths: '{{ scan_file_paths }}'
        get_checksum: '{{ scan_use_checksum }}'
        recursive: '{{ scan_use_recursive }}'
      when: scan_file_paths is defined

scan_files ファクトモジュールは、スキャンジョブテンプレートの extra_vars で渡されるパラメーターを受け入れる唯一のモジュールです。

scan_file_paths: '/tmp/'
scan_use_checksum: true
scan_use_recursive: true
  • scan_file_paths パラメーターには複数の設定がある場合があります (/tmp/ または /var/log など)。
  • scan_use_checksum および scan_use_recursive パラメーターは false に設定したり、省略したりすることもできます。省略することと false に設定することは同じです。

スキャンジョブテンプレートは become を有効にし、become が使用される可能性のある認証情報を使用するはずです。「オプション」メニューの 権限昇格の有効化 にチェックを付けて become を有効にすることができます。

_images/job-templates-create-new-job-template-become.png

注釈

Ansible Tower バージョン 3.1.x でスキャンジョブテンプレートを維持していて、Ansible Tower バージョン 3.2 にアップグレードする場合、新たな「Tower Fact Scan - Default」プロジェクトが自動的に作成されます。このプロジェクトには、これまで以前のバージョンの Ansible Tower で使われていた古いスキャン Playbook が含まれます。

14.9.2. scan_facts.yml でサポートされるオペレーションシステム

ファクトキャッシュと共に scan_facts.yml playbook を使用する場合、OS がサポートされていることを確認してください。

  • Red Hat Enterprise Linux 5, 6, & 7
  • CentOS 5, 6, & 7
  • Ubuntu 12.04, 14.04, 16.04
  • OEL 6 & 7
  • SLES 11 & 12
  • Debian 6, 7, 8
  • Fedora 22, 23, 24
  • Amazon Linux 2016.03
  • Windows Server 2008 以降

一部のオペレーティングシステムには、python を実行したり、スキャンモジュールが依存する python パッケージ (python-apt など)にアクセスしたりするために初期設定が必要になる場合があります。

14.9.3. スキャン前の設定

以下は、スキャンジョブを実行できるように特定のディストリビューションを設定する Playbook の例です。

Bootstrap Ubuntu (16.04)

---

- name: Get Ubuntu 15, 16, and on ready
 hosts: all
 sudo: yes
 gather_facts: no

 tasks:

 - name: install python-simplejson
   raw: sudo apt-get -y update
   raw: sudo apt-get -y install python-simplejson
   raw: sudo apt-get install python-apt

Bootstrap Fedora (23, 24)

---

- name: Get Fedora ready
 hosts: all
 sudo: yes
 gather_facts: no

 tasks:

 - name: install python-simplejson
   raw: sudo dnf -y update
   raw: sudo dnf -y install python-simplejson
   raw: sudo dnf -y install rpm-python

CentOS 5 または Red Hat Enterprise Linux 5 では、simplejson パッケージのインストールが必要になる場合があります。

14.9.4. カスタムファクトスキャン

カスタムファクトスキャンの Playbook は上記のファクトスキャン Playbook の例と似ています。例として、カスタム scan_foo Ansible ファクトモジュールのみを使用する Playbook は以下のようになります。

scan_custom.yml:

- hosts: all
  gather_facts: false
  tasks:
    - scan_foo:

scan_foo.py:

def main():
    module = AnsibleModule(
        argument_spec = dict())

    foo = [
      {
        "hello": "world"
      },
      {
        "foo": "bar"
      }
    ]
    results = dict(ansible_facts=dict(foo=foo))
    module.exit_json(**results)

main()

カスタムファクトモジュールを使用するには、それがスキャンジョブテンプレートで使用される Ansible プロジェクトの /library/ サブディレクトリーにあることを確認します。このファクトスキャンモジュールは非常に単純で、ハードコーディングされたファクトのセットを返します。

[
   {
     "hello": "world"
   },
   {
     "foo": "bar"
   }
 ]

詳細は、Ansible ドキュメントの Module Provided ‘Facts’ セクションを参照してください。

14.10. ファクトのキャッシング

Tower は Ansible ファクトキャッシュプラグイン経由でホストごとにファクトを保存し、取得します。この動作はジョブテンプレート別に設定されます。ファクトのキャッシングはデフォルトでオフにされていますが、ジョブの実行に関連するインベントリーのすべてのホストについてのファクト要求に対応できるように有効にできます。これにより、ホストのファクトのインベントリー全体にアクセスを有する状態で、--limit を使ってジョブテンプレートを使用できます。プラグインがホストごとに施行するグローバルタイムアウト設定は、「ジョブ」タブの下の「Configure Tower (Tower の設定)」インターフェースから (秒単位で) 指定できます。

_images/configure-tower-jobs-fact-cache-timeout.png

ファクトキャッシュを使用するジョブの起動時 (use_fact_cache=True) に、Tower は memcached に対し、ジョブに関連付けられたインベントリーの各ホストに関連付けられたすべての ansible_facts を挿入します。インベントリーのすべてのホストの一覧も inventory_id キーとホスト名の値と共に memcached に挿入されます。Ansible Tower に同梱される Ansible ファクトキャッシュプラグインは、ファクトキャッシュが有効にされた (use_fact_cache=True) ジョブに対して有効にされます。Ansible で実行されるファクトキャッシュプラグインは同じ memcached インスタンスに接続されます。

ファクトキャッシュが有効にされた (use_fact_cache=True) ジョブの実行が終了すると、Tower は memcached をチェックし、インベントリーのホストのすべてのレコードを収集します。現在のホスト別に保存されているファクトよりも更新時間が新しいレコードがデータベースに保存されます。

Tower はホストの ansible_facts を memcached に常に挿入します。キャッシュされた値は、ホスト別に新たに保存されたファクトおよびグローバルファクトキャッシュ設定に指定されたタイムアウト値に基づいて表示または非表示になります。

新規の、および変更されたファクトは Tower のロギング機能によってログに記録されます。とりわけ system_tracking 名前空間またはロガーに対して実行されます。ログのペイロードには以下のフィールドが含まれます。

  • host_name
  • inventory_id
  • ansible_facts

ここで ansible_facts は、Tower インベントリー inventory_idhost_name のすべての Ansible ファクトの辞書になります。

14.10.1. ファクトキャッシングの利点

ファクトのキャッシングにより、ファクトの収集を実行する場合よりも大幅の時間を節約できます。数千のホストおよびフォークに対して実行されるジョブに Playbook がある場合に、それらのホスト全体でファクトを収集するだけで 10 分程度の時間がかかってしまう可能性があります。一方、ジョブを定期的に実行する場合に最初の実行時にそれらのファクトがキャッシュされると、次回実行時にはそれらがデータベースからプルされるようになります。これにより、スマートインベントリーなどの大規模なインベントリーに対するジョブの実行時間が大幅に削減されます。

注釈

ファクトのキャッシングを適用する際に tower.cfg ファイルを変更しないでください。カスタムファクトキャッシングは Tower のファクトキャッシング機能と競合する可能性があります。Ansible Tower に同梱されるファクトキャッシングモジュールを使用することをお勧めします。ファクトキャッシングは分離されたノードではサポートされません。

キャッシュされたファクトのジョブでの使用は、「ジョブテンプレート」ウィンドウの オプション フィールドでこれを有効にして選択できます。

_images/job-templates-options-use-factcache.png

ファクトをクリーンアップするには、Tower にパッケージされない「ファクトのクリア (clear fact)」Playbook を実行する必要がありますが、これは GitHub からプルできます。gather_facts: False を設定しても、既存のファクトはクリアされません。

ファクトキャッシングの API エンドポイントについては、http://<Tower server name>/api/v2/hosts/x/ansible_facts を参照してください。

14.11. クラウド認証情報の利用

クラウド認証情報は、それぞれのクラウドインベントリーの同期時に使用されます。クラウド認証情報はジョブテンプレートに関連付け、Playbook で使用できるようにランタイム環境に組み込むこともできます。クラウド認証情報の使用は、Ansible Tower バージョン 2.4.0 で導入されました。

14.11.1. OpenStack

以下のサンプル Playbook は nova_compute Ansible OpenStack クラウドモジュールを起動し、タスクの実行にあたっては認証情報を要求し、とくに auth_urlユーザー名パスワード、および project_name などの情報を要求します。これらのフィールドは、クラウド認証情報の内容に基づいて Tower で作成された YAML ファイルをポイントする環境変数 OS_CLIENT_CONFIG_FILE を使って Playbook で利用できるようにされます。このサンプル Playbook は YAML ファイルを Ansible 変数スペースに読み込みます。

OS_CLIENT_CONFIG_FILE の例:

clouds:
  devstack:
    auth:
      auth_url: http://devstack.yoursite.com:5000/v2.0/
      username: admin
      password: your_password_here
      project_name: demo

Playbook の例:

- hosts: all
  gather_facts: false
  vars:
    config_file: "{{ lookup('env', 'OS_CLIENT_CONFIG_FILE') }}"
    nova_tenant_name: demo
    nova_image_name: "cirros-0.3.2-x86_64-uec"
    nova_instance_name: autobot
    nova_instance_state: 'present'
    nova_flavor_name: m1.nano

    nova_group:
      group_name: antarctica
      instance_name: deceptacon
      instance_count: 3
  tasks:
    - debug: msg="{{ config_file }}"
    - stat: path="{{ config_file }}"
      register: st
    - include_vars: "{{ config_file }}"
      when: st.stat.exists and st.stat.isreg

    - name: "Print out clouds variable"
      debug: msg="{{ clouds|default('No clouds found') }}"

    - name: "Setting nova instance state to: {{ nova_instance_state }}"
      local_action:
        module: nova_compute
        login_username: "{{ clouds.devstack.auth.username }}"
        login_password: "{{ clouds.devstack.auth.password }}"

14.11.2. Amazon Web Services

Amazon Web Services クラウド認証情報は Playbook の実行時に以下の環境変数として公開されます (ジョブテンプレートで、設定に必要なクラウド認証情報を選択します):

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

すべての AWS モジュールは、aws_access_key_id または aws_secret_access_key モジュールオプションを設定せずに Tower で実行される際にこれらの認証情報を暗黙的に使用します。

14.11.3. Rackspace

Rackspace クラウド認証情報は Playbook 実行時に以下の環境変数として公開されます (ジョブテンプレートで、設定に必要なクラウド認証情報を選択します):

  • RAX_USERNAME
  • RAX_API_KEY

すべての Rackspace モジュールは、username または api_key モジュールオプションを設定せずに Tower で実行される際にこれらの認証情報を暗黙的に使用します。

14.11.4. Google

Google クラウド認証情報は、Playbook の実行時に以下の環境変数として公開されます (ジョブテンプレートで、設定に必要なクラウド認証情報を選択します)。

  • GCE_EMAIL
  • GCE_PROJECT
  • GCE_PEM_FILE_PATH

すべての Google モジュールは、service_account_emailproject_id、または pem_file モジュールオプションを設定せずに Tower で実行される際にこれらの認証情報を暗黙的に使用します。

14.11.5. Azure

Azure クラウド認証情報は、Playbook の実行時に以下の環境変数として公開されます (ジョブテンプレートで、設定に必要なクラウド認証情報を選択します)。

  • AZURE_SUBSCRIPTION_ID
  • AZURE_CERT_PATH

すべての Azure モジュールは、subscription_id または management_cert_path モジュールオプションを設定せずに Tower で実行される際にこれらの認証情報を暗黙的に使用します。

14.11.6. VMware

VMware クラウド認証情報は、Playbook の実行時に以下の環境変数として公開されます (ジョブテンプレートで、設定に必要なクラウド認証情報を選択します)。

  • VMWARE_USER
  • VMWARE_PASSWORD
  • VMWARE_HOST

以下のサンプル Playbook は、これらの認証情報の使用方法を示しています。

- vsphere_guest:
    vcenter_hostname: "{{ lookup('env', 'VMWARE_HOST') }}"
    username: "{{ lookup('env', 'VMWARE_USER') }}"
    password: "{{ lookup('env', 'VMWARE_PASSWORD') }}"
    guest: newvm001
    from_template: yes
    template_src: centosTemplate
    cluster: MainCluster
    resource_pool: "/Resources"
    vm_extra_config:
      folder: MyFolder

14.12. プロビジョニングコールバック

プロビジョニングコールバックは、ユーザーがジョブを起動して Tower コンソールからホストを管理するのを待機するのではなく、ホストが独自に Playbook 実行を開始できるようにする Tower の機能です。プロビジョニングコールバックは、呼び出し側のホストで Playbook を実行する場合に のみ 使用されることに注意してください。プロビジョニングコールバックは、クラウド拡張 (cloud bursting) に対応するものです。つまり、別のホストに対してジョブを実行するのではなく、 (承認キーの送信などの) 設定のためにクライアントとサーバー間の通信が必要な新規インスタンスを想定しています。これは、別のシステムでプロビジョニングされた後のシステムの自動設定 (AWS 自動スケーリング、またはキックスタートまたは peseed などの OS プロビジョニングシステムなど)、または Tower API を直接起動しないジョブのプログラムによる起動を可能にします。起動するジョブテンプレートはプロビジョニングを要求するホストに対してのみ実行されます。

これは firstboot タイプのスクリプトまたは cron からアクセスされることが多くあります。

コールバックを有効にするには、ジョブテンプレートで プロビジョニングコールバックの許可 チェックボックスにチェックを付けます。これにより、このジョブテンプレートの プロビジョニングコールバック URL が表示されます。

注釈

Tower のプロビジョニングコールバック機能を動的インベントリーと共に使用しようとする場合、「起動時の更新」がジョブテンプレートでインベントリーグループに対して設定されている必要があります。

_images/provisioning-callbacks-config.png

コールバックには、URL のある外部ホストが設定を要求できないようにするためにホスト設定キーも必要です。create ボタンをクリックしてこのコールバックの固有のホストキーを作成するか、または独自のキーを入力します。ホストキーは複数のホストで再利用でき、このジョブテンプレートは多数のホストに対して適用できます。設定を要求できるホストを制御する必要がある場合、キーはいつでも変更できます。

REST 経由で手動のコールバックを実行するには、以下の形式のコールバック URL を UI で確認します。

http://<Tower server name>/api/v2/job_templates/1/callback/

同じ URL の ‘1’ は Tower のジョブテンプレート ID です。

ホストからの要求は POST である必要があります。以下は、curl を使用した例になります (すべて単一行にあります)。

[email protected]:~$ curl --data "host_config_key=5a8ec154832b780b9bdef1061764ae5a" \
                    http://<Tower server name>/api/v2/job_templates/1/callback/

コールバックが正常に実行されるには、要求側のホストをインベントリーに定義する必要があります。Tower から定義済みのインベントリーで名前または IP アドレスによるホストの検索ができない場合、要求は拒否されます。このようにジョブテンプレートを実行する場合、独自に実行される Playbook を実行するホストはインベントリーになければなりません。ホストがインベントリーにない場合、ジョブテンプレートは「一致するホストがありません」というタイプのエラーメッセージを出して失敗します。

注釈

ホストがインベントリーになく、起動時の更新 がインベントリーグループに設定されている場合、Tower はコールバックの実行前にクラウドベースのインベントリーソースの更新を試行します。

要求が成功した場合は、「ジョブ」タブにエントリーが作成されます。ここで結果および履歴を確認できます。

コールバックは REST でアクセスできますが、コールバックの推奨される使用方法として、/usr/share/awx/request_tower_configuration.sh (Linux/UNIX) または /usr/share/awx/request_tower_configuration.ps1 (Windows) など、Tower に同梱されるサンプルのスクリプトのいずれかを使用できます。使用方法については、以下のように -h フラグを渡すと、ファイルのソースコードに表示されます。

./request_tower_configuration.sh -h
Usage: ./request_tower_configuration.sh <options>

Request server configuration from Ansible Tower.

OPTIONS:
   -h      Show this message
   -s      Tower server (e.g. https://tower.example.com) (required)
   -k      Allow insecure SSL connections and transfers
   -c      Host config key (required)
   -t      Job template ID (required)
   -e      Extra variables
   -s      Number of seconds between retries (default: 60)

このスクリプトには、コマンドを再試行する方法を認識する点でインテリジェンスがあります。単純な curl 要求に対し、コールバックを使用するためのより堅牢な方法になります。記載されているように、スクリプトの再試行は 1 分に 1 回の頻度で最長 10 分間行われます。

注釈

これはスクリプトのサンプルであることに注意してください。200 エラーコード以外のエラーコードは再試行を要求する一時的なエラーでない場合があるため、失敗シナリオを検出する際により動的な動作が必要な場合にはこのスクリプトを編集する必要があります。

クラウドインベントリーをサポートされているクラウドプロバイダーのいずれかからプルする場合のように、コールバックを Tower の動的インベントリーと共に使用する可能性が高くなります。これらの場合には、起動時の更新 の設定と共に、クラウドの API エンドポイントのハンマリングを防ぐために、インベントリーソースのインベントリーのキャッシュタイムアウトを設定します。request_tower_configuration.sh スクリプトは 1 分に 1 回の頻度で最小 10 分間ポーリングを行うため、インベントリーの推奨されるキャッシュ無効化の時間 (インベントリーソース自体に設定される) は 1 分または 2 分間になります。

cron ジョブからの request_tower_configuration.sh スクリプトの実行についての推奨を行う一方、cron の間隔については 30 分ごとが推奨されます。繰り返される設定は Tower のスケジュールで簡単に処理できるため、ほとんどのユーザーによるコールバックの主な使用方法は、オンライン時の最新の設定にブートストラップされるベースイメージを有効にする方法です。これを実行するには、初回の起動時に実行するのがより適切です。初回起動時のスクリプトは、通常は自己削除を実行する単純な init スクリプトであるため、request_tower_configuration.sh スクリプトのコピーを呼び出す init スクリプトを設定し、それを自動スケーリングイメージに入れます。

14.12.1. 追加変数をプロビジョニングコールバックに渡す

通常のジョブテンプレートで extra_vars を渡せるように、それらをプロビジョニングコールバックに渡すこともできます。extra_vars を渡すには、送信されたデータはアプリケーション/json として (コンテンツタイプとして) POST 要求の本体の一部にする必要があります。独自の extra_vars が渡されるように追加する際に、例として以下の JSON 形式を使用します。

'{"extra_vars": {"variable1":"value1","variable2":"value2",...}}'

(Ansible Tower バージョン 2.2.0 で追加されています。)

また以下の例に示されているように、curl を使用してジョブテンプレートの呼び出しに追加の変数を渡すこともできます。

[email protected]:~$ curl -f -H 'Content-Type: application/json' -XPOST \
                 -d '{"host_config_key": "5a8ec154832b780b9bdef1061764ae5a", "extra_vars": "{\"foo\": \"bar\"}"}' \
                 http://<Tower server name>/api/v2/job_templates/1/callback

詳細は、Launching Jobs with Curl を参照してください。

14.12.2. tower-cli でのプロビジョニングコールバック

request_tower_configuration.sh スクリプトまたはカスタムスクリプトを実行する代わりに、tower-cli を使用してプロビジョニングコールを実行できます。以下は例になります。

tower-cli job_template callback --host-config-key="5a8ec154832b780b9bdef1061764ae5a" --extra-vars="foo: bar"

14.13. 追加変数

注釈

追加の厳密な extra_vars 検証が Ansible Tower 3.0.0 で追加されました。ジョブ起動 API に渡される extra_vars は、以下が True の場合のみ受け入れられます。

  • それらは有効な survey の変数に対応するものである。
  • ask_variables_on_launch は True に設定されている。

Survey 変数を渡す際に、それらは Tower 内の追加変数 (extra_vars) として渡されます。これは、(Survey で実行するように) 追加変数をジョブテンプレートに渡すと、インベントリーおよびプロジェクトから渡される他の変数が上書きされる可能性があるために注意が必要です。

たとえば、インベントリーの定義された変数が debug = true であるとします。この変数 debug = true がジョブテンプレート Survey で上書きされる可能性はあります。

渡す必要のある変数が上書きされないようにするには、それらを Survey で再定義することでそれらが組み込み済みであることを確認します。追加変数はインベントリー、グループおよびホストのレベルで定義できることに注意してください。

注釈

Ansible Tower バージョン 2.4 より、ジョブテンプレートの追加変数および Survey 変数の動作が変更されました。以前のバージョンでは、Survey を使用して設定される変数はジョブテンプレートで指定される追加変数をオーバーライドしました。2.4 以降では、ジョブテンプレートの追加変数辞書は Survey 変数にマージされています。これにより、2.4 へのアップグレード時に動作の変更が生じる可能性があります。

以下の表では、Ansible の変数の順序との比較で、Ansible Tower の変数の順序の動作 (階層) を示しています。

Ansible Tower 変数の順序の階層 (最後に一覧表示された win)

_images/Architecture-Tower_Variable_Precedence_Hierarchy.png

14.13.1. ジョブテンプレートの再起動

Ansible Tower バージョン 2.4 の別の変更により、ジョブの launch_type 設定が導入されました。ジョブを手動で再起動せずに、再起動は launch_typerelaunch に設定して表示されます。再起動の動作は、extra_vars継承しない 点で、起動の動作とは異なります。

ジョブを再起動しても継承ロジックが実行される訳でありません。再起動されるジョブについて計算されたものと同じ extra_vars を使用します。

たとえば、extra_vars を指定せずにジョブテンプレートを起動するとします。これにより、j1 というジョブが作成されます。次に、そのジョブテンプレートを編集し、一部の extra_vars の追加 ("{ "hello": "world" }" の追加など) を実行するとします。

j1 を再起動すると j2 が作成されますが、継承するロジックがなく、j1 には extra_vars がないため、j2 には extra_vars が指定されません。

この例では、j1 の作成後に追加した extra_vars でジョブテンプレートを起動した場合、作成される再起動ジョブ (j3) には extra_vars が含まれます。j3 を再起動すると j4 が作成され、これにも extra_vars が含まれます。