【AAP】ansible.controllerコレクション使ってワークフロージョブテンプレートを作る

この記事はエーピーコミュニケーションズ Advent Calendar 2024 24日目のエントリです。

はじめに

AAPの設定をAnsibleから行えるansible.controllerコレクションでは、認証情報やジョブテンプレートはもちろん、ワークフロージョブテンプレートも作成することができます。
今回はこのコレクションを使ってワークフロージョブテンプレートを作成してみます。

環境

AWS EC2: m5.large
ansible-core: 2.15.13
AAP Version: 2.5

コレクションのインストール

ansible.controllerコレクションはデフォルトではインストールできないので下準備をします。
具体的にはansible-galaxyコマンドでコレクションをインストールする際の参照先を切り替える作業を実施します。

参考：

接続用トークンの取得

以下のページにログインして[Ansible] -> [Automation Hub] -> [Connect to Hub]に移動します。

「トークンの読み込み」をクリックし、表示されるトークンを控えておく。

ansible.cfgの設定

ansible-galaxyの参照先の変更はAnsibleの設定ファイルであるansible.cfgで行います。
ansible.cfgに以下を追記します。(ない場合は作成)
<TOKEN>のところにAutomation Hubで取得したトークンを張る。

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/content/published/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<TOKEN>

ansible.controllerのインストール

下準備が終わったのでコレクションのインストールします。
インストール方法はシンプルにansible-galaxy collection install <コレクション名>でOK。
コレクションのページに書いてあるコマンドを実行。

ansible-galaxy collection install ansible.controller

$ ansible-galaxy collection install ansible.controller
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://console.redhat.com/api/automation-hub/v3/plugin/ansible/content/published/collections/artifacts/ansible-controller-4.6.2.tar.gz to /home/ec2-user/.ansible/tmp/ansible-local-3845h2typ3zt/tmpwc5w_9mf/ansible-controller-4.6.2-hf4ecdq0
Installing 'ansible.controller:4.6.2' to '/home/ec2-user/.ansible/collections/ansible_collections/ansible/controller'
ansible.controller:4.6.2 was installed successfully

$ ansible-galaxy collection list | grep ansible.controller
ansible.controller            4.6.2  

無事インストール完了。

※AAP2.5からAPIのURLが変わっているので、インストールするコレクションのバージョンは使用するAAPやコントローラのバージョンに合わせる必要があります。
コレクションのバージョンを指定してインストールする場合は ansible-galaxy collection install ansible.controller==4.6.3のように指定します。

インベントリ等について

ジョブテンプレートを動かすためにはインベントリやプロジェクトなどが必要ですが、今回の主題はワークフロージョブテンプレートの作成なためここはスキップします。
AAPインストール時から存在するDemo InventoryやDemo Projectを使ってジョブテンプレートを作ります。

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

ワークフロージョブテンプレートはジョブテンプレートを数珠繋ぎにするものなのでまずはジョブテンプレートを作成。
今回はジョブテンプレートもコレクションを使って作ってみます。
ジョブテンプレートを作成するためにはjob_templateモジュールを使用します。
例としてはこんな形。

---
- name: create job template
  ansible.controller.job_template:
    name: "job template name"
    job_type: "run"
    inventory: "Inventory name"
    project: "Project name"
    playbook: "Playbook name"
    state: "present"
    execution_environment: "ee name"

GUIからジョブテンプレートを作成する時に指定するものをオプションで与えているだけなので分かりやすい。

一度動作確認

まだ本題に入ってないですが、ここで一度AAPへの接続確認も兼ねて動作確認をしておきます。
使うPlaybookは以下。

---
- hosts: localhost
  connection: local
  gather_facts: false

  environment:
    CONTROLLER_HOST: https://localhost
    CONTROLLER_USERNAME: admin
    CONTROLLER_PASSWORD: hogefuga
    CONTROLLER_VERIFY_SSL: false


  tasks:
    - name: create job template
      ansible.controller.job_template:
        name: "job_template_1"
        job_type: "run"
        inventory: "Demo Inventory"
        project: "Demo Project"
        playbook: "hello_world.yml"
        state: "present"
        credential: "Demo Credential"
        execution_environment: "Default execution environment"

環境変数で定義しているAAPへの接続情報が平文なのは分かりやすさ重視ということで...

実行。

ansible-playbook create_job_template.yml 

PLAY [localhost] ****************************************************

TASK [create job template] *****************************************
changed: [localhost]

PLAY RECAP ********************************************************
localhost                  : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

成功。

AAPから確認してみます。

作成されていることが確認できました。

ワークフロージョブテンプレートを作る

さきほど書いたタスクで作成されるジョブテンプレートを元にしてワークフロージョブテンプレートを作ります。
使用するのはworkflow_job_templateとworkflow_job_template_nodeモジュールの2つ。
簡単にそれぞれを説明すると以下のようになります。

