Documentation

25. ジョブ

job は、Ansible Playbook をホストのインベントリーに対して起動する automation controller のインスタンスです。

ジョブ リンクでは、ジョブとそのステータス (正常に完了、失敗、またはアクティブ (実行中) のジョブ) の一覧が表示されます。デフォルトのビューは折りたたまれており (コンパクト)、ジョブ名、ステータス、ジョブタイプ、開始/終了時間が表示されますが、展開して更に情報を表示できます。さまざまな基準でこのリストをソートし、必要とするジョブに絞り込むことができます。

Jobs - home with example job

_images/jobs-list-all-expanded.png

この画面から実行できるアクションには、特定のジョブの詳細および標準出力の表示、ジョブの再起動 (launch)、または選択したジョブの削除が含まれます。再起動操作は、Playbook の実行の再起動にのみ適用され、システムジョブ、プロジェクト/インベントリーの更新、ワークフロージョブなどには適用されません。

ジョブが再起動すると、ジョブの実行時にジョブ出力画面が表示されます。任意のタイプのジョブをクリックしても、そのジョブのジョブ出力ビューに移動します。このビューでは、さまざまな条件でジョブをフィルタリングできます。

_images/job-details-view-filters.png
  • Stdout オプションは、ジョブプロセスおよび出力を表示するデフォルトの表示です。

  • イベント オプションを使用すると、エラー、ホスト障害、ホストの再試行、スキップされた項目など、対象のイベントでフィルタリングできます。フィルターには、必要な数のイベントを含めることができます。

_images/job-details-view-filters-examples.png
  • **詳細**オプションは、条件の包含または除外、キーによる検索、またはルックアップタイプによる検索の組み合わせを可能にする高度な検索です。検索の使用方法について、詳しくは 検索 の章を参照してください。

25.1. インベントリー同期ジョブ

インベントリの同期が実行されると、完全な結果が自動的に Output タブに表示されます。これは、Ansible コマンドラインで実行した場合に表示されるのと同じ情報を示しており、デバッグに役立ちます。ANSIBLE_DISPLAY_ARGS_TO_STDOUT は、デフォルトで、すべての Playbook の実行に対して False に設定されます。これは、Ansible のデフォルトの動作と同じです。これにより、ジョブ詳細インターフェースのタスクヘッダーにタスクの引数を表示しなくなり、標準出力に特定の機密情報のモジュールパラメーターを漏洩しなくなります。(セキュリティーの問題がありますが) 以前の動作を復元するには、AWX_TASK_ENV 構成設定の ANSIBLE_DISPLAY_ARGS_TO_STDOUTTrue に設定できます。詳細情報は、ANSIBLE_DISPLAY_ARGS_TO_STDOUT を参照してください。

出力タブの右上隅にあるアイコンを使用すると、再起動 (launch)、ジョブ出力のダウンロード (download)、またはジョブの削除 (delete) を実行できます。

job details example of inventory sync

注釈

関連ジョブの実行中にインベントリーの更新を実行できます。大規模なプロジェクト (約10 GB) がある場合は、/tmp のディスク容量が問題になる可能性があります。

25.1.1. インベントリー同期の詳細

詳細 タブにアクセスし、ジョブ実行の詳細を提供します。

_images/jobs-show-job-details-for-inv-sync.png

実行したジョブの主な詳細は以下のとおりです。

  • ステータス: 以下のいずれかになります。

    • 保留中: インベントリーの同期は作成されていますが、まだキューに入れられていないか、または開始されていません。すべてのジョブ (インベントリーソースの同期に限らない) はシステムで実際に実行可能になるまで保留中の状態になります。インベントリーソースの同期が準備できる状態でない理由として、依存関係が現在実行中であるか (次の手順に進む前にすべての依存関係の実行が完了していなければならない)、または設定先で実行する容量が足りないなどが挙げられます。

    • 待機中: インベントリーの同期はキューに入れられており、実行を待機中です。

    • 実行中: インベントリーの同期が進行中です。

    • 成功: インベントリー同期ジョブが成功しました。

    • 失敗: インベントリーの同期ジョブが失敗しました。

  • インベントリー: 関連付けられたインベントリーグループの名前。

  • ソース: クラウドインベントリーのタイプ。

  • インベントリーソースのプロジェクト: このインベントリー同期ジョブのソースとして使用されるプロジェクト。

  • 実行環境: execution environment が使用されています。

  • 実行ノード: ジョブの実行に使用されるノード。

  • インスタンスグループ: このジョブで使用されるインスタンスグループの名前 (コントローラーはデフォルトのインスタンスグループ)。

