AWX APIで構築自動化 / 開発者向けブログ・イベント

こんにちは、GMOインターネット長谷川です。
今回は昨年2021/11/26に開催されたGMO Developers Night CloudNativeLT＆座談会で紹介した、AWX APIの実際の仕様等をより詳しくお伝えしていこうと思います。

GMO Developers Night#30 / GMOインターネットグループ CloudNative LT&座談会

今回お話する部分

AWX APIではInventory登録、Job登録（playbook登録）、workflow登録など
様々な処理を行えるAPIがありますが今回はJob登録の自動化に絞って
お伝えしていきます。

AWXとは

AWX provides a web-based user interface, REST API, and task engine built on top of Ansible. It is one of the upstream projects for Red Hat Ansible Automation Platform.
引用元 : https://github.com/ansible/awx

簡単に言えば、web画面＆APIの付いたAnsibleの管理、実行環境ということです。

AWXで解決したい課題

実行時のオペレーション
登録時の負担

大きく上記の2つです。1つずつ説明していきます。

実行時のオペレーション

業務で実際にAnsibleを使った自動化を行うと、playbookの作成者と実行者が異なる場合があります。

playbookのアップデートが適切に実行者のplaybookに反映されていない。
複数のパラメータを付けて実行する必要がある。

このような場合にはオペレーションによって異なった設定が入ってしまう可能性があります。

登録時の負担

業務では年間数百を超えるplaybookをAWXに登録場面があります。
その際にいくつもの設定項目を人間が埋めていくのは現実的ではありませんし、
ミスも発生する可能性があります。

上記の課題はAPIによる登録の自動化とAWXに統一された実行環境を提供することで解決できます。

AWXのAPIを早速使っていきましょう（準備体操）

まずはtokenの取得を行います。
取得方法としてはawx-cliでも取れますが、ここはシンプルにcurlで取得していきます。

USER、PASSWORD、IPは適宜変えていきましょう。

curl -ku USER:PASSWORD -H "Content-Type: application/json" \
-X POST -d '{"description":"AWX", "application":null, "scope":"write"}' \
http://IP/api/v2/users/1/personal_tokens/ | jq -r .token

API経由でJob登録

ここからはPythonを使って登録作業の自動化を進めていきます。

import requests
import pprint
import json

ENDPOINT = "http://***.***.***.***"
TOKEN = "***"

def createJobTemplate(endpoint, token):
    headers = {
        "User-agent": "python-awx-client",
        "Content-Type": "application/json",
        "Authorization": "Bearer {}".format(token)
    }
    uri = str(endpoint) + "/api/v2/job_templates/"
    payloads = {
        # ここから下のask_*はGUIでJob実行を起動した際に
        # 起動プロンプトとして起動させるかを設定します
        "ask_job_type_on_launch": "true",
        "ask_scm_branch_on_launch": "false",
        "ask_diff_mode_on_launch": "false",
        "ask_variables_on_launch": "false",
        "ask_limit_on_launch": "false",
        "ask_tags_on_launch": "false",
        "ask_skip_tags_on_launch": "false",
        "ask_verbosity_on_launch": "false",
        "ask_inventory_on_launch": "false",
        "ask_credential_on_launch": "false",
        "survey_enabled": "false",
        # become（権限昇格可能）かどうかを設定します。
        "become_enabled": "true",
        "diff_mode": "false",
        "allow_simultaneous": "false",
        # playbookで使用する仮想環境のパスを指定します。
        "custom_virtualenv": "/opt/my-envs/custom-venv3/",
        "description": "VMの構築用playbook",
        # playbookの実行する際のInventoryをIDで指定します。
        "inventory": 15,
        # 実行時のsliceを指定します。（同時実行数）
        "job_slice_count": 1,
        # 起動時のjob_typeの指定
        # "run" -> 実行, "check" -> ドライラン
        "job_type": "check",
        # オーガナイゼーションのIDを指定します。
        # defaultはID=1となります。
        "organization": 1,
        # Jobテンプレートに名前を付けます
        "name": "[API]_CreateVM",
        # 登録するplaybookの場所を指定します。
        "playbook": "module/playbook_vm_create.yaml",
        # AWXに同期済みのプロジェクトIDを指定（登録playbookのあるもの）
        "project": 22,
        # Git等のSCMでplaybook同期している場合はブランチの指定も出来ます。
        "scm_branch": "master",
        "use_fact_cache": "true",
        "webhook_service": "",
        "webhook_credential": None,
    }
    requests.post(uri, data=json.dumps(payloads), headers=headers)

createJobTemplate(ENDPOINT, TOKEN):

各パラメータについて詳しく説明していきます。

        # ここから下のask_*はGUIでJob実行を起動した際に
        # 起動プロンプトとして起動させるかを設定します
        "ask_job_type_on_launch": "true",

運用的には人が行っている作業を徐々に自動化していくことも考えられ、
人が操作する際に実行時のプロンプト起動は安全性という意味で付けています。
実際に指定すると以下のように起動前にパラメータの変更が可能になります。

        # playbookで使用する仮想環境のパスを指定します。
        "custom_virtualenv": "/opt/my-envs/custom-venv3/",

playbookの中には追加でpipによるパッケージのインストールが必要な場合もあり、
仮想環境にパッケージを導入してplaybookを実行するよう指定する必要があります。
AWXはAnsible Towerと互換性が有るので仮想環境の作成は以下が参考になります。
https://docs.ansible.com/ansible-tower/3.4.3/html_ja/upgrade-migration-guide/virtualenv.html

        # playbookの実行する際のInventoryをIDで指定します。
        "inventory": 15,

ここではplaybookの実行時に使うInventoryをIDで指定しています。
Inventory IDの取得は今回の記事では紹介していませんが、APIでの取得の自動化も可能なので是非お試しください。

        # 登録するplaybookの場所を指定します。
        "playbook": "module/playbook_vm_create.yaml",
        # AWXに同期済みのプロジェクトIDを指定（登録playbookのあるもの）
        "project": 22,
        # Git等のSCMでplaybook同期している場合はブランチの指定も出来ます。
        "scm_branch": "master",

“playbook”ではAWXに同期されたplaybookのパスを指定します。
実行時に実際動作するplaybookの指定となります。
“project”では同期済みのプロジェクトを指定します。
プロジェクトが同期されているかどうかは左側のプロジェクトから確認できます。