• workflow_job_template
  ワークフロージョブテンプレートそのものを作成するためのモジュール。

• workflow_job_template_node
  既にあるワークフロージョブテンプレートのノードの編集をするためのモジュール。

なお、workflow_job_templateモジュールだけでもノードを記述することができますが、専用モジュールであるworkflow_job_template_nodeを使った方がより(個人的には)シンプルに記述できます。

ワークフローを作るPlaybook

ほぼExampleのままですがこんな感じ。
ノードを直列に3つ繋ぎ、真ん中に承認ノードを配置したワークフローができあがる。

- name: Create a workflow job template　    # ワークフロージョブテンプレートを作成
  ansible.controller.workflow_job_template:
    name: my-workflow-job-template
    organization: Default

- name: Create 1st node                     # 1つ目のノードを作成
  ansible.controller.workflow_job_template_node:
    identifier: my-first-node
    workflow_job_template: my-workflow-job-template
    unified_job_template: job_template_1
    organization: Default

- name: Create 2nd approval node           # 2つ目のノードを作成(承認ノード)
  ansible.controller.workflow_job_template_node:
    identifier: my-second-approval-node
    workflow_job_template: my-workflow-job-template
    organization: Default
    approval_node:
      description: "Do this?"
      name: my-second-approval-node
      timeout: 3600

- name: Create 3rd node                    # 3つ目のノードを作成
  ansible.controller.workflow_job_template_node:
    identifier: my-third-node
    workflow_job_template: my-workflow-job-template
    unified_job_template: job_template_2
    organization: Default

- name: Link 1st node to 2nd Approval node # 1つ目のノードが成功したら2つ目のノードを実行するよう接続
  ansible.controller.workflow_job_template_node:
    identifier: my-first-node
    workflow_job_template: my-workflow-job-template
    organization: Default
    success_nodes:
      - my-second-approval-node

- name: Link 2nd Approval Node 3rd node    # 2つ目のノードが成功したら3つ目のノードを実行するよう接続
  ansible.controller.workflow_job_template_node:
    identifier: my-second-approval-node
    workflow_job_template: my-workflow-job-template
    organization: Default
    success_nodes:
      - my-third-node

実行するとこんなワークフローが作成されます。

ちなみに、さきほど実行したPlaybookでノードの接続を定義したタスクがないと以下のようなすべてのノードがStartに接続されるワークフローが出来上がります。

分岐させてみる

さきほどのものは直列でしたが成功か失敗かで分岐する形にしてみます。
失敗した際、実行させるようにしたいため、success_nodesではなくfailure_nodesで繋ぎます。
以下のタスクをさきほどのPlaybookに追記します。

- name: Create 4th node
  ansible.controller.workflow_job_template_node:
    identifier: my-Fourth-node
    workflow_job_template: my-workflow-job-template
    unified_job_template: job_template_3
    organization: Default

- name: Link 2nd Approval Node 4th node
  ansible.controller.workflow_job_template_node:
    identifier: my-second-approval-node
    workflow_job_template: my-workflow-job-template
    organization: Default
    failure_nodes:
      - my-Fourth-node

生成物。

承認ノードで許可された場合と拒否された場合で処理を変えるようにできた。

一応動作確認

承認するVer.

拒否するVer.

動作確認OK

おわりに

今回はansible.controllerコレクションを使いAAPのワークフロージョブテンプレートを作成してみました。
今回はワークフロージョブテンプレートにフォーカスしましたが、認証情報やプロジェクトなどAAPの設定はほとんどできるので、よく使う設定をPlaybookとして残しておけば初期設定が簡単できるようになります。

参考(再掲)

おまけ

間に承認ノードを入れた3ノード直列のワークフローをworkflow_job_templateだけで作ってみる。

- name: create workflow job template
  ansible.controller.workflow_job_template:
    state: present
    name: "demo_workflow_job_template"
    workflow_nodes:
      - identifier: my-first-node
        unified_job_template:
          name: "job_template_1"
          type: job_template
        related:
          success_nodes: 
            - identifier: my-second-approval-node

      - identifier: my-second-approval-node
        unified_job_template:
          description: "Do this?"
          timeout: 3600
          name: approval
          type: workflow_approval              
        related:
          success_nodes:
            - identifier: my-third-node

      - identifier: my-third-node
        unified_job_template:
          name: "job_template_2"
          type: job_template

このタスクにより作成されるワークフロージョブテンプレートはこちら。

同じものが作成されるように書いたので当然ですが、同じワークフローが作成されます。
「workflow_job_templateだけで書くよりworkflow_job_template_nodeを使った方がシンプルに書けるよ」と思ってんですが、別にこっちでも割とシンプルに書けますね。。。
もっと複雑なワークフローだと話は変わるかもしれません。