てくなべ (tekunabe)

ansible / network / automation

[Ansible] Ansible Tower / AWX の API で情報取得する汎用 lookup plugin の tower_api

はじめに

Ansible には、Ansible Tower や AWX の情報を取得したり、設定を行うモジュールが多数あります。

docs.ansible.com

バージョンを追うごとに増えていて、対応範囲が広がっていますが、それでもまだのものもあります。

そんなときに便利そうなのが、tower_api lookup plugin です。CHANGELOG には見当たりませんでしたが、awx.awx collection 14.0 で追加されたようです。

おそらくGETのみとなりますが、モジュールがなくてもAPI のエンドポイントやフィルターを直接指定して、情報を取得できます。

モジュールがない場合の代替手段は、uri モジュール あたりになりますが、それよりは楽に URL を組み立てられたりするかと思います。

この記事では簡単なサンプルで説明します。

  • 動作確認環境
    • Ansible 2.9.14
    • AWX 15.0

サンプル Playbook

ここでは、ワークフロージョブの結果を取得して画面に表示する Playbook を作成します。

ジョブであれば、tower_job_list モジュール が利用できますが、ワークフロージョブに対応するモジュールは現状ないようです。

そのため、awx.awx.tower_api lookup plugin を利用します。

---
- hosts: awx01
  gather_facts: false
  connection: local

  tasks:
    - name:
      debug:
        msg: "{{ res }}"
      vars:
        res: "{{ query('awx.awx.tower_api', 'workflow_jobs', query_params={'id': 38}, 
                  host='http://10.0.0.90',username='admin', password='password') }}"

queryawx.awx.tower_api を指定します。

次の引数で、対象の API エンドポイントを指定します。 予め、実機の http://tower/api/v2/ や、API リファレンスなどで調べておきます。

ワークフロージョブの実行結果(テンプレートではなく)の場合は、workflow_jobs です。

query_params には、フィルターを指定します。なくても構いません。ここでは、 id38 のものと指定しています。利用できるフィルターは、API リファレンスなどを参照してください。

他は、接続や認証情報です。サンプルのためベタ書きしています。後述の環境変数で指定する方法がうまくいけば指定不要になるでしょう。

すべてのオプショの説明は awx.awx.tower_api lookup plugin のページを参照してください。

接続・認証情報についての補足

なお、awx.awx.tower_api lookup plugin のページには TOWER_HOST などの環境変数でも指定できると記載がありますが、私が以下のように試したところ反映されずに、デフォルト設定で接続(localhostへ)しようとしていました。lookup plugin ではなく、他の tower_* モジュールではこの方法でうなくいったのですが。

---
- hosts: awx01
  gather_facts: false
  connection: local
  environment:   # うまくいかなかった指定例
    TOWER_USERNAME: admin
    TOWER_PASSWORD: password
    TOWER_HOST: http://10.0.0.90

  tasks:
    # ...(略)... awx.awx.tower_api 利用タスク

実行

Playbook を実行します。

$ANSIBLE_KEEP_REMOTE_FILES=1 ansible-playbook -i inventory.ini job.yml     

PLAY [all] ************************************************************************************************************

TASK [debug] **********************************************************************************************************
ok: [lolcahost] => {
    "msg": [
        {
            "allow_simultaneous": false,
            "canceled_on": null,
            "created": "2020-10-18T16:17:54.013277Z",
            "description": "",
            "elapsed": 8.067,
            "extra_vars": "{\"wf_extra\": \"val1\", \"wf_extra_list\": [111, 222, 333], \"wr_survey_var1\": \"ttttttttt\"}",
            "failed": false,
            "finished": "2020-10-18T16:18:02.282742Z",
            "id": 38,
            "inventory": null,
            "is_sliced_job": false,
            "job_explanation": "",
            "job_template": null,
            "launch_type": "manual",
            "limit": null,
            "modified": "2020-10-18T16:17:54.218539Z",
            "name": "wf_test",
            "related": {
                "activity_stream": "/api/v2/workflow_jobs/38/activity_stream/",
                "cancel": "/api/v2/workflow_jobs/38/cancel/",
                "created_by": "/api/v2/users/1/",
                "labels": "/api/v2/workflow_jobs/38/labels/",
                "modified_by": "/api/v2/users/1/",
                "notifications": "/api/v2/workflow_jobs/38/notifications/",
                "relaunch": "/api/v2/workflow_jobs/38/relaunch/",
                "unified_job_template": "/api/v2/workflow_job_templates/8/",
                "workflow_job_template": "/api/v2/workflow_job_templates/8/",
                "workflow_nodes": "/api/v2/workflow_jobs/38/workflow_nodes/"
            },
            "scm_branch": null,
            "started": "2020-10-18T16:17:54.215745Z",
            "status": "successful",
            "summary_fields": {
                "created_by": {
                    "first_name": "",
                    "id": 1,
                    "last_name": "",
                    "username": "admin"
                },
                "labels": {
                    "count": 0,
                    "results": []
                },
                "modified_by": {
                    "first_name": "",
                    "id": 1,
                    "last_name": "",
                    "username": "admin"
                },
                "unified_job_template": {
                    "description": "",
                    "id": 8,
                    "name": "wf_test",
                    "unified_job_type": "workflow_job"
                },
                "user_capabilities": {
                    "delete": true,
                    "start": true
                },
                "workflow_job_template": {
                    "description": "",
                    "id": 8,
                    "name": "wf_test"
                }
            },
            "type": "workflow_job",
            "unified_job_template": 8,
            "url": "/api/v2/workflow_jobs/38/",
            "webhook_credential": null,
            "webhook_guid": "",
            "webhook_service": "",
            "workflow_job_template": 8
        }
    ]
}

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

無事に表示されました。

AWX の画面でいうとこの画面に相当する情報です。

f:id:akira6592:20201019094348p:plain
ワークフロージョブ実行結果画面

おわりに

仮に、対応するモジュールがあったとしても、情報取得するだけあれば、わざわざ1タスクにする必要がない awx.awx.tower_api lookup plugin は便利かもしれません。