これらの項目をクリックすると、適切な場合には該当するジョブテンプレート、プロジェクト、およびその他のオブジェクトが表示されます。

25.2. SCM インベントリージョブ

SCM から供給されたインベントリーが実行されると、完全な結果が自動的に出力タブに表示されます。これは、Ansible コマンドラインで実行した場合に表示されるのと同じ情報を示しており、デバッグに役立ちます。出力タブの右上隅にあるアイコンを使用すると、再起動 (launch)、ジョブ出力のダウンロード (download)、またはジョブの削除 (delete) を実行できます。

_images/jobs-show-job-results-for-scm-job.png

25.2.1. SCM インベントリーの詳細

**詳細**タブにアクセスして、ジョブの実行とそれに関連するプロジェクトの詳細を提供します。

_images/jobs-show-job-details-for-scm-job.png

実行したジョブの主な詳細は以下のとおりです。

  • ステータス: 以下のいずれかになります。

    • 保留中: SCM ジョブは作成されていますが、まだキューに入れられていないか、または開始されていません。すべてのジョブ (SCM ジョブに限らない) はシステムで実際に実行可能になるまで保留中の状態になります。SCM ジョブが準備できる状態でない理由として、依存関係が現在実行中であるか (次の手順に進む前にすべての依存関係の実行が完了していなければならない)、または設定先で実行する容量が足りないなどが挙げられます。

    • 待機中: SCM ジョブはキューに入れられており、実行を待機中です。

    • 実行中: SCM ジョブが進行中です。

    • 成功: 直前の SCM ジョブが成功しました。

    • 失敗: 直前の SCM ジョブが失敗しました。

  • ジョブタイプ: SCM ジョブはソースコントロールの更新を表示します。

  • プロジェクト: プロジェクトの名前。

  • プロジェクトステータス: 関連付けられたプロジェクトが正常に更新されたかどうかを示します。

  • リビジョン: このジョブでソースとして使用されたプロジェクトのリビジョン番号を示します。

  • 実行環境: このジョブの実行に使用された execution environment を指定します。

  • 実行ノード: ジョブが実行されたノードを示します。

  • インスタンスグループ: 指定されている場合、ジョブが実行されたインスタンスグループを示します。

  • ジョブタグ: タグは実行されたさまざまなジョブ操作を示します。

これらの項目をクリックすると、適切な場合には該当するジョブテンプレート、プロジェクト、およびその他のオブジェクトが表示されます。

25.3. Playbook 実行ジョブ

Playbook が実行されると、完全な結果が自動的に出力タブに表示されます。これは、Ansible コマンドラインで実行した場合に表示されるのと同じ情報を示しており、デバッグに役立ちます。

_images/jobs-show-job-results-for-example-job.png

イベントの概要では、この Playbook の一部として実行されたイベントの集計が表示されます。

  • この Playbook が Plays フィールドで実行された回数

  • タスク フィールドでこの Playbook に関連付けられているタスクの数

  • ホスト フィールドでこの Playbook に関連付けられているホストの数

  • 経過 フィールドで Playbook の実行を完了するのにかかった時間

_images/jobs-events-summary.png

イベント概要の横ににあるアイコンを使用すると、再起動 (launch)、ジョブ出力のダウンロード (download)、またはジョブの削除 (delete) を実行できます。

ホストのステータスバーは、出力表示の上部で実行されます。ホストステータスバーのセクションにカーソルを置くと、その特定のステータスに関連付けられたホスト数が表示されます。

Job - All Host Events

Playbook ジョブの出力には、ジョブテンプレートページの ジョブ タブからジョブを起動した後もアクセスできます。

出力内のさまざまなラインアイテムタスクをクリックすると、そのホストの詳細を表示できます。

25.3.2. ホストの詳細

ホストの詳細 ダイアログでは、選択したイベントの影響を受けるホストに関する情報と、それに関連するプレイおよびタスクが表示されます。

  • ホスト

  • ステータス

  • プレイ フィールドでの実行タイプ

  • タスク のタイプ

  • 適用可能な場合、タスクの Ansible モジュール、およびモジュールのすべての 引数

_images/job-details-host-hostevent.png

結果を JSON 形式で表示するには、JSON タブをクリックします。タスクの出力を表示するには、標準出力 をクリックします。出力からエラーを表示するには、標準エラー をクリックします。

25.3.3. Playbook 実行の出力:

詳細 タブにアクセスし、ジョブ実行の詳細を提供します。

_images/jobs-show-job-details-for-example-job.png

