Documentation

21. ワークフロー

ワークフローを使うと、インベントリー、Playbook、またはパーミッションを共有または共有しない可能性のある一連の個別ジョブテンプレート (またはワークフローテンプレート) を設定することができます。ただし、ワークフローには、ジョブテンプレートと同様に、「管理者」および「実行」パーミッションがあります。ワークフローでは、単一ユニットとしてリリースプロセスに含まれていたジョブすべてを追跡するタスクを実行します。

ジョブまたはワークフローテンプレートは、ノードと呼ばれるグラフのような構造を使って相互に連携します。これらのノードには、ジョブ、プロジェクト同期、またはインベントリー同期などが含まれます。ジョブテンプレートは異なるワークフローの一部となることも、同じワークフローで複数回使用することもできます。グラフ構造のコピーは、ワークフローの起動時にワークフロージョブに保存されます。

以下の例では、ジョブ、プロジェクト同期、インベントリー同期のワークフローのほかに、ワークフロージョブについて紹介します。

_images/wf-node-all-scenarios-wf-in-wf.png

ワークフローが実行されると、リンクされたノードのテンプレートからジョブが起動します。プロンプト方式 (prompt-driven) のフィールド (job_type、job_tags、skip_tags、limit) が含まれるジョブテンプレートにリンクされているノードには、このようなフィールドが含まれる可能性があり、起動時にプロンプトが表示されません。デフォルト設定がない場合には、プロンプト表示が可能な認証情報/インベントリーを含むジョブテンプレートを、ワークフローに含めることができません。

21.1. ワークフローのシナリオおよび留意事項

ワークフローの構築時に以下のシナリオを考慮してください。

  • root ノードはデフォルトでは ALWAYS (常時) に設定されており、編集できません。

_images/wf-root-node-always.png

  • ノードには複数の親を含めることが可能で、子には「Success (成功)」、「Failure (失敗)」または「Always (常時)」の状態にリンクすることが可能です。「Always (常時)」の場合、状態は「Success (成功)」でも「Failure (失敗)」でもありません。状態はワークフロージョブテンプレートのレベルではなく、ノードのレベルで適用されます。ワークフロージョブは、取り消されないか、エラーが生じない場合にのみ「Success (成功)」とマークされます。

_images/wf-sibling-nodes-all-edge-types.png

  • 以下の例のように、ワークフロー内のジョブまたはワークフローテンプレートを削除した場合に、以前に削除済みのジョブやワークフローに連携されていたノードが自動的にアップストリームに接続され、エッジタイプが保持されます。

_images/wf-node-delete-scenario.png

  • 複数のジョブを 1 つに収束する収束ワークフローを使用できます。このシナリオでは、次の例に示すように、次のジョブが実行する前に、いずれかのジョブまたはすべてのジョブを完了しておく必要があります。

    _images/wf-node-convergence.png

以下の例では、automation controller は最初の 2 つのジョブテンプレートを並行して実行します。指定通りに終了して成功すると、3 番目のダウンストリーム (convergence node) が発生します。

  • インベントリーと Survey のプロンプトは、ワークフロージョブテンプレートに含まれるワークフローノードに適用されます。

  • API から起動する場合に、get コマンドを実行すると、警告の一覧が表示され、欠落しているコンポーネントが強調表示されます。ワークフロージョブテンプレートの基本的なワークフローは以下に示す通りです。

_images/workflow-diagram.png

  • いくつかのワークフローを同時に起動し、ワークフローの起動時のスケジュールを設定することができます。ジョブテンプレートと同様に、ジョブの完了時など、ワークフローに通知を設定することができます。

注釈

Job slicing is intended to scale job executions horizontally. Enabling job slicing on a job template divides an inventory to be acted upon in the number of slices configured at launch time and then starts a job for each slice.

It is expected that the number of slices will be equal to or less than the number of controller nodes. Setting an extremely high number of job slices (e.g., thousands), while allowed, can cause performance degradation as the job scheduler is not designed to schedule simultaneously thousands of workflow nodes, which are what the sliced jobs become.

  • 再帰的なワークフローを構築することができますが、automation controller がエラーを検出した場合には、ネスト化されたワークフローが実行しようとしたタイミングでワークフローは停止します。

  • サブワークフローのジョブで収集されたアーティファクトは、ダウンストリームのノードには渡されません。

  • インベントリーは、ワークレベルとして設定することもインベントリーの起動プロンプトとして設定することも可能です。

  • 起動時に、ask_inventory_on_launch=true が指定されているワークフロー内のジョブテンプレートはすべて、ワークフローレベルのインベントリーを使用します。

  • インベントリーを求めないジョブテンプレートでは、ワークフローインベントリーを無視し、独自のインベントリーに対して実行されます。

  • ワークフローがインベントリーを求める場合には、スケジュールおよび他のワークフローノードでそのインベントリーを提供することができます。

  • ワークフローの収束シナリオでは、set_stats データが定義なしの状態でマージされるので、一意のキーを設定することを推奨します。

