【AWX Operator】REST API完全解説: ジョブテンプレートの操作と応用スクリプト

# はじめに
本記事では、AWX Operatorで管理しているジョブテンプレートをREST APIを利用して操作する方法を解説します。
手動操作を自動化したい方、スクリプトを使ってAWXをより活用したい方に向けた実践的な内容です。具体的なコマンド例や応用的な設定方法も併せてご紹介します。

# この記事でわかること
* REST APIを使ったジョブテンプレートの操作方法
* チェックモードや実行モードなどの基本的なAPIリクエスト例
* 環境変数やextra_varsを活用した高度な操作例
* インベントリや制限指定などの応用的な使い方


# リクエストフロー図
ジョブテンプレートを実行する際の基本的なリクエスト順序を以下に示します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3588696/8232ee9d-7e1d-a8ee-e0d9-ccc8ba6f5331.png)

AWXのREST APIリファレンスはこちらにまとまっていますので、あわせてご参照ください。

https://ansible.readthedocs.io/projects/awx/en/latest/rest_api/api_ref.html

# 事前準備

AWXのジョブテンプレート操作をREST APIで行うには、以下の情報が必要です。

- **Base URL**: AWXサーバーのURL
- **APIトークン**: 認証用のトークン
- **ジョブテンプレートID**: 操作対象のジョブテンプレート


これらは環境変数として定義しておくと、コマンド実行時に便利です。
トークンベース認証の詳細については以下のドキュメントをご参照ください。

https://docs.ansible.com/ansible-tower/latest/html/administration/oauth2_token_auth.html

# 環境変数定義例

```yaml
export AWX_BASE_URL="<BASE_URL>"
export API_TOKEN="<TOKEN>"
export JOB_TEMPLATE_ID="your_job_template_id"
```

# ジョブテンプレート操作
:::note info
ジョブテンプレートを操作する際には、「ジョブテンプレートID」が必要です。
#### ジョブテンプレートIDの確認方法
* ジョブテンプレート名をクリックして詳細を開きます。
  * URLの最後に表示されている数字が、ジョブテンプレートのIDです。
  * 例: https://awx-server-url.com/templates/job_template/12/ → **ID: 12**
:::

## チェックモードで実行する
以下のコマンドで、ジョブテンプレートを「チェックモード（dry run）」で実行できます。
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "job_type": "check"
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```

## 実行モードでジョブを実行する
以下のコマンドで、ジョブテンプレートを実際に実行できます。
```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "job_type": "run"
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```
:::note info
チェック or 実行の制御は"job_type"を指定します。基本的には、-dオプションでJSONデータにパラメータを付与します。
* check: チェックモード（デプロイ前の検証）
* run: 実行モード

:::

## extra_vars を使用して変数を指定して実行
`extra_vars`を使うことで、ジョブに必要な設定値やパラメータを動的に指定できます。

```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "extra_vars": {
            "some_var": "some_value"
        },
        "job_type": "run"
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```

## （応用）シェル変数指定で実行
以下の例では、環境やバージョンを動的に指定してジョブを実行しています。

```bash
export ENVIRONMENT="staging"
export TARGET_HOSTS="web-servers"
export DEPLOY_VERSION="v1.2.3"

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "extra_vars": {
          "environment": "'"${ENVIRONMENT}"'",
          "target_hosts": "'"${TARGET_HOSTS}"'",
          "deploy_version": "'"${DEPLOY_VERSION}"'"
        },
        "job_type": "run"
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```

## 変数／制限（limit）指定で実行

```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "extra_vars": {
            "some_var": "some_value"
        },
         "job_type": "run",
         "limit": "target_host_or_group"
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```

## （応用）変数／正規表現制限指定で実行
`limitパラメータを使うことで、特定のホスト（例: WEB-1011からWEB-1029）に限定してジョブを実行できます。
```bash
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "extra_vars": {
            "some_var": "some_value"
        },
      "limit": "WEB-101[1-9]*:WEB-102[0-9]*"
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```

## インベントリ／変数／制限指定で実行

```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "extra_vars": {
            "some_var": "some_value"
        },
        "job_type": "run",
        "limit": "target_host_or_group",
        "inventory": 12345
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```
:::note info
インベントリ指定にはインベントリ"ID"が必要です。
#### インベントリIDの確認方法
* インベントリ名をクリックして詳細を開きます。
  * URLの最後に表示されている数字が、インベントリのIDです。
  * 例: https://awx-server-url.com/inventories/inventory/5/ → **ID: 5**