実行したジョブの主な詳細は以下のとおりです。

  • ステータス: 以下のいずれかになります。

    • 保留中: Playbook の実行は作成されていますが、まだキューに入れられていないか、または開始されていません。すべてのジョブ (Playbook の実行に限らない) はシステムで実際に実行可能になるまで保留中の状態になります。Playbook の実行が準備できる状態でない理由として、依存関係が現在実行中であるか (次の手順に進む前にすべての依存関係の実行が完了していなければならない)、または設定先で実行する容量が足りないなどが挙げられます。

    • 待機中: Playbook 実行はキューに入れられており、実行を待機中です。

    • 実行中: Playbook 実行が進行中です。

    • 成功: 直前の Playbook 実行が成功しました。

    • 失敗: 直前の Playbook 実行が失敗しました。

  • ジョブテンプレート: ジョブが起動されるジョブテンプレートの名前。

  • インベントリー: このジョブを実行するために選択されたインベントリー。

  • プロジェクト: 起動したジョブに関連付けられたプロジェクトの名前。

  • プロジェクトステータス: 起動したジョブに関連付けられたプロジェクトのステータス。

  • Playbook: このジョブを起動するために使用される Playbook。

  • 実行環境: このジョブで使用される execution environment の名前。

  • コンテナーグループ: このジョブで使用されるコンテナーグループの名前。

  • 認証情報: このジョブで使用される認証情報。

  • 追加変数: ジョブテンプレートの作成時に渡される追加変数がここに表示されます。

これらの項目をクリックすると、適切な場合には該当するジョブテンプレート、プロジェクト、およびその他のオブジェクトが表示されます。

25.4. automation controller の容量判断およびジョブの影響

このセクションでは、インスタンスグループの容量とそのジョブへの影響を判断する方法を説明します。コンテナーグループについては、Automation Controller Administration Guideコンテナーの容量制限 を参照してください。

automation controller 容量システムは、インスタンスで利用可能なリソース量や、実行中のジョブのサイズ (影響 と呼ぶ) をもとに、インスタンスでいくつのジョブを実行可能か判断します。これを判断するのに使用するアルゴリズムは、2 つのアイテムだけをベースとします。

  • システムで利用可能なメモリー容量 (mem_capacity)

  • システムで利用可能な CPU 数 (cpu_capacity)

容量は、インスタンスグループにも影響があります。グループはインスタンスで構成されるので、インスタンスを複数のグループに割り当てることができます。つまり、インスタンス 1 台への影響が、他のグループ全体の容量に影響を与える可能性があります。

インスタンスグループ (インスタンス自体ではなく) は、さまざまなレベルのジョブで使用するために割り当てることができます (クラスタリング 参照)。タスクマネージャーはグラフを作成し、ジョブの実行先のグループや、起動の準備ができていないジョブに対してインスタンスグループの容量をコミットするかどうかを判断します。

最終的に、小規模な構成で、ジョブ実行に利用可能なインスタンスが 1 台しかない場合には、タスクマネージャーは、インスタンスが容量を超えていても、インスタンスでジョブが実行できるようにします。こうすることで、プロビジョニングが十分でないシステムでも、ジョブが停止しないようになります。

このように、容量および影響は、ジョブやインスタンス/インスタンスグループに対してゼロサムシステムではありません。

スライスされたジョブおよび容量への影響に関する情報は、「ジョブスライスの実行動作」を参照してください。

25.4.1. 容量アルゴリズムに向けたリソースの判断

容量アルゴリズムは、システムで同時に実行可能なフォーク数を判断するために定義します。これにより、Ansible 自体が同時に通信するシステム数を制御します。通常、automation controller システムが実行するフォーク数が増えると、並行して作業が実行され、ジョブの実行速度がをより早くなります。代わりに、システムの負荷が増加し、全体的な作業速度が遅くなってしまう可能性があります。

Automation controller は、容量の判断時に、2 つのモードで稼働します。mem_capacity (デフォルト) では、システムでメモリーがなくならないようにする一方で、CPU をオーバーコミットできます。作業の多くが CPU に依存していない場合には、このモードを選択して、フォーク数を最大化します。

25.4.1.1. メモリー対容量

mem_capacity は、フォークごとに必要なメモリー容量に対して、計算されます。内部コンポーネントのオーバーヘッドを考慮すると、これは、フォークごとに約 100 MB になります。Ansible ジョブで利用可能なメモリー容量を検討する場合、容量アルゴリズムでは、他のサービスが存在することを考慮し、メモリー 2 GB を確保します。これに関するアルゴリズムの公式は以下のようになります。

