はじめに
お久しぶりです。たそ(taso_int)です。
そう言えば、ネスぺを申し込みました。受けるからには受かる気で取り組みます。
あとは前回今年の目標にしてたところも触り始めてます。継続できれば…
今日はAnsible Automation Controller の REST APIについて触ります。
Ansible Automation ControllerはREST APIに対応しており、ジョブの起動などが出来たりします。
REST APIに対応しているおかげでAnsible Automation Controllerの操作設定ができるAnsibleのコレクションがあったりします。
環境
- OS RHEL8.9
- インスタンス m5.large
- SG (少なくとも22 443 許可)
AAP
- バージョン2.4(RHEL8用)
インストール方法はこちら
今回はAWSのEC2でAPIを実行しています。
Windows環境の場合はPostmanやWSLで行った方がいいです。
また出力を見やすくするためにjqコマンドを使えるようにしておくとよいです。
curl実行文 | jq . でJsonフォーマットとして出力してくれます。
参考情報
恐らく、上がRed Hatが提供しているリファレンスで2つ目がコミュニティのリファレンスのような気がしています。
わかる方いたら教えてください。
またhttps://controller_url/api/でも確認することが可能です。
下準備
APIを実行する際に認証用のTokenが必要になるので生成します。
アクセス→ユーザー→ユーザーを指定(今回はadmin)→トークンの順でクリックし、作成をします。
範囲は書き込みを指定して作成します。
そうするとToken情報が出るのでこれをメモリます。再表示はされないので注意してください。
以下の画像のようにトークンの一覧にパーソナルアクセストークンが出ていれば問題ないです。
今回はトークンを認証情報としてますが、ユーザーとパスワードによるBasic認証でも実行可能です。
実際に触る
ベース
curlでの実行の場合、基本的に以下のような構造になります。
-k オプションを入れているのはAnsible Automation Controller側がデフォルトのインストールだと自己証明書を設定してしまうためSSL証明書の検証を無視します。
curl -k -X HTTPメソッド \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 生成したtoken" \
https://controller_url/api/v2/hoge
例えば/api/v2を実行するとAPIのリストが出ます。
今回はジョブ(ジョブテンプレート)の起動と結果確認と結果のデバッグまでを書きます。
次回はジョブ(ワークフロー)の起動と結果確認と失敗したジョブの特定までを書きます。
ジョブの起動
試しにジョブテンプレートのDemo Job Templateを起動させてみます。
ジョブテンプレートを起動する際に各ジョブに割り振られているIDが必要になります。
このIDを知るには直接GUIで知りたいジョブテンプレートを開くとURLにIDが含まれています。
APIのみで完結させたい場合はapi/v2/job_templates/?search=ジョブ名でIDを調べることができます。
Demo Job Templateの場合は以下のような表記になります。
curl -k -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 生成したtoken" \
https://controller_url/api/v2/job_templates/?search=Demo+Job+Template
# 抜粋 "results": [ { "id": 7, "type": "job_template", "url": "/api/v2/job_templates/7/", "related": { "created_by": "/api/v2/users/1/", "modified_by": "/api/v2/users/1/", "labels": "/api/v2/job_templates/7/labels/", "inventory": "/api/v2/inventories/1/", "project": "/api/v2/projects/6/", "organization": "/api/v2/organizations/1/", "credentials": "/api/v2/job_templates/7/credentials/", "last_job": "/api/v2/jobs/3/", "jobs": "/api/v2/job_templates/7/jobs/", "schedules": "/api/v2/job_templates/7/schedules/", "activity_stream": "/api/v2/job_templates/7/activity_stream/", "launch": "/api/v2/job_templates/7/launch/", }
IDがわかったので、実際にジョブテンプレートを起動させます。
エンドポイントはapi/v2/job_templates/id/launch/になります。
ここでのレスポンスとして返ってくるIDがテンプレートの実行履歴のID(以降、ジョブID)となり、これを使用してジョブの結果を調べます。
curl -k -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 生成したtoken" \
https://controller_url/api/v2/job_templates/7/launch
# 抜粋 { "job": 76, "ignored_fields": {}, "id": 76, "type": "job", "url": "/api/v2/jobs/76/", "related": { "created_by": "/api/v2/users/1/", "modified_by": "/api/v2/users/1/", "labels": "/api/v2/jobs/76/labels/", "inventory": "/api/v2/inventories/1/", "project": "/api/v2/projects/6/", "organization": "/api/v2/organizations/1/", "credentials": "/api/v2/jobs/76/credentials/", "unified_job_template": "/api/v2/job_templates/7/", "stdout": "/api/v2/jobs/76/stdout/", "job_events": "/api/v2/jobs/76/job_events/", "job_host_summaries": "/api/v2/jobs/76/job_host_summaries/", "activity_stream": "/api/v2/jobs/76/activity_stream/", "notifications": "/api/v2/jobs/76/notifications/", "create_schedule": "/api/v2/jobs/76/create_schedule/", "job_template": "/api/v2/job_templates/7/", "cancel": "/api/v2/jobs/76/cancel/", "relaunch": "/api/v2/jobs/76/relaunch/" }
実際にGUIでも実行されていることがわかりました。画面上の数字とジョブIDが一致していますね。
ジョブの確認
このAPIは起動するだけなので、実際の結果は別で確認することが必要です。
結果のエンドポイントはapi/v2/jobs/id/になります。このIDはジョブIDを指します。
curl -k -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 生成したtoken" \
https://controller_url/api/v2/jobs/76/
# 抜粋 "launch_type": "manual", "status": "successful", "execution_environment": 2, "failed": false, "started": "2024-02-18T12:53:27.139004Z", "finished": "2024-02-18T12:53:30.991682Z",
ここでstatusがsuccessfulかつfailedがTrueであれば成功になります。
statusがrunningであれば実行中でfailedであれば失敗になります。
ジョブの標準出力
ここまででジョブ(ジョブテンプレート)の起動と結果確認がわかりました。
念のため起動したジョブの標準出力を確認します。
エンドポイントはapi/v2/jobs/id/stdoutでテキストフォーマットにしたいので、?format=txtを追加します。
curl -k -X GET \
-H "Authorization: Bearer 生成したtoken" \
https://controller_url/api/v2/jobs/76/stdout/?format=txt
PLAY [Hello World Sample] ******************************************************
TASK [Gathering Facts] *********************************************************
ok: [localhost]
TASK [Hello Message] ***********************************************************
ok: [localhost] => {
"msg": "Hello World!"
}
PLAY RECAP *********************************************************************
localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
見覚えのある標準出力が出ましたね。これでAPIでも実行から結果確認ができます。
最後に
今回はAPIを使ってジョブ(ジョブテンプレート)の起動と結果確認とジョブの標準出力をしました。
次はテンプレートの集合であるWFの方も紹介します。
ここまで読んでいただきありがとうございました。