:::

## （応用）デバックモードでインベントリ／変数／制限指定で実行

```bash
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "extra_vars": {
            "some_var": "some_value"
        },
        "job_type": "run",
        "limit": "target_host_or_group",
        "inventory": 12345,
        "verbosity": 4
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/
```

:::note info
verbosityフィールドを追加して詳細なログ出力を有効にします。通常、デバッグレベルの詳細度を得るためには、verbosityを"3"以上に設定します。
:::

## ジョブ実行詳細情報の取得

```bash
curl -s -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  $AWX_BASE_URL/api/v2/jobs/$JOB_ID/
```

:::note info
ジョブ"ID"が必要です。ジョブテンプレート実行後にレスポンスが返ってくるため、レスポンスの中からジョブ"ID"を確認します。
:::


## （応用）ジョブ実行ステータスのみ取得
### ジョブテンプレートを実行し、ジョブIDを取得する例
以下のスクリプトでは、ジョブテンプレートを実行し、レスポンスからジョブIDを取得します。
```bash
response=$(curl -s -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "job_type": "run",
        "extra_vars": {
          "commit_hash": "'"${COMMIT_HASH}"'",
          "github_token": "'"${GITHUB_TOKEN}"'",
          "app_pool_name": "'"${APP_POOL_NAME}"'"
        }
      }' \
  $AWX_BASE_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/)
  
job_id=$(echo $response | jq -r '.job')
echo "Job ID: $job_id"
  
Job ID: 368 ⭐️ジョブIDを取得
```

### ジョブステータスのみ取得

```bash
response=$(curl -s -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  $AWX_BASE_URL/api/v2/jobs/$job_id/)
  
job_status=$(echo $response | jq -r '.status')
echo "Job Status: $job_status"
Job Status: running　⭐️出力結果

```

# Pythonを使ったジョブ実行とステータス確認
Pythonを使えば、ジョブの実行とステータス確認を簡単にスクリプト化できます。

```python
import requests

# 環境設定
AWX_BASE_URL = "https://awx.example.com"
API_TOKEN = "your_api_token"
JOB_TEMPLATE_ID = "your_job_template_id"

# ヘッダー設定
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# ジョブを実行
response = requests.post(
    f"{AWX_BASE_URL}/api/v2/job_templates/{JOB_TEMPLATE_ID}/launch/",
    headers=headers,
    json={
        "extra_vars": {"some_var": "some_value"},
        "job_type": "run"
    }
)

if response.status_code == 201:  # 正常終了
    job_id = response.json().get("job")
    print(f"ジョブID: {job_id}")
else:
    print(f"ジョブ実行失敗: {response.status_code}, {response.text}")
    exit()

# ジョブステータスを確認
status_response = requests.get(
    f"{AWX_BASE_URL}/api/v2/jobs/{job_id}/",
    headers=headers
)

if status_response.status_code == 200:
    print(f"ジョブステータス: {status_response.json().get('status')}")
else:
    print(f"ステータス取得失敗: {status_response.status_code}, {status_response.text}")
```

# まとめ
今回、AWX OperatorのREST APIを使ったジョブテンプレート操作の方法を解説しました。
REST APIを活用することで、AWX Operatorのジョブテンプレート操作を効率化できます。
例えば、環境変数やPythonスクリプトを活用することで、ジョブの柔軟な制御や自動化が可能です。また、インベントリや制限指定などの応用例を用いれば、より精密なデプロイ作業が実現できます。

さらに、今回ご紹介したAPI操作の応用例として、GitOpsを活用したリリース自動化の事例があります。具体的には、AWX Operatorを用いてASPアプリケーションのリリースを自動化した取り組みについて、以下の記事で詳しく紹介しています。

https://techblog.zozo.com/entry/asp-auto-deploy-implementation-first-part

https://techblog.zozo.com/entry/asp-auto-deploy-implementation-second-part

これらをヒントに、REST APIを活用した効率的な運用や、自動化の可能性を広げる取り組みにぜひお役立てください。

# 参考資料

https://forum.ansible.com/tag/awx

https://github.com/ansible/awx-operator

https://www.dbi-services.com/blog/how-to-use-awx-rest-api-to-execute-jobs/