(mem - 2048) / mem_per_fork

以下に例を示します。

(4096 - 2048) / 100 == ~20

このように、メモリー 4GB のシステムは、フォーク 20 個分実行することができます。mem_per_fork の値は、設定値 (または環境変数) SYSTEM_TASK_FORKS_MEM (デフォルト値は 100) を設定して制御できます。

25.4.1.2. CPU 対容量

頻繁に、Ansible のワークロードが CPU に大きく依存する場合があります。このような場合には、同時の実行するワークロードを減らして、タスクの実行速度を高め、これらのジョブの平均完了時間を短縮することができる場合があります。

mem_capacity アルゴリズムでフォークごとに必要なメモリー容量を使用するように cpu_capacity アルゴリズムも、フォークごとに必要な CPU リソース数に着目します。このベースラインの値として、コアごとのフォーク数が 4 つとなります。CPU のアルゴリズムの公式は以下のとおりです。

cpus * fork_per_cpu

たとえば、4 つのコアが搭載されているシステムの場合:

4 * 4 == 16

fork_per_cpu の値は、設定値 (または環境変数) SYSTEM_TASK_FORKS_CPU (デフォルト値は 4) を設定して制御できます。

25.4.2. ジョブが影響を与える容量

容量を選択する場合に、各ジョブタイプがどのように容量に影響を与えるかを理解することが重要です。

