はじめに

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

この記事でわかること

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

リクエストフロー図

ジョブテンプレートを実行する際の基本的なリクエスト順序を以下に示します。

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

事前準備

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

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

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

環境変数定義例

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

ジョブテンプレート操作

ジョブテンプレートを操作する際には、「ジョブテンプレートID」が必要です。

ジョブテンプレートIDの確認方法

ジョブテンプレート名をクリックして詳細を開きます。
- URLの最後に表示されている数字が、ジョブテンプレートのIDです。
- 例: https://awx-server-url.com/templates/job_template/12/ → ID: 12

チェックモードで実行する

以下のコマンドで、ジョブテンプレートを「チェックモード（dry run）」で実行できます。

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/

実行モードでジョブを実行する

以下のコマンドで、ジョブテンプレートを実際に実行できます。

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/

チェック or 実行の制御は"job_type"を指定します。基本的には、-dオプションでJSONデータにパラメータを付与します。

check: チェックモード（デプロイ前の検証）
run: 実行モード

extra_vars を使用して変数を指定して実行

extra_varsを使うことで、ジョブに必要な設定値やパラメータを動的に指定できます。

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/

（応用）シェル変数指定で実行

以下の例では、環境やバージョンを動的に指定してジョブを実行しています。

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）指定で実行

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）に限定してジョブを実行できます。

  -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/

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

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/

インベントリ指定にはインベントリ"ID"が必要です。

インベントリIDの確認方法

インベントリ名をクリックして詳細を開きます。
- URLの最後に表示されている数字が、インベントリのIDです。
- 例: https://awx-server-url.com/inventories/inventory/5/ → ID: 5

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

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/

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

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

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

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

（応用）ジョブ実行ステータスのみ取得

ジョブテンプレートを実行し、ジョブIDを取得する例

以下のスクリプトでは、ジョブテンプレートを実行し、レスポンスからジョブIDを取得します。

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を取得

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

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を使えば、ジョブの実行とステータス確認を簡単にスクリプト化できます。

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アプリケーションのリリースを自動化した取り組みについて、以下の記事で詳しく紹介しています。

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

参考資料