はじめに
本記事では、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を活用した効率的な運用や、自動化の可能性を広げる取り組みにぜひお役立てください。
参考資料