Ansible におけるフォークの意味を理解しておくと役に立ちます (https://www.ansible.com/blog/ansible-performance-tuning の Know Your Forks セクションを参照)。

Ansible のデフォルトのフォーク値は 5 ですが、automation controller では実際には 5 台未満のシステムに対して実行していることを認識しているため、実際の同時並行処理の値は 5 よりも少なくなります。

ジョブ実行時に、Ansible の親プロセスに対応するために、automation controller はフォークの選択数に 1 つ追加します。そのため、フォークの値が 5 のシステム 5 台に対して、Playbook を実行する場合は、ジョブの影響に関する実際のフォーク値が 6 になります。

25.4.2.1. 自動コントローラーのジョブタイプの影響

ジョブとアドホックのジョブは、上記のモデル (フォーク + 1) を採用します。ジョブテンプレートでフォークの値を設定する場合は、ジョブの容量値は指定のフォーク最小値、使用するホスト数に 1を加えた数値になります。1 を加えることで、親 Ansible プロセスに対応します。

インスタンスの容量で、どのジョブを特定のインスタンスに割り当てるかを決定します。フォークの値が高く指定されている場合には、ジョブとアドホックコマンドは、より多くの容量を使用します。

他のジョブタイプへの影響は固定されています。

  • インベントリーの更新: 1

  • プロジェクトの更新: 1

  • システムジョブ: 5

ジョブテンプレートにフォークの値を設定しない場合には、ジョブは Ansible のデフォルトのフォーク値 4 を使用します。Ansible のデフォルト値はフォーク 5 ですが、ジョブのホストが 5 台未満の場合には、フォークの使用数は少なくなります。一般的に、フォークの値に、システムの機能より高い数値を設定すると、メモリーが足りなくなったり、CPU をオーバーコミットしたりする問題が発生する可能性があります。個別のシステムではそれほど容量がないにも拘わらず、Playbook でフォーク 1000 個を使用する場合には、システムのサイズが小さすぎたり、パフォーマンスやリソースの問題のリスクが発生したりします。

25.4.2.2. 適切な容量の選択

CPU バインドまたはメモリーバインドの容量制限から容量を選択するのは、実質的には、フォーク数の最小数または最大数を選択していることになります。上記の例では、CPU の容量でフォーク数を最大 16 個許容し、メモリー容量では 20 個許容できます。システムによっては、これらの差異は大きくなる可能性があり、多くの場合にこれらの 2 つの間でバランスを取っていくと良いでしょう。

インスタンスフィールド capacity_adjustment では、どちらをどの程度考慮するかを選択できます。これは、0.0 から 1.0 の値で表します。値を 1.0 に設定すると、最大値が使用されます。上記の例では、メモリー容量となるので、フォークの値を 20 が選択されます。値を 0.0 に設定すると、最小値が使用されます。また、0.5 は 2 つのアルゴリズムを 50/50 の割合で使用することになり、フォーク数は 18 になります。

16 + (20 - 16) * 0.5 == 18

ユーザーインターフェースで容量を表示または編集するには、インスタンスグループの インスタンス タブを選択します。

_images/instance-group-instances-capacity-callouts.png

25.5. ジョブブランチの上書き

プロジェクトでは、ブランチ、タグ、または参照が scm_branch フィールドで指定されます。以下で示されているように、これらは、プロジェクトの詳細のフィールドで指定された値で表示されます。

_images/projects-create-scm-project-branching-emphasized.png

プロジェクトには、「ブランチの上書きを許可する」オプションがあります。このオプションを選択すると、プロジェクト管理者は、そのプロジェクトを使用するジョブテンプレートに対して、ブランチの選択を委任できます (プロジェクトの use_role のみが必要)。

_images/projects-create-scm-project-branch-override-checked.png

25.5.1. ソースツリーのコピー動作

すべてのジョブ実行には、独自のプライベートデータディレクトリーがあります。このディレクトリーには、このジョブが実行されている指定された scm_branch のプロジェクトソースツリーのコピーが含まれています。ジョブは、プロジェクトフォルダーを自由に変更し、実行中にそれらの変更を自由に使用できます。このフォルダーは一時的なものであり、ジョブ実行の終了時にクリーンアップされます。

クリーニング を選択している場合、automation controller は、git および Subversion に関連した各 Ansible モジュールの force パラメーターを使用して、リポジトリーのローカルコピーにある変更ファイルを破棄します。

_images/projects-create-scm-project-clean-checked.png

25.5.2. プロジェクトのリビジョンの動作

一般に、プロジェクトの更新中、デフォルトブランチのリビジョン (プロジェクトの SCM ブランチ フィールドで指定) が更新時に保存され、そのプロジェクトを使用するジョブではそのリビジョンが使用されます。ジョブでデフォルト以外の SCM ブランチ (コミットハッシュ値またはタグではない) を使用した場合は、ジョブの開始前に最新のリビジョンがソースコントロールリモートから即時に取得されます。このリビジョンは、ジョブおよびそれぞれのプロジェクト更新の ソースコントロールの改訂 フィールドに表示されます。

_images/jobs-output-branch-override-example.png

そのため、デフォルト以外のブランチではオフラインジョブを実行できません。タグを使用するか、ハッシュをコミットを使用して、ジョブが確実にソースコントロールからの静的バージョンを実行するようにします。プロジェクトの更新では、すべてのブランチのリビジョンは保存されず、プロジェクトのデフォルトブランチのみが保存されます。

** SCM ブランチ** フィールドは検証されないため、プロジェクトを更新して有効であることを確認する必要があります。このフィールドが指定されたり、要求されたりした場合には、ジョブテンプレートの Playbook フィールドは検証されず、 ジョブテンプレートを起動して、必要とされる Playbook が存在するかを確認する必要があります。

25.5.3. Git Refspec

SCM Refspec フィールドは、更新がリモートからダウンロードする必要がある追加の参照を指定します。以下に例を示します。

  1. refs/*:refs/remotes/origin/*: リモートのリモートを含む、すべての参照を取得

  2. refs/pull/*:refs/remotes/origin/pull/* (GitHub 専用): すべてのプル要求に対して、すべての参照を取得

  3. refs/pull/62/head:refs/remotes/origin/pull/62/head: 対象の GitHub プル要求に対して、参照を取得

プロジェクトの規模が大きく、本書で紹介する 1 例目と 2 例目を使用する場合には、パフォーマンスへの影響を考慮する必要があります。

SCM Refspec パラメーターは、プロジェクトブランチの可用性に影響するものであり、他の場合には利用できない参照へのアクセスを許可できます。上記の例では、ユーザーは SCM ブランチ からのプル要求を指定できますが、これは SCM Refspec フィールドがなければ不可能です。

Ansible git モジュールはデフォルトで refs/heads/* を取得します。つまり、SCM Refspec が空の場合には、プロジェクトのブランチとタグ (およびその中のコミットハッシュ) を SCM ブランチとして使用できます。SCM Refspec フィールドで指定された値は、オーバーライドとして使用できる SCM ブランチ フィールドに影響します。プロジェクトの更新 (任意のタイプ) は、追加の git fetch コマンドを実行して、リモートからその refspec をプルします。

たとえば、1 番目または 2 番目の refspec の例でブランチの上書きを許可するプロジェクトを設定したとします -> ** SCMブランチ** を要求するジョブテンプレートでこれを使用します -> ジョブテンプレートを起動すると、新しいプル要求が作成された場合に、ブランチ pull/N/head が指定されます -> ジョブテンプレートは、指定された GitHub プル要求の参照に対して実行されます。

Ansible git モジュールの詳細は、https://docs.ansible.com/ansible/latest/modules/git_module.html を参照してください。