21.2. 追加変数

ジョブテンプレートと同様に、ワークフローは Survey を使用して、extra_vars というワークフローの Playbook で使用される変数を指定します。Survey 変数はワークフロージョブテンプレートで定義される extra_vars defined と組み合わされ、ワークフロージョブ extra_vars に保存されます。ワークフロージョブの extra_vars は、ワークフロー内のジョブの生成時にジョブテンプレート変数に組み合わされます。

ワークフローは、3 つの追加変数を除き、ジョブテンプレートと同じ変数の順序の動作 (階層) を使用します。本書のジョブテンプレートの章の 追加変数 セクションの変数の順序の階層について参照してください。3 つの追加の変数には以下が含まれます。

_images/Architecture-Tower_Variable_Precedence_Hierarchy-Workflows.png

ワークフローに含まれるワークフローでは、同様の変数の優先順位を使用します。survey の一部として定義されるか、具体的に求められた場合にのみ、変数を敬称します。

ワークフローの extra_vars のほかにも、ワークフローの一部として実行されるジョブおよびワークフローは、ワークフローの親ジョブに含まれるアーティファクト辞書の変数を継承できます (また、ブランチの祖先のアップストリームと組み合わされます)。これらは、set_stats Ansible module 以降で定義できます。

Playbook で set_stats モジュールを使用すると、別のジョブでダウンストリームで使用できる結果を出す生成できます。たとえば、ユーザーに対し、統合の実行の成功または失敗について通知することができます。この例では、アーティファクトを渡すためにワークフローに組み合わせることのできる 2 つの Playbook を示します。

  • invoke_set_stats.yml: ワークフローの最初の Playbook

---
- hosts: localhost
  tasks:
    - name: "Artifact integration test results to the web"
      local_action: 'shell curl -F "file=@integration_results.txt" https://file.io'
      register: result

    - name: "Artifact URL of test results to Workflows"
      set_stats:
        data:
          integration_results_url:  "{{ (result.stdout|from_json).link }}"

  • use_set_stats.yml: ワークフローの 2 番目の Playbook

---
- hosts: localhost
  tasks:
    - name: "Get test results from the web"
      uri:
        url: "{{ integration_results_url }}"
        return_content: true
      register: results

    - name: "Output test results"
      debug:
        msg: "{{ results.content }}"

set_stats モジュールはこのワークフローを以下のように処理します。

  1. 統合の結果の内容 (例: 以下の integration_results.txt) がまず web にアップロードされます。

the tests are passing!

  1. 次に invoke_set_stats Playbook により、set_stats が起動すると、アップロードされた integration_results.txt の URL が作成され、Ansible 変数「integration_results_url」に渡されます。

  2. ワークフローの 2 つ目の Playbook は、Ansible 追加変数「integration_results_url」を使用します。これは、uri モジュールを使用して web に対して呼び出しを実行し、直前のジョブテンプレートジョブでアップロードされたファイルの内容を取得します。次に、取得したファイルの内容を単純に出力します。

_images/wf-templates_set_stats.png

注釈

アーティファクトを機能させるには、set_stats モジュールの per_host = False というデフォルト設定をそのまま使用してください。

21.3. ワークフローの状態

ワークフロージョブには以下の状態が設定されます (「失敗」状態は含まれなし)。

  • 待機中

  • 実行中

  • 成功 (終了)

  • 取り消し

  • エラー

  • 失敗

ワークフローのスキームでは、ジョブを取り消すとブランチが取り消され、ワークフロージョブを取り消すとワークフロー全体が取り消されます。

21.4. ロールベースのアクセス制御

ワークフロージョブテンプレートの編集や削除には、管理者ロールが必要です。ワークフロージョブテンプレートを作成するには、組織管理者またはシステム管理者でなければなりません。ただし、パーミッションのないジョブテンプレートが含まれるワークフロージョブテンプレートを実行することは可能です。プロジェクトと同様に、組織管理者は空のワークフローを作成してから、「admin_role」を管理者権限を持たないユーザーに割り当てると、それらのユーザーは追加のアクセスを委任したり、グラフを作成したりできます。ジョブテンプレートをワークフロージョブテンプレートに追加するには、ジョブテンプレートへの実行アクセスがなればなりません。

特定のユーザーに付与されるパーミッションの種類に応じて、複製コピーを作成したり、ワークフローを再起動する機能などの他のタスクを実行することもできます。通常は、再起動やコピーの作成を実行する前に (ジョブテンプレートなどの) ワークフローで使用されるすべてのリソースに対するパーミッションが必要になります。

このセクションに記載のタスクの実行に関する情報は、「Administration Guide」を参照してください。